create-skill

Standalone Web-only skill. Copy it into Claude, or drop it into your project.

Copy skill Copied to clipboard Download Open Claude.ai

Paste into Claude Code, Claude.ai, the desktop app, or the browser extension — ⌘/Ctrl+V.

ExperimentalNo security review

Create Skill

Scaffold a new Agent Skill that is spec-correct against both Anthropic's open Agent Skills baseline and Claude Code's layered extensions. When the brief is thin, apply the exploration-first intake methodology in references/intake-methodology.md to flesh it out before drafting. Always run the verification gate appropriate to the chosen scope before reporting done.

When this skill applies

• The user asks to "create", "scaffold", "design", "author", "build", or "make" a skill.
• The user describes a repeated workflow or a pasted-instruction pattern they want to capture as a reusable skill.
• The user says "I want a skill that…" or "new SKILL.md".

Skip when the user is modifying an existing skill in place (edit it directly), when they are asking how skills work in general (answer from references/frontmatter-spec.md or point at the upstream URLs), or when they are invoking a different existing skill.

Workflow

1. Intake — apply the exploration-first methodology when the brief is ambiguous. Check the brief for these slots before drafting:

   • target name (kebab-case, lowercase letters/numbers/hyphens only, max 64 chars, cannot contain "anthropic" or "claude")
   • one-paragraph purpose
   • 2–5 trigger phrases (for the description field)
   • skip conditions
   • whether the skill takes arguments and what argument-hint should be (Claude Code modes only)
   • whether disable-model-invocation or user-invocable: false applies (Claude Code modes only)
   • target scope (project / personal / portable — see step 2)
   • copyright-footer choice (whose notice, or none)

   If every slot is present in the brief, skip ahead to step 3. If any slot is missing OR the user is exploring rather than dictating, load references/intake-methodology.md and apply the methodology — ask before answering, surface assumptions, track an insights log, resist solutioning — until the user explicitly signals readiness ("okay, draft it", "let's go", "what would you do?"). Then resume here at step 2 with a complete brief.

2. Confirm scope mode.

   Mode	Path	Frontmatter set	Template
   project	.claude/skills/<name>/	open baseline + Claude Code	assets/SKILL.template.claude-code.md
   personal	~/.claude/skills/<name>/	open baseline + Claude Code	assets/SKILL.template.claude-code.md
   portable	wherever the user specifies	open baseline only	assets/SKILL.template.portable.md

   Portable mode is for skills shipping via the Claude API or claude.ai Projects, where Claude Code-specific frontmatter (when_to_use, argument-hint, allowed-tools, paths, etc.) is ignored or rejected. In portable mode emit ONLY name + description and keep the body to standard markdown.

3. Detect supporting-file signals, suggest, then ask. Scan the brief for these signals before scaffolding subdirs:

   • "large API spec", "reference docs", "specification", "examples library", "RFC", "schema" → suggest references/
   • "script", "Python", "shell", "executable", "automation", "validator" → suggest scripts/
   • "template", "boilerplate", "starter file", "fill-in" → suggest assets/

   Present the detected signals and proposed subdirs in one block; ask the user to confirm or adjust. If no signals fire, default to SKILL.md only. Never scaffold an empty subdir — only create one when at least one file will land in it during this turn.

4. Draft SKILL.md from the appropriate template. Open the template (assets/SKILL.template.claude-code.md for project/personal, assets/SKILL.template.portable.md for portable) and fill in the slots from the intake brief. Apply the frontmatter and body rules below. Write through to the chosen path.

5. Draft supporting files for any subdirs confirmed at step 3. Reference each one from SKILL.md so the model knows what it contains and when to load it.

6. Run the verification gate for the chosen scope (see below). Fix every failure before reporting done.

Frontmatter rules

The full table with constraints and source citations lives in references/frontmatter-spec.md. Load it when an edge case comes up (e.g. paths glob syntax, context: fork agent selection, allowed values for effort). The must-know rules:

• name and description are the only fields the open baseline requires. Everything else is a Claude Code extension and only applies in project/personal mode.
• name: lowercase letters, numbers, hyphens only; max 64 chars; cannot contain XML tags; cannot contain the reserved words "anthropic" or "claude".
• description: non-empty; max 1024 chars on the open baseline. In Claude Code, the combined description + when_to_use is truncated at 1,536 chars in the skill listing.
• Defaults are not re-stated in frontmatter. Don't emit disable-model-invocation: false or user-invocable: true — those are noise.
• Invented fields are forbidden. context: inline is not a valid value (the only documented value for context is fork; inline is the implicit default). allowed-tools takes real tool names like Read, Grep, Bash(git add *) — not strings like file-reading or code-analysis.
• In portable mode, emit ONLY name and description. Any other field is a validation failure.

