From 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 URL list), storing them in references/, and keeping them current with an auto-update script plus freshness metadata. Covers the naming taxonomy (working-with-X / developing-X / topic skills), SKILL.md frontmatter, the doc-fetching cookbook, the doc-frontmatter.cjs freshness helpers, the Makefile/CI auto-discovery, and the registration checklist. Invoke on "create a skill", "add a working-with-X skill", "wrap these docs in a skill", "write an auto-update script", "add freshness metadata", or "add a skill to this repo".
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-skills:authoring-agent-skillsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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:
skill-creator (or superpowers:writing-skills) for generic skill quality — description wording, triggering accuracy, progressive disclosure, evals.doc-frontmatter.cjs helper, 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.
skills/ in this repo.working-with-X skill with an auto-update script.source/fetched_at/sha256, metadata.last_updated).| 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 |
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 |
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 in scripts/ 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 matching working-with-X for official docs.agent-instructions, domain-driven-design, web-research, git-github-workflows. Hand-written references/, no fetch script.This skill itself is a topic skill — it wraps no external docs and ships no fetch script.
Track these with TodoWrite when building a real skill.
name: in frontmatter. See naming-and-structure.SKILL.md. Frontmatter (name, trigger-rich description, metadata.last_updated) + body (overview, when-to-use, quick-reference table pointing at references/, behavioral guidance). Mirror the shape of skills/developing-claude-code-plugins/SKILL.md (workflow-style) or skills/working-with-vercel-ai-sdk/SKILL.md (doc-wrapper style).skills/<name>/scripts/update_docs.js (or update.js/update.sh). Choose a discovery pattern — llms.txt, sitemap, or curated list — from the cookbook. Output to skills/<name>/references/.withFrontmatter + setSkillLastUpdated from scripts/lib/doc-frontmatter.cjs, wrap each written doc, track wrapped.changed, restamp SKILL.md only when something changed. See freshness-metadata.AGENTS.md (Available Skills table + Common Workflows), README.md, add a named update-<name> Makefile target (doc-wrappers only), and bump the plugin version. Full list in registration-checklist.make list-update-scripts (confirm discovery), make update-<name> (doc-wrappers — confirm it fetches and stamps), and check that every references/*.md path the SKILL.md links to actually exists.skills/working-with-vercel-ai-sdk/ (scripts/update_docs.js)skills/working-with-claude-code/ (scripts/update_docs.js)skills/devcontainers/ (scripts/update.js)developing-X shape (workflow skill) — skills/developing-claude-code-plugins/skills/working-with-pieces/scripts/lib/doc-frontmatter.cjsskill-creator / superpowers:writing-skills — generic skill description quality, triggering, and progressive disclosure.marketplace-publishing — version bump rules and official-marketplace submission once the skill is registered.AGENTS.md ("Auto-generated docs convention" and "Freshness metadata convention").npx claudepluginhub joeblackwaslike/agent-marketplace --plugin agent-skillsProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.