/authoring

name: authoring
description: "Use when writing, completing, improving, or adapting SKILL.md and agents/*.md in a bundle-plugin — integrating external skills, filling scaffolded stubs, or rewriting for better triggering and token efficiency"
allowed-tools: Bash(bundles-forge audit-skill *)

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