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 ` on each authored/modified skill

• If audit script is unavailable: review against references/quality-checklist.md manually

1. Act on findings — fix Critical immediately, fix Warning if straightforward, report Info as suggestions
2. 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: OdradekAI
• Source: OdradekAI/bundles-forge
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.