Skill Manager

Skill Manager

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.

What are Agent Skills?

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:

• Extend Claude's capabilities for specific workflows
• Share expertise across teams via git
• Reduce repetitive prompting
• Compose multiple Skills for complex tasks

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:

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Project-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks

Progressive Disclosure

Skills use a three-level loading system to manage context efficiently:

1. Metadata (name + description) - Always in context (~100 words)

   • Claude sees this for every skill to decide if it's relevant
   • Critical for skill discovery

2. SKILL.md body - Loaded when skill triggers (<5k words recommended)

   • Contains core instructions and workflow guidance
   • Loaded into context only when Claude activates the skill

3. Bundled resources - Loaded or executed as needed

   • scripts/ may execute without loading into context (token efficient, deterministic)
   • references/ loaded into context when Claude determines needed
   • assets/ used in output, never loaded into context

This design keeps Claude's context lean while providing access to unlimited specialized knowledge when needed.

Skill Types and Locations

Personal Skills

Location: ~/.claude/skills/

Use for:

• Individual workflows and preferences
• Experimental Skills under development
• Personal productivity tools

Create a personal skill:

mkdir -p ~/.claude/skills/my-skill-name

Project Skills

Location: .claude/skills/ (within your project)

Use for:

• Team workflows and conventions
• Project-specific expertise
• Shared utilities and scripts

Create a project skill:

mkdir -p .claude/skills/my-skill-name

Project Skills are checked into git and automatically available to team members.

Plugin Skills

Skills can also come from Claude Code plugins. These work the same way as personal and project Skills.

Example Usage Scenarios

The skill-manager skill activates automatically when working with skills. Here are concrete examples of using this skill:

Example 1: Create a PDF Processing 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:

1. The skill-manager activates based on "create a skill" trigger
2. Claude asks clarifying questions about the workflow
3. Identifies that PDF rotation needs a deterministic script
4. Creates the skill structure with scripts/rotate_pdf.py
5. Writes SKILL.md with clear instructions and examples
6. Tests the skill with a sample PDF task

Result: A new .claude/skills/pdf-processor/ directory with SKILL.md and scripts that can be used immediately.

Example 2: Debug Skill Activation Issues

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:

1. The skill-manager activates based on "debug" and "skill" triggers
2. Claude checks the SKILL.md file location and YAML syntax
3. Reviews the description for specificity and trigger words
4. Discovers the description lacks "code review" as a trigger phrase
5. Updates the description with better trigger words
6. Tests with a code review request

Result: The code review skill now activates correctly when requested.

Example 3: Convert Workflow into Reusable Skill

User request:

Every time I deploy, I run the same 5 commands and checks. Can we turn this into a skill?

What happens:

1. The skill-manager activates based on "turn this into a skill" trigger
2. Claude analyzes the deployment workflow
3. Identifies commands that could be automated via scripts
4. Creates .claude/skills/deployment/ with clear pre-deployment checklist
5. Adds a scripts/preflight-check.sh for automated checks
6. Writes deployment instructions in SKILL.md

Result: A deployment skill that activates with "deploy" or "deployment" triggers, automating repetitive tasks.

Creating a Skill

Writing Style Guidelines

Follow these style rules when writing skills for consistency and clarity:

Use imperative/infinitive form (verb-first instructions), not second person:

• ✅ Correct: "To accomplish X, do Y" or "Run the command"
• ❌ Wrong: "You should do X" or "You need to run the command"

Use imperative form in descriptions without redundant "this skill":

• ✅ Correct: "Use when..." or "Use for..."
• ❌ Wrong: "Use this skill when..." or "This skill should be used when..."

Use objective, instructional language:

• Focus on clear, actionable steps
• Avoid conversational or persuasive language
• Maintain consistency throughout the skill

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).

Basic Structure

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.

Required Fields

name: The skill's display name

• Keep it concise and descriptive
• Use kebab-case
• Needs to be EXACTLY the same as the skill folder name

description: Critical for Claude to discover when to use the Skill

• Include what the Skill does
• Include when Claude should use it
• Include trigger words users would mention
• Be specific, not vague

Optional Fields

allowed-tools: Restrict which tools Claude can use when the Skill is active

• Comma-separated list of tool names
• Useful for read-only skills or limited-scope operations
• If not specified, Claude asks for permission normally

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

• Set to true to prevent the skill from being offered when external users install skills from the repo
• Internal skills still work locally — agents discover them from the filesystem as usual
• Only the vertical skill in this project should be publicly discoverable; all other project skills must have metadata.internal: true

Example:

---
name: my-internal-skill
description: An internal skill not shown by default.
metadata:
  internal: true
---

Writing Effective Descriptions

The description is the most critical part of skill discovery.

Good Descriptions

✅ 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.

Bad Descriptions

❌ Too vague:

description: Helps with documents

❌ Too generic:

description: For data

❌ Missing triggers:

description: Document processing tool

Description Formula

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.

File Structure Options

Single-File Skill (Simple)

my-skill/
└── SKILL.md

Best for:

• Simple, focused tasks
• Skills with minimal instructions
• Quick utilities

Multi-File Skill (Complex)

my-skill/
├── SKILL.md (required)
├── references/
│   └── detailed-guide.md
├── scripts/
│   └── helper.py
└── assets/
    └── template.txt

Best for:

• Complex workflows requiring detailed documentation
• Skills needing executable scripts for deterministic operations
• Skills that produce output from templates or boilerplate

Resource Types

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 (scripts/)

Executable code (Python/Bash/etc.) for tasks requiring deterministic reliability.

When to include:

• The same code is being rewritten repeatedly
• Deterministic reliability is needed
• Complex operations better handled by dedicated code

Examples: scripts/rotate_pdf.py for PDF rotation, scripts/analyze_data.py for data processing

Benefits:

• Token efficient (may execute without loading into context)
• Deterministic execution
• Reusable across tasks

Note: Scripts may still need to be read by Claude for patching or environment-specific adjustments

References (references/)

Documentation and reference material loaded INTO context as needed to inform Claude's process.

When to include:

• Detailed documentation Claude should reference while working
• Information too detailed for SKILL.md body
• Database schemas, API specifications, domain knowledge
• Company policies, detailed workflow guides

Examples: references/schema.md for database schemas, references/api-docs.md for API specifications, references/policies.md for company guidelines

Benefits:

• Keeps SKILL.md lean and focused
• Loaded only when Claude determines it's needed
• Allows unlimited detailed documentation

Best practice: For large files (>10k words), include grep search patterns in SKILL.md to help Claude find specific information efficiently

Assets (assets/)

Files used IN the output Claude produces, never loaded into context.

When to include:

• Templates that get copied or modified in the output
• Images, icons, fonts, or other media files
• Boilerplate code or starter projects
• Sample documents

Examples: assets/logo.png for brand assets, assets/template.html for HTML templates, assets/boilerplate/ for project starters

Benefits:

• Separates output resources from documentation
• Claude can use files without consuming context window
• Enables consistent output formatting

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
```

Tool Restrictions with allowed-tools

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:

• Read-only Skills that shouldn't modify files
• Skills with limited scope (only analysis, no writing)
• Security-sensitive workflows

When to skip allowed-tools:

• Skills that need full capabilities
• Most general-purpose skills
• Let Claude ask for permission normally

Skill Creation Process

Follow this process when creating a new skill from scratch: