Skip to content
Skills Library
AI & agents · Building & coding

claude-code-skill-development

/claude-code-skill-development

This skill should be used when the user asks to "create a skill", "write a skill", "build a skill", or wants to add new capabilities to Claude Code. Use when developing SKILL.md files, organizing skill content, or improving existing skills. Do NOT use for plugin development, hook creation, agent creation, or slash command creation — those have dedicated skills.

Licence
MIT
Last repository change
10.09.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
8
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 10.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

This skill should be used when the user asks to "create a skill", "write a skill", "build a skill", or wants to add new capabilities to Claude Code. Use when developing SKILL.md files, organizing skill content, or improving existing skills. Do NOT use for plugin development, hook creation, agent creation, or slash command creation — those have dedicated skills.

Triggers from the description

create a skillwrite a skillbuild a skill
Original author description

This skill should be used when the user asks to "create a skill", "write a skill", "build a skill", or wants to add new capabilities to Claude Code. Use when developing SKILL.md files, organizing skill content, or improving existing skills. Do NOT use for plugin development, hook creation, agent creation, or slash command creation — those have dedicated skills.

How it works

  1. Quick Reference
  2. Before You Start
  3. Core Principles
  4. Skill Structure
  5. YAML Frontmatter
  6. Writing Effective Descriptions
  7. Progressive Disclosure Pattern
  8. Testing Your Skill
  9. Troubleshooting
  10. Important
Original SKILL.md headings · 153 lines, 731 words
SKILL.md preview
---
name: claude-code-skill-development
description: This skill should be used when the user asks to "create a skill", "write a skill", "build a skill", or wants to add new capabilities to Claude Code. Use when developing SKILL.md files, organizing skill content, or improving existing skills. Do NOT use for plugin development, hook creation, agent creation, or slash command creation — those have dedicated skills.
allowed-tools: Read, Grep
---

# Skill Development

Create effective Claude Code skills that are concise, discoverable, and well-structured.

## Quick Reference

You MUST read these references for detailed guidance:

- [Best Practices](./references/best-practices.md) - Official Anthropic guidance
- [Skill Examples](./references/examples.md) - Patterns from real skills
- [Skill Categories & Patterns](./references/patterns.md) - Three categories and five reusable patterns
- [Testing Guide](./references/testing.md) - Triggering, functional, and performance testing
- [Troubleshooting](./references/troubleshooting.md) - Common problems and fixes
- [The Complete Guide to Building Skills for Claude](./references/complete-guide-to-building-skills.md) - Comprehensive Anthropic guide ([source PDF](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf))

## Before You Start

Define 2-3 concrete use cases before writing anything:

```
Use Case: [Name]
Trigger: User says "[phrase]" or "[phrase]"
Steps:
1. [First action]
2. [Second action]
Result: [What gets produced]
```

Then identify which category your skill falls into — this determines which techniques to use. See [Skill Categories & Patterns](./references/patterns.md).

## Core Principles

1. **Concise is key** - Only add context Claude doesn't already have
2. **Progressive disclosure** - SKILL.md is the overview; details go in `references/`
3. **Write in third person** - "This skill processes..." not "I can help you..."

## Skill Structure

```
skill-name/
├── SKILL.md              # Main instructions (< 500 lines)
├── scripts/              # Optional: executable code (Python, Bash, etc.)
├── assets/               # Optional: templates, fonts, icons
└── references/           # Detailed docs (loaded on demand)
    ├── guide.md
    └── examples/
```

## YAML Frontmatter

```yaml
---
name: my-skill-name
description: This skill should be used when the user asks to "do X", "create Y", or mentions Z. Be specific about triggers.
context: fork          # Optional: run in isolated context (prevents side effects)
user-invocable: true   # Optional: show in slash command menu (default: true)
---
```

**Name rules:**
- Lowercase letters, numbers, hyphens only
- Max 64 characters
- No reserved words (anthropic, claude)

**Description rules:**
- Max 1024 characters
- Third person ("This skill..." not "I can...")
- Include WHAT it does AND WHEN to use it

