Create a New Skill
Author a SKILL.md file that agentic systems can consume to execute a specific procedure.
When to Use
- Codifying a repeatable procedure that agents should follow
- Adding a new capability to the skills library
- Converting a guide, runbook, or checklist into agent-consumable format
- Standardizing a workflow across projects or teams
Inputs
- Required: Task the skill should accomplish
- Required: Domain classification — one of the domains catalogued in
skills/_registry.yml (the registry is the authoritative, current list), e.g.:
r-packages, jigsawr, containerization, reporting, compliance, mcp-integration,
web-dev, git, general, citations, data-serialization, review, bushcraft,
esoteric, design, defensive, project-management, devops, observability, mlops,
workflow-visualization, swarm, morphic, alchemy, tcg, intellectual-property,
gardening, shiny, animal-training, mycology, prospecting, crafting,
library-science, travel, relocation, a2a-protocol, geometry, number-theory,
stochastic-processes, theoretical-science, diffusion, hildegard, maintenance,
blender, visualization, 3d-printing, lapidary, versioning
- Required: Complexity level (basic, intermediate, advanced)
- Optional: Source material (existing guide, runbook, or working example)
- Optional: Related skills to cross-reference
Procedure
Step 1: Create Directory
Each skill lives in its own directory:
mkdir -p skills/<skill-name>/
Naming conventions:
- Use lowercase kebab-case:
submit-to-cran, not SubmitToCRAN
- Start with a verb:
create-, setup-, write-, deploy-, configure-
- Be specific:
create-r-dockerfile not create-dockerfile
Expected: Directory skills/<skill-name>/ exists, and the name follows lowercase kebab-case starting with a verb.
On failure: If the name does not start with a verb, rename the directory. Check for naming conflicts: ls skills/ | grep <keyword> to ensure no existing skill has an overlapping name.
Step 2: Write YAML Frontmatter
---
name: skill-name-here
description: >
One to three sentences plus key activation triggers. Must be clear
enough for an agent to decide whether to activate this skill from
the description alone. Max 1024 characters. Start with a verb.
license: MIT
allowed-tools: Read Write Edit Bash Grep Glob # optional, experimental
metadata:
author: Philipp Thoss
version: "1.0"
domain: general
complexity: intermediate
language: R | TypeScript | Python | Docker | Rust | multi
tags: comma, separated, lowercase, tags
---
Required fields: name, description
Optional fields: license, allowed-tools (experimental), metadata, compatibility
Metadata conventions:
complexity: basic (< 5 steps, no edge cases), intermediate (5-10 steps, some judgment), advanced (10+ steps, significant domain knowledge)language: primary language; use multi for cross-language skillstags: 3-6 tags for discovery; include the domain name
Expected: YAML frontmatter parses without errors, name matches the directory name, and description is under 1024 characters with clear activation triggers.
On failure: Validate YAML by checking for matching --- delimiters, proper quoting of version strings (e.g., "1.0" not 1.0), and correct > multi-line folding syntax for the description field.
Step 3: Write the Title and Introduction
# Skill Title (Imperative Verb Form)
One paragraph: what this skill accomplishes and the value it provides.
The title should match the name but in human-readable form. "Submit to CRAN" not "submit-to-cran".
Expected: A top-level # heading in imperative form followed by a concise paragraph stating what the skill accomplishes.
On failure: If the title reads as a noun phrase rather than a verb phrase, rewrite it. "Package Submission" becomes "Submit to CRAN."
Step 4: Write "When to Use"
List 3-5 trigger conditions — concrete scenarios where an agent should activate this skill:
## When to Use
- Starting a new R package from scratch
- Converting loose R scripts into a package
- Setting up a package skeleton for collaborative development
Write from the agent's perspective. These are the conditions the agent checks to decide activation.
Note: The most important trigger conditions should also appear in the description frontmatter field, since that is read during the discovery phase before the full body is loaded. The ## When to Use section provides additional detail and context.
Expected: 3-5 bullet points describing concrete, observable conditions under which an agent should activate this skill.
On failure: If triggers feel vague ("when something needs to be done"), rewrite from the agent's perspective: what observable state or user request would trigger activation?
Step 5: Write "Inputs"
Separate required from optional. Be specific about types and defaults:
## Inputs
- **Required**: Package name (lowercase, no special characters except `.`)
- **Required**: One-line description of the package purpose
- **Optional**: License type (default: MIT)
- **Optional**: Whether to initialize renv (default: yes)
Expected: Inputs section clearly separates required from optional parameters, each with a type hint and default value where applicable.
On failure: If a parameter's type is ambiguous, add a concrete example in parentheses: "Package name (lowercase, no special characters except .)".
Step 6: Write "Procedure"
This is the core of the skill. Each step follows this pattern:
### Step N: Action Title
Context sentence explaining what this step accomplishes.
\```language
concrete_code("that the agent can execute")
\```
**Expected:** What success looks like. Be specific — file created, output matches pattern, command exits 0.
**On failure:** Recovery steps. Don't just say "fix it" — provide the most common failure cause and its resolution.
Writing effective steps:
- Each step should be independently verifiable
- Include actual code, not pseudocode
- Put the most common path first, edge cases in "On failure"
- 5-10 steps is the sweet spot. Under 5 may be too vague; over 12 should be split into multiple skills.
- Reference real tools and real commands, not abstract descriptions
Writing for translation:
- Target ~400 lines maximum for English skills. German expands 10-20%, and some CJK translations expand further — a 400-line English source stays under 500 after translation.
- Avoid idioms and culturally-specific examples that translate poorly.
- Keep prose concise and direct — shorter sentences translate better.
Expected: Procedure section contains 5-12 numbered steps, each with concrete code, an **Expected:** outcome, and an **On failure:** recovery action.
On failure: If a step lacks code, add the actual command or configuration. If Expected/On failure is missing, write it now — every step that can fail needs both.
Step 7: Write "Validation"
A checklist the agent runs after completing the procedure:
## Validation
- [ ] Criterion 1 (testable, binary pass/fail)
- [ ] Criterion 2
- [ ] No errors or warnings in output
Each item must be objectively verifiable. "Code is clean" is bad. "devtools::check() returns 0 errors" is good.
Expected: A markdown checklist (- [ ]) with 3-8 binary pass/fail criteria that an agent can verify programmatically or by inspection.
On failure: Replace subjective criteria with measurable ones. "Well-documented" becomes "All exported functions have @param, @return, and @examples roxygen tags."
Step 8: Write "Common Pitfalls"
3-6 pitfalls with cause and avoidance:
## Common Pitfalls
- **Pitfall name**: What goes wrong and how to avoid it. Be specific about the symptom and the fix.
Draw from real experience. The best pitfalls are ones that waste significant time and are non-obvious.
The 3-6 cap holds for the life of the skill: when a later evolution wants a seventh pitfall, evolve-skill evicts the pitfall with the lowest rediscovery cost instead of appending past the cap.
Expected: 3-6 pitfalls, each with a bold name, a description of what goes wrong, and how to avoid it.
On failure: If pitfalls feel generic ("be careful with X"), make them specific: name the symptom, the cause, and the fix. Draw from actual failure scenarios encountered during development or testing.
Step 9: Write "Related Skills"
Cross-reference 2-5 skills that are commonly used before, after, or alongside this one:
## Related Skills
- `prerequisite-skill` - must be done before this skill
- `follow-up-skill` - commonly done after this skill
- `alternative-skill` - alternative approach to the same goal
Use the skill name field (kebab-case), not the title.
Expected: 2-5 related skills listed with kebab-case IDs and brief descriptions of the relationship (prerequisite, follow-up, alternative).
On failure: Verify each referenced skill exists: ls skills/<skill-name>/SKILL.md. Remove any references to skills that have been renamed or removed.
Step 10: Add to Registry
Edit skills/_registry.yml and add the new skill under the appropriate domain:
- id: skill-name-here
path: skill-name-here/SKILL.md
complexity: intermediate
language: multi
description: One-line description matching the frontmatter
Update the total_skills count at the top of the registry.
Expected: New entry appears in skills/_registry.yml under the correct domain, and total_skills count matches the actual number of skill directories on disk.
On failure: Count skills on disk with find skills -name SKILL.md | wc -l and compare against total_skills in the registry. Verify the id field matches the directory name exactly.
Step 11: Add Citations (Optional)
If the skill is based on established methodologies, research papers, software packages, or standards, add citation subfiles to the references/ directory:
mkdir -p skills/<skill-name>/references/
Create two files:
references/CITATIONS.bib — Machine-readable BibTeX (source of truth)references/CITATIONS.md — Human-readable rendered references for GitHub browsing
% references/CITATIONS.bib
@article{author2024title,
author = {Author, First and Other, Second},
title = {Paper Title},
journal = {Journal Name},
year = {2024},
doi = {10.xxxx/xxxxx}
}
<!-- references/CITATIONS.md -->
# Citations
References underpinning the **skill-name** skill.
1. Author, F., & Other, S. (2024). *Paper Title*. Journal Name. https://doi.org/10.xxxx/xxxxx
Citations are optional — add them when provenance tracking matters (academic methods, published standards, regulatory frameworks).
Handling references/ in translations: Prose descriptions in references/EXAMPLES.md should be translated. references/CITATIONS.bib stays in English (BibTeX is language-neutral). Translations may symlink to the English references/ directory if its content is code-only.
Expected: Both files exist and .bib parses as valid BibTeX.
On failure: Validate BibTeX syntax with bibtool -d references/CITATIONS.bib or an online validator.
Step 12: Validate Skill
Run local validation checks before committing:
# Check line count (must be ≤500)
lines=$(wc -l < skills/<skill-name>/SKILL.md)
[ "$lines" -le 500 ] && echo "OK ($lines lines)" || echo "FAIL: $lines lines > 500"
# Check required frontmatter fields
head -20 skills/<skill-name>/SKILL.md | grep -q '^name:' && echo "name: OK"
head -20 skills/<skill-name>/SKILL.md | grep -q '^description:' && echo "description: OK"
Expected: Line count ≤500, all required fields present. That flat 500 is the ceiling this repository enforces on i18n mirrors; the English source itself is held to a DERIVED, stricter ceiling once mirrors exist or will exist (node scripts/check-skill-line-ceiling.js <skill-name>, CONTRIBUTING.md § local checks, #855) — a scaffolded translation adds provenance frontmatter on top of English's body, so an English file at exactly 500 lines puts a freshly-scaffolded mirror over its own 500-line limit. Run that script, not the flat check above, before treating an English file near 500 lines as safe.
On failure: If over 500 lines, apply progressive disclosure — extract large code blocks (>15 lines) to references/EXAMPLES.md:
mkdir -p skills/<skill-name>/references/
Move extended code examples, full configuration files, and multi-variant examples to references/EXAMPLES.md. Add cross-reference in SKILL.md: See [EXAMPLES.md](references/EXAMPLES.md) for complete configuration examples. Keep brief inline snippets (3-10 lines) in the main SKILL.md. The CI workflow at .github/workflows/validate-skills.yml enforces these limits on all PRs.
Step 13: Sync Discovery Symlinks
Scope: the maintainer's machine. --fix also writes the global ~/.claude/skills/ hub and removes stale almanac-owned links there. An external contributor commits the one project-level link by hand instead (ln -s ../../skills/<skill-name> .claude/skills/<skill-name>), as CONTRIBUTING.md § Adding a skill says; the script's global half runs on the maintainer's side at merge.
Run the idempotent sync script so Claude Code discovers the skill as a /slash-command at both discovery layers. It reads the registry and ensures every registered skill has its repo-internal relative link and its global absolute link, skipping any that already exist — on this machine, do not hand-roll ln -s per skill:
bash scripts/sync-discovery-symlinks.sh --report # preview drift
bash scripts/sync-discovery-symlinks.sh --fix # create/repair links
Expected: --report prints OK: hub in sync; ls -la .claude/skills/<skill-name>/SKILL.md resolves to the skill file.
On failure: The two links the script creates are .claude/skills/<skill-name> -> ../../skills/<skill-name> (relative, project) and ~/.claude/skills/<skill-name> -> <almanac>/skills/<skill-name> (absolute, global). If discovery still fails, use readlink -f .claude/skills/<skill-name> to debug resolution — Claude Code expects a flat structure at .claude/skills/<name>/SKILL.md. See Symlink Architecture.
Step 14: Scaffold Translations
Required for all skills. This step applies to both human authors and AI agents following this procedure. Do not skip — missing translations accumulate into stale backlog.
Scope: the maintainer's repository, after the English is committed and final. On an external pull request this step is the maintainer's, run once at merge — a scaffold copies the English bytes at the moment it runs, so one made while the PR is still being revised strands every mirror after the next push (#765 finding 2). A contributor leaves this step out; CONTRIBUTING.md § Adding a skill says which steps are theirs.
Scaffold translation files for the four translated locales (de, zh-CN, ja, es) as soon as the English commit is final:
for locale in de zh-CN ja es; do
npm run translate:scaffold -- skills <skill-name> "$locale"
done
Then translate the scaffolded prose in each file (code blocks and IDs stay in English). Finally regenerate the status files:
npm run translation:status
Expected: 4 files created at i18n/{de,zh-CN,ja,es}/skills/<skill-name>/SKILL.md, all with source_commit matching current HEAD. npm run validate:translations shows 0 stale warnings for the new skill.
On failure: If scaffold fails, verify the skill exists in skills/_registry.yml before scaffolding — the script reads the registry. If translation:status shows the new files as stale, check that source_commit matches the commit hash where the English source was last modified.
Step 15: Author a Test Scenario (Coverage)
Do not skip. A new skill with no scenario widens the eval-coverage gap (~2% of skills covered today — tracked in #435). Author a scenario now, or record in the PR why the skill is not scenario-testable.
Create tests/scenarios/skills/test-<skill-name>-<focus>.md from tests/_template.md, with target: <skill-name> and test-level: skill in the frontmatter and all required sections (Objective, Pre-conditions, Task, Expected Behaviors, Acceptance Criteria, Observation Protocol). Increment total_tests in tests/_registry.yml.
npm run coverage:evals # <skill-name> should now appear under "Covered"
Expected: the scenario passes .github/workflows/validate-tests.yml (frontmatter fields, required sections, registry count, target-exists), and npm run coverage:evals lists <skill-name> as covered.
On failure: if the skill genuinely resists a black-box scenario (e.g., a pure meta/self-care skill with no observable output contract), record that decision in the PR rather than forcing a hollow scenario — but authoring one is the default.
Validation
Common Pitfalls
- Missing On failure: Every step that can fail needs recovery guidance. Agents can't improvise — they need the fallback spelled out.
- Overly broad scope: A skill that tries to cover "Set up entire development environment" should be 3-5 focused skills instead. One skill = one procedure.
- Stale cross-references: When renaming or removing skills, grep for the old name in all Related Skills sections.
- Authoring at 500-line limit for single language: An English skill at 490 lines will exceed 500 when translated to German (~10-20% expansion) or CJK languages. Target ~400 lines for the English source and use progressive disclosure (
references/EXAMPLES.md) for the rest.
- Avoid
git mv on NTFS-mounted paths (WSL): On /mnt/ paths, git mv for directories can create broken permissions (d?????????). Use mkdir -p + copy files + git rm the old path instead. See the environment guide troubleshooting section.
- Asserting tool behavior you have not checked: The claim you feel surest about is the one to verify — "the default is X" reads as authoritative, so a wrong one survives review by default. Cite the doc you checked, and prefer a failure you observed over one you believe exists.
Examples
A well-structured skill follows this quality checklist:
- An agent can decide whether to use it from the description alone
- The procedure can be followed mechanically without ambiguity
- Every step has a verifiable outcome
- Failure modes have concrete recovery paths
- The skill can be composed with related skills
Size reference from this library:
- Basic skills: ~80-120 lines (e.g.,
write-vignette, configure-git-repository)
- Intermediate skills: ~120-180 lines (e.g.,
write-testthat-tests, manage-renv-dependencies)
- Advanced skills: ~180-250 lines (e.g.,
submit-to-cran, setup-gxp-r-project)
- Skills with extended examples: SKILL.md ≤500 lines +
references/EXAMPLES.md for large configs
Related Skills
evolve-skill - evolve and refine skills created with this procedurecreate-agent - parallel procedure for creating agent definitionscreate-team - parallel procedure for creating team compositionswrite-claude-md - CLAUDE.md can reference skills for project-specific workflowsconfigure-git-repository - skills should be version-controlledcommit-changes - commit the new skill and its symlinkssecurity-audit-codebase - review skills for accidentally included secrets or credentials- Content Styleguide - canonical markdown formatting for SKILL.md (tables, code fences, headings)