Body-writing rules

• H1 = the skill's display name.
• Keep the body under ~500 lines. Skill content sits in context every turn — every line is a recurring token cost.
• State what to do, not why or how — well-named sections do that work.
• Move large reference material (API specs, full field tables, examples libraries) to references/*.md so it loads only on demand.
• Reference supporting files from SKILL.md with relative links so the model knows what each contains and when to load it.

Copyright footer

Decide with the user whether to include a copyright notice and, if so, whose. Common patterns: the skill author's name, an employer or organization name, or no footer at all. When included, placement depends on file type:

• SKILL.md and any other markdown file with YAML front matter: HTML-comment block at the very bottom (front matter on top of a header comment would break parsing).
• Markdown reference files without front matter: same HTML-comment block at the bottom.
• scripts/*.sh and scripts/*.py: #-comment header at the top.

Standard block shape (substitute the rights holder and year):

Copyright © <year> <rights holder>. All rights reserved.
Third-party and open source components remain under their respective licenses;
see LICENSE.md for details.

Verification gate

<dir> is the new skill's directory.

The gate runs as manual model-driven checks (read the file back, validate the structure). In a shell-enabled environment, additionally run the tooling commands listed under "Shell-enabled environments" below, but the manual checks remain authoritative when no shell is available.

Manual checks (always run)

• Frontmatter validator: parse the YAML between the --- fences. Verify:
  • name matches ^[a-z0-9-]{1,64}$ and contains neither "anthropic" nor "claude"
  • description is non-empty and ≤ 1024 chars (open-baseline cap)
  • In project/personal mode, the combined description + when_to_use ≤ 1536 chars
  • Every field name is in the allowed list (see references/frontmatter-spec.md)
  • Portable mode is strict: ONLY name and description are allowed; any other field is a failure
  • No XML-like tags (<…>) in name or description. claude.ai rejects skills whose name or description contains anything matching <[^>]+>. The most common slip is angle-bracket placeholders like <name> in description prose — use [name] or rephrase. (The body of SKILL.md can still use <name> freely; the rule applies only to the two YAML fields.)
• Body-length check: SKILL.md is ≤ ~500 lines.
• Supporting-file references: every file scaffolded under references/, scripts/, or assets/ is referenced from SKILL.md so the model knows when to load it.
• Copyright-footer check (when a footer was chosen): the last non-blank line of every markdown file is inside the copyright HTML comment block; any scripts have the #-comment header at the top.
• Forbidden-field-value check: no context: inline, no abstract tool names in allowed-tools, no defaults emitted explicitly (disable-model-invocation: false, user-invocable: true, shell: bash).

Shell-enabled environments (optional accelerators)

If the destination environment exposes a shell, additionally run:

npx prettier --check '<dir>/**/*.md'
npx markdownlint-cli2 '<dir>/**/*.md'
# Project mode in a Claude Code repo with cspell configured:
npx cspell '<dir>/**/*.md'

Auto-fix prettier failures with npx prettier --write … and re-run. If cspell flags a legitimate technical term, append it to the repo's cspell dictionary in alphabetical position. These commands are not available in claude.ai Projects or in Claude API contexts that don't expose Bash.

Definition of done

• All manual checks pass for the chosen scope; shell-tool checks also pass when shell is available.
• The new skill directory exists with SKILL.md at minimum.
• For project and personal modes in Claude Code, live-change detection picks up the new skill in the same session — asking "what skills are available?" lists it with the correct description.
• The bundle has no broken sibling-skill references and no commands required as mandatory that the destination environment cannot run.

Hard rules

• Never invent frontmatter fields. If a field isn't documented in references/frontmatter-spec.md or the upstream pages it cites, don't emit it.
• Never write a skill body longer than 500 lines. Move overflow into references/*.md and link to it from SKILL.md.
• Never scaffold empty subdirectories. Only create references/, scripts/, or assets/ when a file is being placed inside.
• Never bypass the intake step on a thin brief. If any required slot is missing, apply references/intake-methodology.md first.
• Never assume the destination has a shell. Manual checks are authoritative; shell tools are optional accelerators.

Technical details

Source

Standalone skill

Skill name

create-skill

Maturity

experimental

Security review

No security review

File

skills/create-skill/SKILL.md

To use this skill in Claude Code, copy SKILL.md into your local .claude/skills/create-skill/ directory. Standalone skills are not exposed via claude plugin install — that path is reserved for plugin bundles.

Edit this skill on GitHub — opens GitHub's web editor. No git knowledge needed.