new-skill

name	new-skill
description	Use when creating a new Claude Code skill directory and SKILL.md. Also use when the user says 'create a skill', 'new skill', or 'add a skill'. Handles both shared (~/.claude/skills/) and project-specific (.claude/skills/) skills.
allowed-tools	Read, Write, Edit, Glob, Grep, Bash
argument-hint	<skill-name>
disable-model-invocation	true

New Skill

What this skill does

Creates a new Claude Code skill from scratch, following the canonical template structure. It guides the agent through choosing a skill name, writing trigger-oriented descriptions, structuring the SKILL.md with progressive disclosure, and placing the skill in the correct scope (shared personal vs. project-specific). The result is a complete, spec-compliant skill directory ready for use.

When to load sub-files

• Creating any new skill → read SKILL_TEMPLATE.md and use it as the starting skeleton
• Need current Anthropic field specs or substitution variable docs → read ~/.claude/skills/do-skills-audit/references/anthropic-skills-docs.txt
• Need a real-world example of a canonical skill structure → read ~/.claude/skills/do-skills-audit/references/anthropic-skill-creator.md

Quick start

1. Choose a name: lowercase, hyphenated (e.g., my-new-skill). Must match the directory name.
2. Choose scope:
   • Project-specific: .claude/skills/<name>/SKILL.md (only this repo)
   • Shared/personal: ~/.claude/skills/<name>/SKILL.md (all repos for this user)
3. Create the directory: mkdir -p <scope-path>/<name>/
4. Copy the template: Read SKILL_TEMPLATE.md and save it as <name>/SKILL.md
5. Fill in the frontmatter: Set name, description, and allowed-tools
6. Write the body: Follow the template sections — "What this skill does", "When to load sub-files", "Quick start"
7. Test discovery: Invoke /name in Claude Code and verify the skill loads

Description field rules

The description field in frontmatter is what Claude uses to decide whether to load a skill. It must be written carefully.

Format: Third person, trigger-oriented. Start with "Use when..." not "This skill...".

Structure: Use when [primary trigger]. Also use when [secondary triggers]. Handles [capability list].

Examples:

• Good: Use when creating a new Claude Code skill directory and SKILL.md. Also use when the user says 'create a skill'. Handles both shared and project-specific skills.
• Bad: This skill helps create new skills for Claude Code.
• Bad: A tool for making skills.

Rules:

1. Must describe WHEN to use the skill, not WHAT it is
2. Include natural language phrases users might say (e.g., "create a skill", "add a command")
3. Written in third person — Claude reads this to decide if the skill matches
4. Max 1024 characters (hard limit from spec)
5. Aim for under 200 characters to stay within the 2% context budget across all skills

Field constraints

Field	Required	Constraints
name	Yes	Must match directory name. Lowercase, hyphenated.
description	Yes	Max 1024 chars. Third person, trigger-oriented ("Use when...").
allowed-tools	No	Comma-separated tool names. Restricts which tools the skill can use. Omit to allow all.
hooks	No	YAML block defining validation hooks that run on Stop events.
disable-model-invocation	No	Set true to prevent Claude from auto-triggering. Use for infrastructure skills (setup, update).
user-invocable	No	Set false to hide from /slash-command menu. Use for background reference skills.
context	No	Set fork to run in a separate context. Use for long-running or parallel tasks.
agent	No	Which subagent type to use when context: fork is set.
argument-hint	No	Hint shown during autocomplete when the skill expects $ARGUMENTS.
model	No	Model to use when this skill is active.

Skill directory structure

A minimal skill needs only SKILL.md. Larger skills use progressive disclosure:

.claude/skills/<name>/
├── SKILL.md              # Main file (REQUIRED, < 500 lines)
├── SUB_FILE.md           # Reference material loaded on demand
├── ANOTHER_SUB_FILE.md   # More reference material
├── scripts/
│   └── validate.sh       # Executable automation (saves context tokens)
└── references/
    └── API_REFERENCE.md  # Detailed specs, schemas, examples

Key principle: SKILL.md is a navigator. It tells Claude what the skill does and when to read sub-files. Detailed instructions, templates, and reference material go in sub-files that are loaded only when needed.

Debugging

If a skill is not being discovered or loaded:

1. Check the name: name in frontmatter must exactly match the directory name
2. Check frontmatter syntax: YAML must be valid, enclosed in --- delimiters
3. Check description: Must contain trigger words that match the user's request
4. Check location: Skill must be in .claude/skills/ (project) or ~/.claude/skills/ (personal)
5. Check disable-model-invocation: If true, Claude will not auto-load it — only /slash-command works
6. Check line count: SKILL.md should stay under 500 lines for optimal loading
7. Restart Claude Code: Skill discovery happens at session start; new skills need a restart

Anti-patterns

• Monolithic SKILL.md: Do not put everything in one file. Extract templates, examples, and reference material into sub-files loaded conditionally.
• Vague descriptions: "A useful skill for doing things" will never match. Be specific about triggers.
• First-person descriptions: "I help create skills" is wrong. Use "Use when creating skills."
• Missing trigger phrases: If users say "make a command" but the description only says "create a skill", it will not match. Include synonyms.
• Hardcoded paths: Use relative paths for sub-file references so skills work in both project and personal scope.
• Over-permissive allowed-tools: Only list tools the skill actually needs. Fewer tools = smaller attack surface.
• Skipping progressive disclosure: A 600-line SKILL.md that loads every time wastes context tokens. Split it.

Version history

• v1.0.0 (2026-02-22): Initial — extracted from new-valor-skill as a generic, repo-agnostic skill creator