Guide for creating Agent Skills with progressive disclosure, SKILL.md structure, and best practices
Comprehensive guide for creating modular Agent Skills with progressive disclosure, SKILL.md structure, and best practices. Use when building new skills or understanding skill organization and implementation patterns.
/plugin marketplace add vinnie357/claude-skills/plugin install claude-code@vinnie357This skill is limited to using the following tools:
Comprehensive guide for creating modular, self-contained Agent Skills that extend Claude's capabilities with specialized knowledge.
Activate this skill when:
Agent Skills are organized directories containing instructions, scripts, and resources that Claude can dynamically discover and load. They enable a single general-purpose agent to gain domain-specific expertise without requiring separate custom agents for each use case.
Skills operate on a principle of progressive disclosure across multiple levels:
Agent system prompts include only skill names and descriptions, allowing Claude to decide when each skill is relevant based on the task at hand.
When Claude determines a skill applies, it loads the full SKILL.md file into context, gaining access to the complete procedural knowledge and guidelines.
Additional bundled files (like references, forms, or documentation) load only when needed for specific scenarios, keeping token usage efficient.
This tiered approach maintains efficient context windows while supporting potentially unbounded skill complexity.
Every skill must have:
skill-name/
└── SKILL.md
More complex skills can include additional resources:
skill-name/
├── SKILL.md # Required: Core skill definition
├── scripts/ # Optional: Executable code for deterministic tasks
├── references/ # Optional: Documentation loaded on-demand
└── assets/ # Optional: Templates, images, boilerplate
Each SKILL.md file must begin with YAML frontmatter followed by Markdown content:
---
name: skill-name
description: Concise explanation of when Claude should use this skill
license: MIT
---
# Skill Name
Main instructional content goes here...
name: Hyphen-case identifier matching directory name (lowercase alphanumeric and hyphens only)description: Explains the skill's purpose and when Claude should utilize itlicense: License name or filename referenceallowed-tools: Pre-approved tools list (Claude Code support only)metadata: Key-value string pairs for client-specific propertiesThe content section has no restrictions and should contain:
Gather concrete use cases to clarify what the skill should support. Real-world examples reveal actual needs better than theoretical requirements.
Example:
Use Case: Help developers follow Git best practices
Examples:
- Creating conventional commit messages
- Rebasing feature branches
- Resolving merge conflicts
- Creating descriptive branch names
Analyze examples to identify needed components:
Example:
Git skill resources:
- scripts/analyze-commit.sh - Parse git diff for commit message
- references/conventional-commits.md - Detailed commit format spec
- assets/gitignore-templates/ - Common .gitignore files
Create the skill directory structure with the required SKILL.md file. Ensure the directory name matches the name property exactly.
mkdir -p my-skill/{scripts,references,assets}
touch my-skill/SKILL.md
Develop resource files and update SKILL.md with:
Use imperative/infinitive form rather than second-person instruction for clarity.
✅ Good: "Follow the Conventional Commits specification" ✅ Good: "Use descriptive branch names with type prefixes" ❌ Avoid: "You should try to use descriptive names when possible"
Keep core procedural information in SKILL.md and detailed reference material in separate files.
Document all sources in the plugin's sources.md. For each skill created, record:
This maintains traceability and helps others understand the skill's foundation.
Test the skill with representative scenarios to ensure:
Refine based on real-world usage feedback. Monitor how Claude actually uses the skill and adjust the description and content accordingly.
Identify specific capability gaps by testing agents on representative tasks. Build skills incrementally to address actual shortcomings rather than anticipated needs.
Split unwieldy SKILL.md files into separate referenced documents:
Example:
# Git Skill
For detailed conventional commit format, see references/conventional-commits.md
For rebase workflow, see references/rebasing-guide.md
The skill name and description heavily influence when Claude activates it. Pay particular attention to:
git-operations, elixir-phoenix)Examples:
✅ Good Description:
description: Guide for Git operations including commits, branches, rebasing, and conflict resolution
❌ Too Vague:
description: Helps with Git
Monitor real usage patterns and iterate based on actual behavior.
Work with Claude to capture successful approaches and common mistakes into reusable skill components. Ask Claude to self-reflect on what contextual information actually matters.
Use clear, imperative language that Claude can follow:
✅ Good:
❌ Avoid:
Include concrete examples wherever possible to illustrate patterns and approaches.
Install skills only from trusted sources. When evaluating unfamiliar skills:
All skills MUST adhere to strict anti-fabrication requirements to ensure factual, measurable content.
---
name: git
description: Guide for Git operations including commits, branches, rebasing, and conflict resolution
license: MIT
---
# Git Operations
## When to Use
Activate when:
- Creating commit messages
- Managing branches
- Resolving conflicts
- Rebasing or merging
## Conventional Commits
Follow the format: `type(scope): description`
Types: feat, fix, docs, style, refactor, test, chore
Example: `feat(auth): add OAuth2 login support`
## Branch Naming
Use format: `type/description`
Examples:
- `feature/user-authentication`
- `fix/memory-leak`
- `docs/api-reference`
## Rebasing Workflow
1. Update main: `git checkout main && git pull`
2. Rebase feature: `git checkout feature-branch && git rebase main`
3. Resolve conflicts if needed
4. Force push: `git push --force-with-lease`
---
name: phoenix
description: Guide for building Phoenix web applications with LiveView, contexts, and best practices
license: MIT
---
# Phoenix Framework
## When to Use
Activate for:
- Phoenix application development
- LiveView implementations
- Context design
- Channel setup
## Project Structure
Phoenix apps follow:
lib/ ├── my_app/ # Business logic (contexts) ├── my_app_web/ # Web interface └── my_app.ex
## Contexts
Group related functionality:
```elixir
defmodule MyApp.Accounts do
def list_users, do: Repo.all(User)
def get_user!(id), do: Repo.get!(User, id)
def create_user(attrs), do: ...
end
For detailed context patterns, see references/contexts.md
For real-time interfaces, see references/liveview-guide.md
## Common Pitfalls
### Too Generic
❌ Avoid:
```yaml
name: programming
description: Helps with programming
✅ Better:
name: elixir-phoenix
description: Guide for building Phoenix web applications with LiveView, contexts, and Elixir best practices
❌ Avoid putting entire API reference in SKILL.md
✅ Better: Keep core patterns in SKILL.md, detailed reference in references/
❌ Avoid:
# My Skill
This skill helps with stuff.
✅ Better:
# My Skill
## When to Use
Activate when:
- Specific scenario 1
- Specific scenario 2
- Specific scenario 3
For more information:
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.