nledford/engineering-review-board / skills/create-agent-skill
create-agent-skill
VerifiedCreate or improve reusable agent skills. Use when the user asks to create a new skill, update an existing skill, define skill instructions, scaffold a SKILL.md-based skill directory, validate skill structure, or turn repeated agent workflows into a global or project skill. Do not use for ordinary documentation edits, application implementation, or ignored third-party runtime skills.
Create Agent Skill
This skill helps create concise, maintainable agent skills that future agents can reliably use. Treat a skill as reusable operating instructions for a recurring task, not as a transcript of one solution.
Workflow
-
Clarify the goal only as much as needed.
- Identify the task the skill should help agents perform.
- Ask for missing requirements only when a reasonable default would be risky.
- Infer defaults when the user has already provided the purpose, scope, target location, or examples.
- State assumptions briefly before implementing them.
-
Inspect local conventions before writing.
- Look for existing skills in the requested skill root, commonly
~/.agents/skillsfor global agent skills. - Follow the target repository's ownership policy before editing a repository skill. Use tracked and ignored status, repository instructions, lockfiles, and other local evidence to distinguish source from runtime installs. Leave ownership unresolved when the available evidence is ambiguous.
- Match the local file names, frontmatter style, optional metadata, resource folders, and validation tools already in use.
- Do not invent a different skill format when a local convention exists.
- Load
documentation-engineeringfor skill-document quality. For a requested or final review, also loadcode-reviewandreview-verification-protocol.
- Look for existing skills in the requested skill root, commonly
-
Define the skill contract.
- Name the users, tasks, inputs, outputs, and success criteria.
- List activation triggers: user phrases, file types, domains, tools, or workflows that should load the skill.
- List non-goals so the skill does not silently expand into unrelated work.
- Decide whether optional
scripts/,references/, orassets/resources are genuinely useful. Do not add empty or placeholder resource folders.
-
Choose the directory name.
- Use lowercase letters, digits, and hyphens only.
- Prefer short, verb-led names such as
create-agent-skill,fix-ci-checks, orsummarize-incident. - Keep the folder name and frontmatter
nameidentical. - Avoid vague names such as
helper,workflow, orassistant.
-
Write the skill.
- Put required trigger information in the frontmatter
description; the body loads only after the skill is selected. - Keep the body procedural and reusable. Prefer checklists, decision rules, and compact examples over long explanations.
- Use imperative instructions that tell the agent what to do.
- Include constraints, assumptions, and non-goals when they affect behavior.
- Include examples only when they clarify activation, output quality, or common mistakes.
- Avoid project-local paths, private repository assumptions, secrets, personal names, or one-off details unless the user explicitly wants a private local skill.
- Put required trigger information in the frontmatter
-
Validate and refine.
- Confirm the required files exist and the directory lives in the requested skill root.
- Confirm frontmatter parses as YAML and includes at least
nameanddescription. - Confirm the
descriptionexplains both what the skill does and when it should activate. - Confirm first-party resource files are linked from
SKILL.md, local Markdown links resolve, and there are no draft placeholders, stale examples, or unnecessary files. - Run any local validator or skill CLI if available. If not, perform a manual structure and content review.
- Test the skill mentally against at least two realistic user requests: one that should trigger it and one that should not.
Minimal Structure
Follow the local convention if it differs, but a simple SKILL.md-based skill usually looks like this:
skill-name/
`-- SKILL.md
Use this frontmatter pattern unless the local format requires additional fields:
---
name: skill-name
description: What the skill helps with. Use when the user asks for specific trigger scenarios, task types, file types, or workflows.
---
Add optional resources only when they carry reusable value:
skill-name/
|-- SKILL.md
|-- scripts/ # deterministic commands or helpers the agent can run
|-- references/ # detailed docs loaded only when needed
`-- assets/ # templates or files used in generated output
Instruction Quality Rules
- Make instructions specific enough to guide behavior, but not so narrow that they only solve one prompt.
- Prefer "inspect existing files before editing" over "always use file X" unless the file is guaranteed by the skill.
- Prefer "ask if the target system is unknown" over asking for every detail up front.
- Use examples to distinguish good and bad behavior, not to restate the workflow.
- Avoid ambiguous verbs like "handle", "support", or "optimize" unless followed by concrete actions.
- Remove setup history, author notes, release notes, and general README content from the skill.
Good and Bad Patterns
Good description:
description: Create or update GitHub pull request review responses. Use when the user asks to address review comments, inspect unresolved PR threads, implement requested changes, or summarize reviewer feedback.
Bad description:
description: Helps with GitHub.
Good workflow instruction:
1. Fetch the PR metadata and unresolved review threads.
2. Separate actionable code-change requests from discussion-only comments.
3. Implement the smallest change that satisfies each actionable thread.
4. Run the relevant tests and summarize unresolved risks.
Bad workflow instruction:
Do a great job and make the PR better.
Good scope control:
Do not rewrite unrelated modules while addressing review comments unless the review specifically requires it.
Bad scope control:
Improve anything that looks wrong.
Maintenance Checklist
Before finishing a new or updated skill, verify:
- The skill name, folder name, and frontmatter
namematch. - The frontmatter
descriptioncontains activation guidance. - The body is concise, procedural, and free of one-off context.
- Project names, modules, paths, recipes, frameworks, and validation commands come from target-repository evidence; examples use portable placeholders and do not encode source-project or machine-local assumptions.
- Optional resources are referenced from
SKILL.mdand are actually needed. - Examples are realistic and transferable.
- Constraints and non-goals are explicit where they prevent misuse.
- The skill can be understood by a future agent without reading this creation conversation.
- Repository-maintained inventory or routing docs are updated when they exist and the skill set changes.
- Repository-specific review and validation guidance has been applied when working on first-party skills.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |