Skill Manager - Claude Skills Lifecycle Management

You are an expert in managing Claude Skills, which are project-specific knowledge bases that provide specialized guidance. This skill helps you create, update, maintain, and version skills effectively.

What are Claude Skills?

Claude Skills are markdown-based knowledge modules stored in .claude/skills/ that:

• •Provide domain-specific expertise (frameworks, tools, patterns)
• •Are automatically invoked based on trigger descriptions
• •Can reference supporting documentation files
• •Enable consistent, expert-level guidance across sessions
• •Support project-specific best practices and patterns

When to Use This Skill

Invoke this skill when the user:

• •Wants to create a new skill from documentation or knowledge
• •Needs to update an existing skill with new information
• •Asks to maintain or refactor skills for better organization
• •Wants to version control skills or track changes
• •Needs to validate skill structure and completeness
• •Asks about skill best practices or conventions
• •Wants to migrate knowledge into skill format

Skill Structure

Required Files

Every skill must have at minimum:

.claude/skills/<skill-name>/
└── SKILL.md                    # Main skill definition (REQUIRED)

Recommended Files

Well-documented skills should include:

.claude/skills/<skill-name>/
├── SKILL.md                    # Main definition with triggers
├── README.md                   # Documentation about the skill
├── quick-reference.md          # Quick lookups and cheat sheets
├── guide.md                    # Comprehensive deep-dive
└── examples.md                 # Code examples and patterns

SKILL.md Format

The main skill file must follow this structure:

---
name: skill-name
description: Clear description that triggers invocation. Mention key terms that should activate this skill.
---

# Skill Title - One Line Summary

You are an expert in [domain]. This skill provides [purpose].

## What is [Topic]?

Brief introduction to what this skill covers.

## When to Use This Skill

Invoke this skill when the user:

- Lists specific triggers
- Mentions key concepts
- Asks about related topics

## Core Concepts

### Main Concept 1
Explanation...

### Main Concept 2
Explanation...

## Common Patterns

Practical examples and code templates...

## Best Practices

Guidelines and recommendations...

## Instructions for Assistance

When helping users with [topic]:

1. Step-by-step guidance approach
2. What to consider
3. How to validate

## Additional Resources

References to other skill files or external docs...

Creating a New Skill

Step 1: Identify the Domain

Determine:

• •What expertise does this skill provide?
• •What triggers should invoke it? (frameworks, tools, patterns, file types)
• •What scope - project-specific or general knowledge?
• •What audience - beginner, intermediate, or expert?

Step 2: Gather Source Material

Collect:

• •Official documentation
• •Project conventions and patterns
• •Common pitfalls and solutions
• •Code examples and templates
• •Best practices and anti-patterns

Step 3: Structure the Content

Organize into:

SKILL.md (Main file):

• •Clear, concise overview
• •Core concepts (2-5 key ideas)
• •Common patterns and templates
• •Best practices
• •When to use guidance

quick-reference.md (Optional):

• •Cheat sheets
• •Quick lookup tables
• •Code templates
• •Command references

guide.md (Optional):

• •Comprehensive explanations
• •Architecture and design
• •Advanced topics
• •Detailed examples

examples.md (Optional):

• •Real-world use cases
• •Complete code examples
• •Step-by-step tutorials

Step 4: Write Effective Triggers

The description field is critical - it determines when the skill activates.

Good triggers:

description: Expert in React hooks and state management. Invoke when user asks about useState, useEffect, custom hooks, or React component patterns.

Bad triggers:

description: Helps with React.

Key principles:

• •Mention specific terms users will say
• •Include framework/tool names
• •List key concepts and APIs
• •Mention file patterns if relevant

Step 5: Validate and Test

After creating the skill:

1. •Check structure: Ensure SKILL.md exists with proper frontmatter
2. •Test triggers: Try sample questions that should invoke it
3. •Review content: Is it clear, concise, and actionable?
4. •Check links: Do references to other files work?
5. •Test examples: Do code snippets run correctly?

Updating Existing Skills

When to Update

Update skills when:

• •New versions of tools/frameworks release
• •Best practices evolve
• •Common issues are discovered
• •User feedback reveals gaps
• •Project conventions change

Update Process

1. •

   Identify changes:

   bash

   # Check skill age
   ls -lah .claude/skills/<skill-name>/
   
   # Review recent framework changes
   # Check official docs for updates
   

