Authoring Skill Content

Overview

Guide the authoring of effective SKILL.md files, agent definitions (

agents/*.md

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:

skill-inventory

scaffold-output

skill-md

optimization-spec

When the target is an agent definition (

agents/*.md

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 — if the skill references MCP tools or CLI commands, read

   references/skill-writing-guide.md

   "External Tool References" section for declaration syntax, fallback patterns, and CLI vs MCP guidance
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

references/

references/skill-writing-guide.md

bundles-forge audit-skill

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