// Create, manage, and debug Claude Code Agent Skills. Use when creating new skills, debugging skill activation issues, writing SKILL.md files, managing skill structure, or learning about Claude Code skills. Helps with personal skills, project skills, YAML frontmatter, descriptions, and troubleshooting.
Release a new version of the itsvertical npm package. Bump version, build, publish, and create a GitHub release. Use when the user mentions releasing, publishing, cutting a release, or shipping a new version.
Manage projects with the Vertical board using the itsvertical CLI. Create projects, add tasks, organize boxes, split layers, and track progress. Use when the user mentions Vertical, project management, boxes, slices, .vertical files, or itsvertical.
Write and run unit tests with Vitest. Use when writing tests, adding test coverage, debugging test failures, or when the user mentions testing, vitest, unit tests, or test-driven development.
| name | skill-manager |
| description | Create, manage, and debug Claude Code Agent Skills. Use when creating new skills, debugging skill activation issues, writing SKILL.md files, managing skill structure, or learning about Claude Code skills. Helps with personal skills, project skills, YAML frontmatter, descriptions, and troubleshooting. |
| metadata | {"internal":true} |
Create and manage Agent Skills for Claude Code. Skills are modular capabilities that extend Claude's functionality through organized folders containing instructions, scripts, and resources.
Skills are model-invoked: Claude autonomously decides when to use them based on the user's request and the Skill's description. This is different from slash commands, which are user-invoked (explicitly typing /command).
Benefits:
What Skills Provide:
Skills act as "onboarding guides" that transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess. They provide:
Skills use a three-level loading system to manage context efficiently:
Metadata (name + description) - Always in context (~100 words)
SKILL.md body - Loaded when skill triggers (<5k words recommended)
Bundled resources - Loaded or executed as needed
scripts/ may execute without loading into context (token efficient, deterministic)references/ loaded into context when Claude determines neededassets/ used in output, never loaded into contextThis design keeps Claude's context lean while providing access to unlimited specialized knowledge when needed.
Location: ~/.claude/skills/
Use for:
Create a personal skill:
mkdir -p ~/.claude/skills/my-skill-name
Location: .claude/skills/ (within your project)
Use for:
Create a project skill:
mkdir -p .claude/skills/my-skill-name
Project Skills are checked into git and automatically available to team members.
Skills can also come from Claude Code plugins. These work the same way as personal and project Skills.
The skill-manager skill activates automatically when working with skills. Here are concrete examples of using this skill:
User request:
I frequently work with PDF files and need to extract text, rotate pages, and merge documents. Can you help me create a skill for this?
What happens:
scripts/rotate_pdf.pyResult: A new .claude/skills/pdf-processor/ directory with SKILL.md and scripts that can be used immediately.
User request:
I created a code review skill but Claude isn't using it when I ask for code reviews. Can you help debug this?
What happens:
Result: The code review skill now activates correctly when requested.
User request:
Every time I deploy, I run the same 5 commands and checks. Can we turn this into a skill?
What happens:
.claude/skills/deployment/ with clear pre-deployment checklistscripts/preflight-check.sh for automated checksResult: A deployment skill that activates with "deploy" or "deployment" triggers, automating repetitive tasks.
Follow these style rules when writing skills for consistency and clarity:
Use imperative/infinitive form (verb-first instructions), not second person:
Use imperative form in descriptions without redundant "this skill":
Use objective, instructional language:
Example of proper style:
## Instructions
1. Read the target file to understand its structure
2. Identify the sections requiring updates
3. Apply the transformation using the script
4. Validate the output meets requirements
For detailed schema information, refer to [references/schema.md](references/schema.md).
Every skill requires a SKILL.md file with YAML frontmatter:
---
name: Skill Name
description: Brief description of what this Skill does and when to use it
---
# Skill Name
## Instructions
Provide clear, step-by-step guidance for Claude.
## Examples
Show concrete examples of using this Skill.
name: The skill's display name
description: Critical for Claude to discover when to use the Skill
allowed-tools: Restrict which tools Claude can use when the Skill is active
Example:
---
name: Safe File Reader
description: Read files without making changes. Use when you need read-only file access.
allowed-tools: Read, Grep, Glob
---
metadata.internal: Hide skill from remote discovery via npx skills add
true to prevent the skill from being offered when external users install skills from the repovertical skill in this project should be publicly discoverable; all other project skills must have metadata.internal: trueExample:
---
name: my-internal-skill
description: An internal skill not shown by default.
metadata:
internal: true
---
The description is the most critical part of skill discovery.
✅ Specific with triggers:
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
✅ Clear use case:
description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.
✅ Action-oriented:
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
❌ Too vague:
description: Helps with documents
❌ Too generic:
description: For data
❌ Missing triggers:
description: Document processing tool
Use this formula for effective descriptions:
[What it does] + [Specific actions] + "Use when" + [Trigger scenarios/keywords]
Example:
description: Review code for best practices, security issues, and performance problems. Use when reviewing code, checking PRs, analyzing code quality, or when user mentions code review or security audit.
my-skill/
└── SKILL.md
Best for:
my-skill/
├── SKILL.md (required)
├── references/
│ └── detailed-guide.md
├── scripts/
│ └── helper.py
└── assets/
└── template.txt
Best for:
IMPORTANT: Avoid Duplication - Information should live in either SKILL.md or resource files, not both. Keep SKILL.md lean with essential procedural instructions; move detailed reference material, schemas, and examples to resource files.
scripts/)Executable code (Python/Bash/etc.) for tasks requiring deterministic reliability.
When to include:
Examples: scripts/rotate_pdf.py for PDF rotation, scripts/analyze_data.py for data processing
Benefits:
Note: Scripts may still need to be read by Claude for patching or environment-specific adjustments
references/)Documentation and reference material loaded INTO context as needed to inform Claude's process.
When to include:
Examples: references/schema.md for database schemas, references/api-docs.md for API specifications, references/policies.md for company guidelines
Benefits:
Best practice: For large files (>10k words), include grep search patterns in SKILL.md to help Claude find specific information efficiently
assets/)Files used IN the output Claude produces, never loaded into context.
When to include:
Examples: assets/logo.png for brand assets, assets/template.html for HTML templates, assets/boilerplate/ for project starters
Benefits:
Reference files from SKILL.md:
For advanced usage, see [references/detailed-guide.md](references/detailed-guide.md).
Run the helper script:
```bash
python scripts/helper.py input.txt
```
Use the template:
```bash
cp assets/template.html output.html
```
Use allowed-tools to limit capabilities for safety or scope:
Read-only skill:
---
name: Code Analyzer
description: Analyze code without making changes. Use for code analysis and review.
allowed-tools: Read, Grep, Glob
---
Limited scope skill:
---
name: Data Inspector
description: Inspect data files and generate reports. Use for data analysis.
allowed-tools: Read, Bash
---
When to use allowed-tools:
When to skip allowed-tools:
Follow this process when creating a new skill from scratch:
Clearly understand how the skill will be used before implementing it. Gather concrete examples through:
Example questions:
Conclude when there is a clear sense of the functionality the skill should support.
Analyze each concrete example to identify reusable resources:
Example analysis:
scripts/rotate_pdf.py"assets/boilerplate/ template"references/schema.md"Create a list of reusable resources to include: scripts, references, and assets.
Create the skill directory and initial structure:
# Personal skill
mkdir -p ~/.claude/skills/skill-name
# Project skill
mkdir -p .claude/skills/skill-name
# Create SKILL.md
touch .claude/skills/skill-name/SKILL.md
Add resource directories as needed:
mkdir -p .claude/skills/skill-name/{scripts,references,assets}
Start with reusable resources:
Write SKILL.md: Answer these questions in the skill:
Reference all reusable contents so Claude knows how to use them.
Remember:
Test the skill with realistic scenarios:
# Test with questions matching your description
Can you [trigger phrase from description]?
Iteration workflow:
Continue iterating until the skill performs effectively.
After creating a Skill, test it by asking questions that match the description.
If the description mentions "PDF files":
Can you help me extract text from this PDF?
If the description mentions "commit messages":
Help me write a commit message for my changes
Claude should autonomously discover and use the Skill based on context.
Check 1: Verify Description Specificity
Run this mental test:
Check 2: Verify File Location
# Personal Skills
ls ~/.claude/skills/*/SKILL.md
# Project Skills
ls .claude/skills/*/SKILL.md
Check 3: Validate YAML Syntax
# View frontmatter
cat .claude/skills/my-skill/SKILL.md | head -n 15
Common YAML errors:
--- on line 1--- before Markdown contentCheck 4: Run in Debug Mode
claude --debug
Check dependencies: Claude will automatically install required dependencies when needed. List required packages in the description:
description: Extract text from PDF files using pdfplumber. Use when working with PDFs. Requires pdfplumber package.
Check script permissions:
chmod +x .claude/skills/my-skill/scripts/*.py
Check file paths: Use forward slashes (Unix style) in all paths:
scripts/helper.pyscripts\helper.pyMake descriptions distinct: Use specific trigger terms that differentiate skills.
Instead of:
# Skill 1
description: For data analysis
# Skill 2
description: For analyzing data
Use:
# Skill 1
description: Analyze sales data in Excel files and CRM exports. Use for sales reports, pipeline analysis, and revenue tracking.
# Skill 2
description: Analyze log files and system metrics data. Use for performance monitoring, debugging, and system diagnostics.
One Skill = One capability
✅ Focused:
❌ Too broad:
## Instructions
1. Run `git diff --staged` to see changes
2. Analyze the changes for:
- New features (use "Add")
- Bug fixes (use "Fix")
- Refactoring (use "Refactor")
3. Generate a commit message with:
- Summary under 50 characters
- Detailed description explaining why
Show real usage patterns:
## Examples
Extract text from page 1:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
text = pdf.pages[0].extract_text()
print(text)
### 4. Test with the Team
Have teammates:
- Test if the Skill activates when expected
- Verify instructions are clear
- Identify missing examples or edge cases
## Skill Templates
### Template 1: Simple Single-File Skill
```yaml
---
name: [Skill Name]
description: [What it does]. [Specific actions]. Use when [trigger scenarios and keywords].
---
# [Skill Name]
## Instructions
1. [Step 1]
2. [Step 2]
3. [Step 3]
## Examples
[Concrete example showing usage]
## Best Practices
- [Best practice 1]
- [Best practice 2]
---
name: [Skill Name]
description: [What it does] without making changes. Use for [read-only scenarios].
allowed-tools: Read, Grep, Glob
---
# [Skill Name]
## Instructions
1. Use Read to view file contents
2. Use Grep to search within files
3. Use Glob to find files by pattern
4. [Additional read-only operations]
## Analysis Checklist
- [ ] [Check item 1]
- [ ] [Check item 2]
- [ ] [Check item 3]
Directory structure:
skill-name/
├── SKILL.md
├── REFERENCE.md
└── scripts/
└── helper.py
SKILL.md:
---
name: [Skill Name]
description: [What it does]. [Specific actions]. Use when [triggers]. Requires [dependencies].
---
# [Skill Name]
## Quick Start
[Basic usage example]
## Instructions
1. [Step 1]
2. Run helper script:
```bash
python scripts/helper.py input.txt
```
3. [Step 3]
For detailed reference, see [REFERENCE.md](REFERENCE.md).
## Requirements
```bash
pip install [package1] [package2]
```
---
name: Code Reviewer
description: Review code for best practices, security issues, performance problems, and test coverage. Use when reviewing code, checking PRs, analyzing code quality, security audit, or code feedback.
allowed-tools: Read, Grep, Glob
---
# Code Reviewer
## Review Checklist
### Code Organization
- [ ] Clear module structure
- [ ] Logical separation of concerns
- [ ] Consistent naming conventions
### Error Handling
- [ ] Proper error catching
- [ ] Meaningful error messages
- [ ] Graceful failure modes
### Performance
- [ ] No obvious bottlenecks
- [ ] Efficient algorithms
- [ ] Resource management
### Security
- [ ] Input validation
- [ ] No hardcoded secrets
- [ ] Proper authentication/authorization
### Testing
- [ ] Test coverage adequate
- [ ] Edge cases covered
- [ ] Tests are maintainable
## Instructions
1. Read the target files using Read tool
2. Search for patterns using Grep
3. Find related files using Glob
4. Review against checklist
5. Provide specific, actionable feedback
When a skill doesn't work, check in this order:
# Personal
ls ~/.claude/skills/skill-name/SKILL.md
# Project
ls .claude/skills/skill-name/SKILL.md
cat .claude/skills/skill-name/SKILL.md | head -n 10
Check for:
--- on line 1--- before contentname, descriptionReview these criteria:
Ask Claude questions that directly match the description triggers.
claude --debug
Look for skill loading errors.
mkdir -p .claude/skills/team-skill
# Create SKILL.md
git add .claude/skills/
git commit -m "Add team skill for [purpose]"
git push
git pull
claude # Skills are now available
For wider distribution, create a plugin with Skills. See Claude Code plugin documentation.
Ask Claude:
What Skills are available?
or:
List all available Skills
Edit SKILL.md directly:
# Personal
code ~/.claude/skills/my-skill/SKILL.md
# Project
code .claude/skills/my-skill/SKILL.md
Restart Claude Code to load changes.
# Personal
rm -rf ~/.claude/skills/my-skill
# Project
rm -rf .claude/skills/my-skill
git commit -m "Remove unused Skill"
For project-specific feature development workflows.
For running project-specific test suites with custom configurations.
For project-specific deployment procedures and checks.
For generating or updating project-specific documentation formats.
For project-specific code review checklists and standards.
To create a skill:
~/.claude/skills/ (personal) or .claude/skills/ (project)mkdir -p [location]/skill-nameSKILL.md with YAML frontmatter (name + description)For effective discovery:
For debugging:
claude --debug