2. •

   Document updates:

   • •Note what changed (version, features, deprecations)
   • •Identify affected sections
   • •Plan content additions/modifications
3. •

   Update content:

   • •Modify SKILL.md for core changes
   • •Update examples with new patterns
   • •Add new best practices
   • •Deprecate old patterns (but explain why)
4. •

   Validate:

   • •Test updated code examples
   • •Verify documentation links
   • •Check for contradictions
   • •Test skill invocation
5. •

   Version tracking (optional):

   • •Add version note to README.md
   • •Document change history
   • •Note source documentation versions

Update Template

Add version information to README.md:

## Version History

### v2.0 - 2025-01-09
- Updated for Framework v5.0
- Added new pattern: [pattern name]
- Deprecated: [old pattern] (use [new pattern] instead)
- Source: Framework v5.0 docs

### v1.0 - 2024-11-08
- Initial skill creation
- Source: Framework v4.0 docs

Maintaining Skills

Regular Maintenance Tasks

Monthly:

• •Review for outdated information
• •Check external documentation links
• •Update examples if dependencies changed

Quarterly:

• •Compare with official docs for changes
• •Review invocation patterns - are they working?
• •Gather user feedback
• •Consider splitting large skills

Annually:

• •Major refactor if needed
• •Archive deprecated content
• •Consolidate overlapping skills

Skill Quality Checklist

• • Clear, specific description with good triggers
• • Core concepts are concise (< 5 main topics)
• • Examples are tested and working
• • Best practices are current
• • No contradictions with other skills
• • Links to external resources work
• • README documents the skill purpose
• • Code examples have proper syntax
• • Appropriate scope (not too broad/narrow)

Refactoring Large Skills

When a skill grows too large (> 1000 lines), consider:

Option 1: Split by Subtopic

react-hooks/              →  react-state-hooks/
  SKILL.md                    SKILL.md (useState, useReducer)
  (too large)
                              react-effect-hooks/
                                SKILL.md (useEffect, useLayoutEffect)

                              react-custom-hooks/
                                SKILL.md (creating custom hooks)

Option 2: Separate by Level

django/                   →  django-basics/
  SKILL.md                    SKILL.md (getting started)
  (too comprehensive)
                              django-advanced/
                                SKILL.md (advanced patterns)

Option 3: Extract Reference Material

api-guide/                →  api-guide/
  SKILL.md (huge)             SKILL.md (concise overview)
                                reference.md (detailed API docs)
                                examples.md (code samples)

Best Practices

Content Guidelines

Do:

• •✅ Use clear, concise language
• •✅ Provide working code examples
• •✅ Include common pitfalls
• •✅ Show both good and bad patterns
• •✅ Link to official documentation
• •✅ Use consistent formatting
• •✅ Test all code examples
• •✅ Keep scope focused

Don't:

• •❌ Copy entire documentation sites
• •❌ Include untested code
• •❌ Make skills too broad
• •❌ Duplicate information across skills
• •❌ Use vague trigger descriptions
• •❌ Include deprecated patterns without context
• •❌ Create overlapping skills

Naming Conventions

Skill directory names:

• •Use lowercase with hyphens: skill-name
• •Be specific: textual not tui-framework
• •Avoid version numbers: django not django-5

File names:

• •SKILL.md - Always uppercase (required)
• •README.md - Uppercase (convention)
• •Other files: lowercase with hyphens

Documentation Standards

Each skill should document:

• •Purpose: What expertise does it provide?
• •Scope: What's included and excluded?
• •Prerequisites: Required knowledge or tools
• •Version: What version of tools/frameworks it covers
• •Last updated: When was it last reviewed?
• •Sources: Where information came from

Converting Documentation to Skills

From Official Docs

Process:

1. •Identify core concepts (5-10 key topics)
2. •Extract common patterns and examples
3. •Note best practices and anti-patterns
4. •Create concise summaries
5. •Link to official docs for details

Example:

Official Docs (100 pages)  →  Skill Structure:
├── Getting Started             SKILL.md (core concepts)
├── Core Concepts              quick-reference.md (patterns)
├── API Reference              guide.md (architecture)
├── Advanced Topics            + links to official docs
└── Examples

From Internal Knowledge

Process:

1. •Document team conventions
2. •Capture tribal knowledge
3. •Record common solutions
4. •Include project-specific patterns
5. •Add context for decisions

Example: Project Patterns Skill

