Authoring Skills

Authoring skills

This is the skill factory: it turns a capability description into a production-ready skill directory that any runtime can use. It encodes the open spec and the authoring best-practices so the output is correct by construction.

Use this when

• Asked to create / scaffold / package a new skill.
• You notice a repeated procedure worth capturing (the "I keep re-explaining this" signal).
• Skip if an existing skill already covers the capability, extend it, don't fork.

Evaluation-driven authoring (do this order)

- [ ] 1 GAP     run the task WITHOUT a skill; note what context/steps were missing
- [ ] 2 EVALS   write >=3 concrete eval scenarios that capture those gaps (before docs!)
- [ ] 3 FRAME   one capability, one cell of the taxonomy; name it (gerund, [a-z0-9-])
- [ ] 4 DESCRIBE write the what+when description (third person, trigger keywords, 
description: 
license:             # optional but recommended
metadata:                             # optional
  author: 
  version: "1.0"
  tier: ""
  layer: /
compatibility:    # optional
# allowed-tools: 
---

Body rules the factory enforces

1. One responsibility. If the description needs "and also," split into two skills.
2. Concise; assume intelligence. Only context the model lacks. Cut anything it knows.
3. Open with "use this when / not when." Drives correct activation (docs/07).
4. Degrees of freedom matched to fragility: high (text) for judgment tasks, low (exact

script/command) for fragile/irreversible ones.

1. Progressive disclosure: body = table of contents; detail in references, one level deep.
2. No time-sensitive info, consistent terms, concrete examples, forward-slash paths.
3. Scripts solve, don't punt; no magic constants; declare dependencies.

Portability contract (every emitted skill obeys)

• Reference capabilities ("read a file", "run the tests"), never specific tool names in

required steps.

• Forward-slash paths only. Declare real requirements in compatibility; assume nothing else.
• Include a short "Runtime adaptation" section: the minimum mechanisms needed and the

graceful fallback when richer ones (subagents, hooks, compaction) are absent.

• allowed-tools only when genuinely needed; treat as experimental.

Output layout the factory produces

/
├── SKILL.md
├── references.md        (depth, loaded on demand)
├── examples.md          (concrete input/output pairs)
├── templates/           (fill-in artifacts the skill uses)
├── checklists/          (gates the skill references)
└── benchmarks/          (>=3 eval scenarios + metrics, from step 2)

Use templates/skill-skeleton/ as the starting structure and templates/SKILL.md.tpl for the body.

Runtime adaptation

• Minimum: filesystem write. Validate names with the spec rules (and `skills-ref

validate` if available).

• The factory is itself portable: it emits plain files, no runtime-specific assumptions.

Files

• references.md, the spec + best-practices distilled to authoring rules.
• examples.md, a capability turned into a full skill, start to finish.
• templates/SKILL.md.tpl, body template.
• templates/skill-skeleton/, the directory skeleton to copy.
• checklists/authoring.md, the pre-ship gate (mirrors Anthropic's checklist + portability).
• benchmarks/, does the generated skill pass its own evals & the audit?

Source & license

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

• Author: AdrianParedez
• Source: AdrianParedez/capability-fabric
• License: Apache-2.0
• Homepage: https://paredez.dev

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