authoring

# 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, decla