authoring-agent-skills
Use when creating, adding, or maintaining a skill in this agent-skills repo — especially a "working-with-X" skill that wraps external/official docs by fetching them (llms.txt, sitemap, or a curated UR
SKILL.mdskills/authoring-agent-skills/SKILL.md
GitHubAuthoring Agent Skills
Overview
This skill encodes this repo's conventions for building skills — the patterns that have worked well across ~20 existing skills. It is the playbook for adding a new skill that an agent can follow end-to-end without reverse-engineering the existing ones.
It is repo-specific and complements the generic skill tooling rather than replacing it:
- Use
skill-creator(orsuperpowers:writing-skills) for generic skill quality — description wording, triggering accuracy, progressive disclosure, evals. - Use this skill for the agent-skills conventions — naming taxonomy, the doc-fetching + freshness pipeline, the shared
doc-frontmatter.cjshelper, Makefile/CI auto-discovery, and what to update when registering a new skill.
The biggest, most distinctive convention here is the doc-wrapping working-with-X skill: fetch a tool's official docs into references/, stamp each file with source/fetched_at/sha256, and let a weekly GitHub Action keep them current. If that's what you're building, the doc-fetching cookbook and freshness metadata references are the heart of the job.
When to use
- Creating any new skill in
skills/in this repo. - Specifically wrapping an external tool/library's docs into a
working-with-Xskill with an auto-update script. - Adding or fixing freshness metadata (
source/fetched_at/sha256,metadata.last_updated). - Registering a skill (AGENTS.md table, README, Makefile target, version bump).
- Deciding which archetype a new skill should be and how to name it.
Quick reference
| Need to… | Read this |
|---|---|
| Pick an archetype, name the skill, lay out the directory, write SKILL.md frontmatter | references/naming-and-structure.md |
| Write the auto-update fetch script (llms.txt / sitemap / curated-list patterns) | references/doc-fetching-cookbook.md |
| Wrap a locally-installed tool (not just a hosted API/library) — live inspection, event schemas, retention limits | references/local-tool-inspection.md |
Wire freshness signals (doc-frontmatter.cjs API, change-detection, backfill) |
references/freshness-metadata.md |
| Register the skill so it's discoverable and shippable | references/registration-checklist.md |
Naming taxonomy (the short version)
Three archetypes — pick the one that matches the skill's job. Full detail, directory layouts, and frontmatter spec are in references/naming-and-structure.md.
working-with-X— wraps the external/official docs for a tool or library X (Claude Code, Codex, the Vercel AI SDK, GitHub Actions).references/is auto-fetched by a script inscripts/and carries per-doc freshness frontmatter. This is the archetype the fetch/freshness pipeline is built for.developing-X— the workflow/lifecycle for building plugins or extensions for platform X (developing Claude Code / Codex / Cursor / Gemini plugins).references/is hand-written (patterns, structure, troubleshooting), no fetch script. Cross-references the matchingworking-with-Xfor official docs.- Topic / capability skills — a domain or capability, not a single tool:
agent-instructions,domain-driven-design,web-research,git-github-workflows. Hand-writtenreferences/, no fetch script.
This skill itself is a topic skill — it wraps no external docs and ships no fetch script.
Authoring workflow
Track these with TodoWrite when building a real skill.
- Decide archetype & name. Match one of the three archetypes above. Name = kebab-case, directory name ==
name:in frontmatter. See naming-and-structure. - Scaffold
SKILL.md. Frontmatter (name, trigger-richdescription,metadata.last_updated) + body (overview, when-to-use, quick-reference table pointing atreferences/, behavioral guidance). Mirror the shape ofskills/developing-claude-code-plugins/SKILL.md(workflow-style) orskills/working-with-vercel-ai-sdk/SKILL.md(doc-wrapper style). - (Doc-wrappers only) Write the fetch script.
skills/<name>/scripts/update_docs.js(orupdate.js/update.sh). Choose a discovery pattern — llms.txt, sitemap, or curated list — from the cookbook. Output toskills/<name>/references/. - (Doc-wrappers only) Wire freshness. Import
withFrontmatter+setSkillLastUpdatedfromscripts/lib/doc-frontmatter.cjs, wrap each written doc, trackwrapped.changed, restampSKILL.mdonly when something changed. See freshness-metadata. - Register the skill. Update
AGENTS.md(Available Skills table + Common Workflows),README.md, add a namedupdate-<name>Makefile target (doc-wrappers only), and bump the plugin version. Full list in registration-checklist. - Verify.
make list-update-scripts(confirm discovery),make update-<name>(doc-wrappers — confirm it fetches and stamps), and check that everyreferences/*.mdpath the SKILL.md links to actually exists.
Canonical examples (real paths to copy from)
- Sitemap fetch + slug-collision handling —
skills/working-with-vercel-ai-sdk/(scripts/update_docs.js) - llms.txt fetch —
skills/working-with-claude-code/(scripts/update_docs.js) - Curated list + HTML→Markdown + manifest (ESM) —
skills/devcontainers/(scripts/update.js) developing-Xshape (workflow skill) —skills/developing-claude-code-plugins/- Freshness exception (merged upstreams, hand-curated) —
skills/working-with-pieces/ - Shared freshness helper —
scripts/lib/doc-frontmatter.cjs
Cross-references
skill-creator/superpowers:writing-skills— generic skill description quality, triggering, and progressive disclosure.agent-skills:agent-instructions(references/editing-discipline.md) — RED-GREEN discipline for editing an existingSKILL.mdor runbook, as opposed to authoring a new one.marketplace-publishing— version bump rules and official-marketplace submission once the skill is registered.- Repo conventions also summarized in
AGENTS.md("Auto-generated docs convention" and "Freshness metadata convention").