skill-dev
Use this skill when creating or refining Claude Code skill definitions. Skills are model-invoked capabilities that Claude activates autonomously based on context. Helps design focused skills with discovery-optimized descriptions, proper directory structures, and supporting resources. Automatically invoked when user requests "create a skill", "make a capability", "add autonomous behavior", or mentions skill development. Ensures skills follow Anthropic specifications with clear activation triggers.
andisab · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add andisab/swe-marketplace --skill skill-devAbout this skill
name: skill-dev description: > Use this skill when creating or refining Claude Code skill definitions. Skills are model-invoked capabilities that Claude activates autonomously based on context. Helps design focused skills with discovery-optimized descriptions, proper directory structures, and supporting resources. Automatically invoked when user requests "create a skill", "make a capability", "add autonomous behavior", or mentions skill development. Ensures skills follow Anthropic specifications with clear activation triggers. allowed-tools: Read, Write, Edit, Grep, Glob, Bash(mkdir:), Bash(tree:), mcp__conventions__find_conventions
Skill Dev Skill
This skill helps create production-ready Claude Code skills following Anthropic's official specifications and best practices.
Skills vs Agents: Key Differences
| Aspect | Skills | Sub-agents |
|---|---|---|
| Invocation | Model-invoked (automatic) | User-invoked (explicit) or Task tool |
| Scope | Single capability | Multiple capabilities |
| File | Directory with SKILL.md | Single .md file |
| Supporting files | Can include templates, scripts | System prompt only |
| Discovery | Description matching | Description + explicit invocation |
| Use case | Reusable patterns, tools, workflows | Specialized AI assistants |
When to use Skills: Create autonomous capabilities that Claude should invoke automatically when context matches (e.g., PDF processing, form filling, specific workflows)
When to use Agents: Create specialized AI assistants for complex domains requiring multi-step reasoning (e.g., database expert, security auditor)
Use Case Categories
Anthropic identifies three common skill categories:
| Category | Purpose | Example |
|---|---|---|
| Document & Asset Creation | Produce tangible outputs (reports, documents, designs, code) | A frontend-design skill that creates production-grade UI components |
| Workflow Automation | Orchestrate multi-step processes with validation gates | A skill-creator skill that walks users through use case definition, frontmatter, and validation |
| MCP Enhancement | Add knowledge and best practices on top of MCP tool access | A sentry-code-review skill that uses Sentry's MCP to analyze and fix bugs in PRs |
The kitchen analogy: MCP provides the professional kitchen (tools, ingredients, equipment). Skills provide the recipes (step-by-step instructions on how to create something valuable). Together, they enable users to accomplish complex tasks without figuring out every step themselves. See patterns/skill-mcp-integration.md for in-depth MCP integration guidance.
Problem-First vs. Tool-First
When designing a skill, choose your framing:
- Problem-first: Start from a user pain point, then orchestrate the right tools to solve it. Users describe outcomes; the skill handles the tools. Example: "I need to set up a project workspace" → skill orchestrates MCP calls in the right sequence.
- Tool-first: You have MCP tools connected, and the skill teaches Claude optimal workflows and best practices for using them. Users have access; the skill provides expertise. Example: "I have Notion MCP connected" → skill teaches Claude the best project setup workflows.
Most skills lean one direction. Knowing which framing fits your use case helps you choose the right pattern (see Common Patterns below).
Skill Structure
skill-name/
├── SKILL.md # Required: Skill definition and content
├── examples/ # Optional: Example usage
│ ├── basic-usage.md
│ └── advanced-patterns.md
├── templates/ # Optional: Code templates
│ └── template-file.py
├── references/ # Optional: Reference materials
│ └── api-docs.md
├── assets/ # Optional: Static resources (templates, fonts, icons)
│ └── report-template.md
└── scripts/ # Optional: Helper scripts
└── helper.py
Important: Do NOT include README.md inside skill directories. SKILL.md serves as both the skill definition and documentation. When distributing via GitHub, use a repo-level README for human users — that is separate from the skill folder contents.
SKILL.md Format
---
name: skill-name
description: >
Detailed description of what this skill does, when Claude should use it,
and specific trigger terms. This field is CRITICAL for skill discovery.
Include:
- What the skill accomplishes
- When to activate (specific scenarios)
- Key trigger terms users might mention
- Concrete examples of usage
allowed-tools: Tool1, Tool2 # Optional: Tool restrictions
---
# Skill Content
Main skill content starts here. This is what Claude sees when the skill is activated.
Include:
- Clear instructions
- Examples
- Best practices
- Common patterns
- Error handling
Reference supporting files with relative paths:
- See `examples/basic-usage.md` for getting started
- Use templates from `templates/` directory
- Consult `references/api-docs.md` for API details
Required Fields
name
Unique identifier for the skill.
Constraints:
- Should match the skill folder name
- Lowercase alphanumeric with hyphens only
- Maximum 64 characters
- Descriptive of the capability
name: pdf-form-filling # Good
name: PDF Form Filling # Bad - no spaces/capitals
name: helper # Bad - too generic
name: skill-that-does-pdf-form-filling-and-extraction # Bad - too long
description
The MOST IMPORTANT field. Claude uses this to decide when to activate the skill.
Critical elements:
- Primary capability: What does this skill do? (1-2 sentences)
- Activation triggers: When should Claude use this? (be specific)
- Key terms: Words/phrases users might mention
- Scope boundaries: What this skill does NOT handle
- Negative triggers: Explicitly state what