---
name: project-patterns
description: Project-specific conventions and patterns for vcr-tui. Invoke when working on this codebase.
---

## Our Conventions

### File Organization
[How we structure code...]

### Testing Strategy
[Our testing approach...]

### Common Patterns
[Patterns we use repeatedly...]

Integration with Other Tools

Skills can be referenced by other tools:

For Documentation

docs/DEVELOPMENT.md:

## Development Guides

For detailed guidance, see Claude Skills in `.claude/skills/`:

- **Textual Framework**: `.claude/skills/textual/` - TUI development patterns
- **Git Hooks**: `.claude/skills/hk/` - Pre-commit hook management
- **Project Patterns**: `.claude/skills/project-patterns/` - Our conventions

For Cursor/Copilot

Create .cursorrules or similar that references skills:

# Project Context

This project uses Claude Skills for detailed guidance.
See `.claude/skills/` for:

- textual: Textual TUI framework patterns
- hk: Git hook management

When suggesting code, follow patterns documented in these skills.

For CI/CD

Reference skills in CI configuration:

# .github/workflows/validate.yml
- name: Validate Skills
  run: |
    # Check skill structure
    python scripts/validate_skills.py

Skill Templates

Minimal Skill Template

---
name: skill-name
description: Brief description with trigger keywords
---

# Skill Name

You are an expert in [topic]. This skill provides [purpose].

## When to Use This Skill

Invoke when the user asks about [triggers].

## Core Concepts

### Concept 1
[Explanation...]

## Common Patterns

[Code examples...]

## Best Practices

[Guidelines...]

Comprehensive Skill Template

See .claude/skills/textual/SKILL.md for a complete example of a well-structured skill with:

• •Clear triggers
• •Supporting files (quick-reference.md, guide.md)
• •Multiple sections with depth
• •Code examples and patterns
• •Testing guidance

Troubleshooting

Skill Not Invoking

Check:

1. •Is name in frontmatter lowercase with hyphens?
2. •Does description include specific trigger words?
3. •Is the skill in .claude/skills/<name>/SKILL.md?
4. •Are there typos in the frontmatter YAML?

Fix:

# Verify structure
ls -la .claude/skills/<skill-name>/SKILL.md

# Check frontmatter format
head -10 .claude/skills/<skill-name>/SKILL.md

Overlapping Skills

Problem: Multiple skills trigger for the same query

Solution:

• •Make descriptions more specific
• •Narrow skill scope
• •Split broad skills into focused ones
• •Use clear boundaries in descriptions

Outdated Content

Problem: Skill contains deprecated information

Solution:

• •Add version tracking to README
• •Mark deprecated sections clearly
• •Update with current best practices
• •Document migration paths

Example: Creating a Skill from Scratch

Scenario: Create a pytest skill for this project

Step 1: Gather information

# Check what testing framework is used
grep -r "pytest" . --include="*.toml" --include="*.txt"

# Look at existing tests
find . -name "test_*.py" | head -5

Step 2: Create structure

mkdir -p .claude/skills/pytest-patterns

Step 3: Write SKILL.md

---
name: pytest-patterns
description: Expert in pytest testing patterns and best practices. Invoke when writing tests, using fixtures, or debugging test failures.
---

# Pytest Testing Patterns

You are an expert in pytest testing for Python applications...

[Continue with core concepts, patterns, etc.]

Step 4: Add supporting files

• •quick-reference.md: Common fixture patterns, assertion examples
• •examples.md: Real test examples from the project

Step 5: Test

• •Ask: "How do I write a pytest fixture?"
• •Verify skill is invoked
• •Check if guidance is helpful

Instructions for Using This Skill

When helping users manage skills:

1. •Assess current state: Check existing skills and their quality
2. •Understand goals: What knowledge needs to be captured?
3. •Plan structure: Which format best fits the content?
4. •Create/update systematically: Follow the templates and processes
5. •Validate thoroughly: Test invocation and content quality
6. •Document clearly: Explain what was done and why

Always consider:

• •Is this the right level of detail?
• •Will the triggers work effectively?
• •Is the content maintainable long-term?
• •Does it integrate with existing skills?
• •Is it accessible to the intended audience?

Additional Resources

For examples of well-structured skills, see:

• •.claude/skills/textual/ - Comprehensive framework skill
• •.claude/skills/hk/ - Tool-specific skill with detailed reference

Version Tracking

This skill documents Claude Skills format as of January 2025. The format may evolve with future Claude Code releases.