**Optional fields:**
- `context: fork` - Run skill in isolated sub-agent context, preventing unintended side effects on main agent state
- `user-invocable: false` - Hide from slash command menu (skills are visible by default)
- `allowed-tools` - Restrict which tools the skill can use (e.g., `"Bash(python:*) Bash(npm:*) WebFetch"`). **Skills with `references/` directories should include `allowed-tools: Read, Grep`** to avoid permission prompts when accessing bundled files ([claude-code#15757](https://github.com/anthropics/claude-code/issues/15757))
- `license` - e.g., MIT, Apache-2.0
- `compatibility` - Environment requirements (1-500 chars)
- `metadata` - Custom key-value pairs (author, version, mcp-server)

## Writing Effective Descriptions

Structure: `[What it does] + [When to use it] + [Key capabilities]`

```yaml
# Good - specific triggers
description: This skill should be used when the user asks to "create a hook", "add a hook", or mentions Claude Code hooks.

# Bad - vague
description: Helps with automation tasks.
```

## Progressive Disclosure Pattern

Keep SKILL.md under 500 lines. Link to details:

```markdown
# My Skill

## Quick start
[Essential info here]

## Advanced features
See [detailed-guide.md](./references/detailed-guide.md)

## API reference
See [api-reference.md](./references/api-reference.md)
```

Claude loads reference files only when needed.

## Testing Your Skill

Validate across three dimensions before sharing:

1. **Triggering** - Does it load when it should? Not load when it shouldn't?
2. **Functional** - Does it produce correct outputs and handle errors?
3. **Performance** - Is it actually better than no skill? (fewer messages, fewer errors, less tokens)

See [Testing Guide](./references/testing.md) for test examples and success criteria.

## Troubleshooting

Common issues and fixes:

| Symptom | Fix |
|---------|-----|
| Doesn't trigger | Add specific trigger phrases to description |
| Triggers too often | Add negative triggers, narrow scope |
| Instructions ignored | Make instructions concise, use explicit headers |
| Slow responses | Move content to `references/`, reduce SKILL.md size |

See [Troubleshooting](./references/troubleshooting.md) for detailed solutions.

## Important

After creating or modifying skills, inform the user:

> **No restart needed.** Skill changes take effect immediately - skills are hot-reloaded.

## Checklist

Before finalizing a skill:

- [ ] 2-3 use cases defined with triggers, steps, and results
- [ ] Category identified (document creation, workflow automation, MCP enhancement)
- [ ] Description includes triggers ("when user asks to...")
- [ ] SKILL.md under 500 lines
- [ ] Complex content moved to `references/`
- [ ] Third person throughout
- [ ] No time-sensitive information
- [ ] Consistent terminology
- [ ] Triggering tests pass (obvious + paraphrased requests)
- [ ] Doesn't trigger on unrelated topics
Files in this package (8)
  • SKILL.md 6 KB
  • skill-tests.yaml 1 KB
  • references/best-practices.md 5 KB
  • references/complete-guide-to-building-skills.md 9 KB
  • references/examples.md 5 KB
  • references/patterns.md 5 KB
  • references/testing.md 7 KB
  • references/troubleshooting.md 5 KB

Versions

The database has no other skills named claude-code-skill-development.

Database snapshot: 13.11.2026 · package version 10223cd506dc (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100skill-authoring
    Expert guidance for creating Claude Code skills and slash commands. Use when authoring new skills, improving existing skills, creating commands, or understanding skill structure and best practices.
  • 100create-agent-skills
    Expert guidance for creating Claude Code skills and slash commands. Use when working with SKILL.md files, authoring new skills, improving existing skills, creating slash commands, or understanding skill structure and best practices.
  • 100claude-code-skills
    Guide for creating effective Agent Skills in Claude Code. This skill should be used when users want to create a new Skill (or update an existing Skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations. Use when working specifically…
  • 100skill-builder
    Use when creating new skills, optimizing existing skills, or auditing skill quality. Guides skill development following Claude Code official best practices.
  • 95meta-command-development
    Use when the user asks to ”create a slash command”, ”add a command”, or ”write a custom command” for Claude Code.
  • 100skill-writer
    Guide users through creating Agent Skills for Claude Code. Use when the user wants to create, write, author, or design a new Skill, or needs help with SKILL.md files, frontmatter, or skill structure.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.