Authoring Skill Content

Overview

Guide the authoring of effective SKILL.md files, agent definitions (agents/*.md), and supporting resources within a bundle-plugin. Good content is the difference between skills that agents consistently find and follow — and ones that get ignored or misinterpreted.

Core principle: Write for the agent's experience. Every instruction should be discoverable (good description), loadable (right size), and followable (clear, motivated instructions). Skills are the first-class source of truth in a bundle-plugin — docs and README must not contradict skill content (see bundles-forge:auditing — references/source-of-truth-policy.md).

Skill type: Hybrid — follow the execution flow rigidly (Entry Detection → Path steps → Validation), but apply writing guidance flexibly based on context. The process is discipline-enforcing; the content decisions are pattern-based.

Announce at start: "I'm using the authoring skill to help [write / complete / improve / adapt] [skill / agent] content."

Entry Detection

Determine the authoring path from context:

Context	Path
skill-inventory from blueprinting, or user requests writing new SKILL.md / agent definition from scratch	Path 1: New Content
User provides an existing/external skill to add into a project, or asks to adapt a skill to match project conventions	Path 2: Integrate Content
scaffold-output directories exist but SKILL.md body has < 10 non-empty lines	Path 3: Complete Content
User provides existing in-project skill-md to improve, or optimization-spec from optimizing with specific changes	Path 4: Improve Content

When the target is an agent definition (agents/*.md) rather than a skill, follow the same path logic but use the agent authoring conventions from references/agent-authoring-guide.md.

Step 0: Project Context (all paths)

Before writing any content, verify scope and detect the project context:

0. Triage: should this be a skill? — Before writing, verify the content warrants a skill:
   • One-off, project-specific conventions → belongs in CLAUDE.md / AGENTS.md, not a skill
   • Mechanically enforceable constraints (regex, schema validation) → automate with scripts, not documentation
   • Standard practices well-documented by the platform → don't duplicate, cross-reference instead
   • Skip this check when arriving from bundles-forge:blueprinting (triage already done during design)
1. Detect project root — look for skills/ directory + package.json above the target
2. If project exists, read 2-3 existing SKILL.md files to extract the project's conventions:
   • Description style (verb form after "Use when", scoping patterns)
   • Section structure (which headings, in what order)
   • Cross-reference format (project:skill-name prefix)
   • Token efficiency patterns (use of references/, line counts)
3. If no project (standalone authoring), use the conventions from references/skill-writing-guide.md directly

Path 1: New Content

Write skill or agent content from scratch.

1. Gather requirements — from skill-inventory and design document context (blueprinting), user description, or conversation context. Identify: skill purpose, triggering scenarios, expected inputs/outputs, relationship to other skills. When a design document is available, leverage its project overview, target users, and use cases to write more targeted descriptions and overviews
2. Load writing guide — read references/skill-writing-guide.md (frontmatter conventions, description rules, instruction style)
3. Write frontmatter — name (kebab-case matching directory), description (start with "Use when...", under 250 chars, triggering conditions only)
4. Write Overview — 1-3 sentences: what the skill does, core principle, skill type declaration (rigid / flexible / hybrid)
5. Write the process — step-by-step execution flow. Use imperative form. Explain why, not just what. Include at least one concrete example per key instruction
6. Write Common Mistakes — table of pitfalls and fixes (at least 3 entries)
7. Write Inputs / Outputs / Integration — declare artifact IDs, calling relationships, and pairing skills
8. Check external dependencies:
   • Declaration syntax — if the skill references MCP tools or CLI commands, read references/skill-writing-guide.md "External Tool References" section for allowed-tools declaration, fallback patterns, and CLI vs MCP guidance
   • Prerequisites section — if allowed-tools declares external CLI tools (not git, python, node, npm, npx, bash, or paths under bin//scripts/), confirm the body includes a ## Prerequisites section with a Tool/Check/Install table. Read references/skill-writing-guide.md "Prerequisites Writing" for the standard format
9. Evaluate token budget — if body exceeds 300 lines, extract heavy sections to references/. Front-load critical instructions in the first ~5,000 tokens — after context compaction, only this portion survives
10. Run validation (see Post-Action Validation below)

Path 2: Integrate Content

Adapt an existing/external skill to fit a project's conventions and workflow.

1. Read the incoming skill — understand its purpose, triggering scenarios, and current structure
2. Read project conventions (from Step 0) — identify gaps between the incoming skill and project patterns
3. Load writing guide — read references/skill-writing-guide.md (frontmatter conventions, description rules, instruction style)
4. Adapt frontmatter — rewrite description to match project style (verb form, scoping), ensure name follows project kebab-case convention
5. Adapt body structure — restructure sections to match project patterns (Overview, Process, Common Mistakes, Inputs/Outputs/Integration)
6. Wire Integration section — add cross-references to existing project skills, declare Inputs/Outputs that connect to the project's workflow graph
7. Adapt instruction style — align with project conventions (imperative form, reasoning over directives, example density)
8. Evaluate token budget — ensure the adapted skill fits project token norms
9. Run validation (see Post-Action Validation below)

Path 3: Complete Content

Fill in scaffolded skill stubs with substantive content.

1. Read scaffold structure — identify which directories and stub files exist
2. Read project conventions (from Step 0) — match the style of already-completed skills
3. Load writing guide — read references/skill-writing-guide.md (frontmatter conventions, description rules, instruction style)
4. Complete frontmatter — fill in description (triggering conditions, "Use when...", under 250 chars). If name is already set, verify it matches directory name
5. Write Overview — core principle + skill type declaration
6. Write the process — step-by-step flow based on the skill's intended purpose from the design document or user context
7. Write remaining sections — Common Mistakes, Inputs/Outputs/Integration
8. Create supporting resources if needed — references/ for heavy content, assets/ for templates. Read references/skill-writing-guide.md "Supporting Resources" section for thresholds. Front-load critical instructions in the first ~5,000 tokens — after context compaction, only this portion survives
9. Run validation (see Post-Action Validation below)

Path 4: Improve Content

Enhance existing in-project content based on user feedback or optimization specs.

1. Read existing content — understand current structure, strengths, and gaps
2. Identify improvement targets — from user request, optimization-spec, or self-diagnosis:
   • Description not triggering reliably → rewrite following description rules
   • Token budget exceeded → extract to references/, cut redundancy, front-load critical instructions in the first ~5,000 tokens
   • Missing sections → add Overview, Common Mistakes, Inputs/Outputs
   • Instruction style issues → reframe directives as reasoning, add examples
3. Load writing guide if needed — read references/skill-writing-guide.md (frontmatter conventions, description rules, instruction style)
4. Apply changes — make targeted improvements. Preserve what works; don't rewrite content that already follows conventions
5. Verify Integration section — ensure cross-references still resolve after changes, artifact IDs match consuming skills
6. Run validation (see Post-Action Validation below)

Post-Action Validation

After completing any path, validate the authored content:

1. Run lint — bundles-forge audit-skill <skill-directory> on each authored/modified skill
   • If audit script is unavailable: review against references/quality-checklist.md manually
2. Act on findings — fix Critical immediately, fix Warning if straightforward, report Info as suggestions
3. Report results — tell the user/calling skill what was validated and any remaining warnings

Common Mistakes

Mistake	Fix
Description summarizes workflow	Describe triggering conditions only — agents shortcut to description
Piling on MUST/ALWAYS/NEVER	Explain why the rule exists — understanding beats compliance
Putting everything in SKILL.md	Extract heavy content (100+ lines) to references/; keep body under 500 lines
No examples, only abstract rules	Add at least one concrete example per key instruction
Writing for humans, not agents	Use imperative form, clear structure, explicit output formats
Description too narrow	Be pushy — list related scenarios, edge cases, alternative phrasings
Description too broad	Scope to the right context (e.g., "bundle-plugins" not just "any project")
Skipping project conventions	Always read existing skills first when working in an established project
Not wiring Integration section	Every skill needs Called by / Calls / Pairs with to connect to the workflow graph
No defensive instructions for rigid skills	For rigid/hybrid skills, add explicit loophole closers, rationalization tables, and red-flag lists — see Defensive Writing in references/skill-writing-guide.md
Forgetting validation	Always run bundles-forge audit-skill after authoring — catches issues before they propagate

Inputs

• skill-inventory (optional) — list of skills and agent definitions to write, from bundles-forge:blueprinting design document
• scaffold-output (optional) — scaffolded skill directories needing content (from blueprinting pipeline or standalone scaffolding)
• skill-md (optional) — existing SKILL.md or agent definition to improve, complete, or adapt
• optimization-spec (optional) — specific content changes requested by bundles-forge:optimizing (e.g., rewrite description, reduce tokens, restructure sections)

Outputs

• skill-content — completed or improved SKILL.md files following authoring conventions (frontmatter, description, body structure, token efficiency)
• agent-content (optional) — completed agents/*.md definitions following agent authoring conventions

Integration

Called by:

• bundles-forge:blueprinting — dispatched as Phase 2 (content writing) in the blueprinting pipeline (write all skills + agent definitions)
• bundles-forge:optimizing — content rewriting for description, token, and structural improvements
• User directly — for standalone SKILL.md or agent definition authoring

Pairs with:

• bundles-forge:scaffolding — scaffolding generates directory structure, authoring fills it with content
• bundles-forge:auditing — auditing validates authored content for quality, cross-references, and security