skill-management

What this skill does

# Skill Management

**IMPORTANT: This skill should be activated BEFORE modifying any skill files!**

You are an expert at creating and maintaining high-quality Claude Code skills. This skill helps you follow best practices and remember to commit changes to the skills repository.

## When to Use This Skill (Read This First!)

### ✅ CORRECT Workflow

**ALWAYS activate this skill FIRST when:**
1. Creating a new skill in `~/.claude/skills/`
2. Editing any existing SKILL.md file
3. Modifying skill-related files (EXAMPLES.md, REFERENCE.md, scripts, etc.)
4. User requests to create, improve, update, review, or refactor a skill
5. Discussing skill quality or effectiveness

**The correct order is:**
```
1. User asks to modify a skill (or you identify need to update one)
2. YOU ACTIVATE THIS SKILL IMMEDIATELY
3. You review best practices and quality checklist
4. You make changes following the guidelines
5. You commit changes to the skills git repository
```

### ❌ INCORRECT Workflow (Anti-pattern)

**NEVER do this:**
```
1. User asks to modify a skill
2. You directly edit the SKILL.md file
3. You commit the changes
4. Later realize you didn't follow best practices
5. You have to redo the changes
```

### Examples of When to Activate

✅ "Can you update the literate-programming skill to be more emphatic?"
   → ACTIVATE THIS SKILL IMMEDIATELY, then plan changes

✅ "Create a new skill for handling API documentation"
   → ACTIVATE THIS SKILL IMMEDIATELY, then design skill

✅ "The code-review skill isn't triggering when it should"
   → ACTIVATE THIS SKILL IMMEDIATELY to review triggers

✅ Any task involving files in ~/.claude/skills/
   → ACTIVATE THIS SKILL IMMEDIATELY

### Remember

- Skills have specific quality requirements and best practices
- Following the checklist prevents having to redo work
- Git commits are REQUIRED after any skill modification
- Skill quality directly affects Claude Code effectiveness

## Original "When to Use" Section

Invoke this skill proactively when:

1. **Creating new skills** - User requests a new skill or you identify a need for one
2. **Modifying existing skills** - Any edit to SKILL.md or related files in `~/.claude/skills/`
3. **Reviewing skills** - User asks to review, improve, or refactor a skill
4. **Skill quality questions** - Discussing skill effectiveness, structure, or best practices
5. **After skill changes** - To verify git commit was performed

## Core Principles (from Claude Code Documentation)

### 1. Conciseness
- Assume Claude is already intelligent
- Only include context Claude doesn't already possess
- Challenge each piece of information for necessity
- Keep SKILL.md under 500 lines
- Split additional content into separate files (REFERENCE.md, EXAMPLES.md, etc.)

### 2. Degrees of Freedom
Match instruction specificity to task fragility:
- **High freedom** (text instructions): Multiple valid approaches exist
- **Medium freedom** (pseudocode/patterns): Preferred patterns with acceptable variation
- **Low freedom** (specific scripts): Operations are fragile, exact sequences required

### 3. Progressive Disclosure
Use referenced files to load content on-demand:
- Keep direct references one level deep from SKILL.md
- Use separate reference files for different domains/features
- Structure long references with table of contents

## Skill Structure Requirements

### YAML Frontmatter (Required)

```yaml
---
name: skill-name-here
description: What this skill does and when to use it. Max 1024 characters.
---
```

**Name requirements:**
- Maximum 64 characters
- Lowercase letters, numbers, and hyphens only
- No reserved words ("anthropic", "claude")

**Description requirements:**
- Maximum 1024 characters
- Non-empty, no XML tags
- Use third-person perspective
- State BOTH what the skill does AND when to use it
- Include specific trigger terms and contexts
- Be explicit about proactive invocation if applicable
- Avoid vague language ("helps with documents")

### Effective Description Pattern

```yaml
description: [What it does]. Use [proactively/when]: (1) [trigger condition],
(2) [keyword/phrase triggers], (3) [context triggers]. [Special instructions].
```

Example:
```yaml
description: Write and analyze literate programs using noweb. Use proactively
when: (1) creating, editing, or reviewing .nw files, (2) user mentions
"literate quality" or "noweb", (3) requests to improve documentation.
This skill should be invoked BEFORE making changes to .nw files.
```

## Three-Level Loading Architecture

**Level 1 - Metadata** (~100 tokens, always loaded):
- YAML frontmatter for discovery

**Level 2 - Instructions** (<5k tokens, loaded when triggered):
- Main SKILL.md body with procedures and best practices

**Level 3 - Resources** (unlimited, accessed as needed):
- Additional files: REFERENCE.md, EXAMPLES.md, FORMS.md
- Python scripts (executed via bash, output only enters context)
- Database schemas, templates, etc.

## Content Guidelines

### Organization Patterns

**Templates**: Provide strict format for critical outputs, flexible guidance for context-dependent work

**Examples**: Show input/output pairs demonstrating desired style and detail level

**Workflows**: Break complex operations into clear sequential steps with checklists

**Feedback loops**: Implement validate-fix-repeat cycles for quality-critical tasks

### Writing Guidelines

- **Use imperative/infinitive form** - Write instructions using verb-first format (e.g., "To accomplish X, do Y" rather than "You should do X"). Maintain objective, instructional language for AI consumption
- **Avoid time-sensitive information** or use "Old Patterns" sections with details tags
- **Maintain consistent terminology** - select one term and use exclusively
- **Use forward slashes** in all paths (never Windows-style backslashes)
- **Provide defaults** for all options rather than excessive choices
- **Justify configuration parameters** - no "magic numbers"
- **Include error handling** in scripts with helpful messages
- **List required packages** and verify availability

### Anti-Patterns to Avoid

- Windows-style paths
- Excessive options without defaults
- Deeply nested file references (keep to one level)
- Assuming tools are pre-installed
- Time-sensitive information without caveats
- Vague activation language
- Loading everything upfront instead of progressive disclosure

## Bundled Resources

Skills can include optional bundled resources organized in three directories:

### scripts/

Executable code (Python/Bash/etc.) for tasks requiring deterministic reliability or repeatedly rewritten operations.

**When to include:**
- Same code is rewritten repeatedly
- Deterministic reliability needed
- Complex operations benefit from pre-tested scripts

**Examples from real skills:**
- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - PDF manipulation utilities
- DOCX skill: `document.py`, `utilities.py` - document processing modules
- This skill: `init_skill.py` - creates new skills from template, `quick_validate.py` - validates skill structure

**Benefits:**
- Token efficient (can execute without loading into context)
- Deterministic behavior
- Reusable across multiple invocations

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

### references/

Documentation and reference material loaded into context to inform Claude's process and thinking.

**When to include:**
- Documentation Claude should reference while working
- Information too lengthy for main SKILL.md
- Domain-specific knowledge, schemas, or specifications

**Examples from real skills:**
- Product management: `communication.md`, `context_building.md` - detailed workflow guides
- BigQuery: API reference documentation and query examples
- Finance: `finance.md` - schemas, `mnda.md` - NDA template, `policies.md` - company policies

**Benefits:**
- Keeps SKILL.md lean and focused
- Loaded only when Claude determines it's needed
- Supports progressive disclo