authoring-agent-skills

Creates well-structured skills for this harness. Upstream port: concepts from mattpocock write-a-skill are folded in here so one meta-skill stays canonical for Agent Forge.

When to Use

• Creating a new repeatable workflow or tool as a skill
• Explaining how description: in YAML routes agents to the right skill
• Deciding whether logic belongs in markdown steps vs scripts/*.ts

Process

1. Gather requirements — task/domain, main use cases, scripts vs docs only, any reference material to bundle.
2. Draft — SKILL.md first; add references/ or scripts/ only when needed.
3. Review — use the checklist in references/AUTHORING-GUIDE.md.

Skill anatomy

A skill lives in .claude/skills/<name>/:

Piece	Role
SKILL.md	Required instructions and entrypoint
references/	Optional deep docs (progressive disclosure)
scripts/	Optional Bun TypeScript; emit JSON per AGENTS.md

SKILL.md frontmatter

---
name: <skill-name>
description: <one line + Use when … triggers>
---

See Description field and checklist in references/AUTHORING-GUIDE.md.

Harness conventions

1. Single responsibility per skill.
2. Numbered steps with exact commands where possible.
3. Scripts return structured JSON (ok, data, error).
4. Idempotent scripts when reruns are likely.
5. Tracked work uses Beads (bd), not TODO files or TODO comments.
6. Ship self-contained — never depend on repos/. repos/ holds cloned sub-repos and is gitignored, so anything under it is absent for other users. A command or skill must not reference repos/skills/... (or any other repos/<x> dependency) as something it needs to read. Vendor a copy into the harness (e.g. .claude/skills/<name>/) and reference that. Referring to repos/<repo>/ as the runtime location of the user's own sub-repos (e.g. bun run repo refresh --repo <name>, repos/repos.json) is fine — that is user data, not a harness dependency.

Scaffold

Creates .claude/skills/<name>/ with SKILL.md, scripts/, and references/:

bun run .claude/skills/authoring-agent-skills/scripts/scaffold.ts <skill-name> "<description>"

Use a slug for <skill-name> (kebab-case, matches name: in frontmatter).

Long-form template and split-file guidance

references/AUTHORING-GUIDE.md — full template, description examples, when to script vs split, review checklist.