11 KiB
11 KiB
Updating Skills
Guidance for modifying and maintaining existing Agent Skills in Claude Code.
Quick Update Process
1. Locate the Skill
# Personal skills
ls ~/.claude/skills/*/SKILL.md
# Project skills
ls .claude/skills/*/SKILL.md
# Find specific skill
find ~/.claude/skills -name "SKILL.md" -path "*/my-skill/*"
2. Edit SKILL.md
# Personal
code ~/.claude/skills/my-skill/SKILL.md
# Project
code .claude/skills/my-skill/SKILL.md
3. Apply Changes
Changes take effect the next time Claude Code starts.
If Claude Code is already running: Restart it to load updates.
Common Update Scenarios
Update Description
The description is critical for skill discovery. Update it when:
- Skill's purpose has expanded
- Trigger terms need refinement
- Usage context has changed
Requirements:
- Write in third person
- Include what the skill does AND when to use it
- Add specific trigger terms
- Maximum 1024 characters
Before:
description: Helps with PDFs
After:
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.
Update Instructions
When adding new features or improving clarity:
Before (vague):
## Instructions
Process the data and generate output.
After (specific):
## Instructions
1. Load data from CSV file using pandas:
```python
import pandas as pd
df = pd.read_csv('data.csv')
-
Clean data:
- Remove null values
- Normalize formats
- Validate ranges
-
Generate summary statistics:
summary = df.describe() -
Export results to Excel:
summary.to_excel('output.xlsx')
### Add Examples
Examples improve skill effectiveness. Add input/output pairs:
````markdown
## Examples
**Example 1: Simple Extraction**
Input: PDF with plain text
Output:
```python
import pdfplumber
with pdfplumber.open("document.pdf") as pdf:
for page in pdf.pages:
text = page.extract_text()
print(text)
Example 2: Table Extraction Input: PDF with tables Output:
import pdfplumber
with pdfplumber.open("tables.pdf") as pdf:
for page in pdf.pages:
tables = page.extract_tables()
for table in tables:
# Process table data
pass
### Add or Update allowed-tools
Restrict which tools Claude can use when the skill is active:
**Before** (no restrictions):
```yaml
---
name: Data Analyzer
description: Analyze data files and generate reports
---
```
**After** (read-only):
```yaml
---
name: Data Analyzer
description: Analyze data files and generate reports
allowed-tools: Read, Grep, Glob
---
```
This ensures Claude can't modify files when using this skill.
### Split Large Skills
If SKILL.md exceeds 500 lines, use progressive disclosure:
**Before** (single large file):
```markdown
# PDF Processing
## Basic Text Extraction
[100 lines of content...]
## Advanced Table Extraction
[150 lines of content...]
## Form Filling
[200 lines of content...]
## API Reference
[300 lines of content...]
```
**After** (split into multiple files):
```
pdf-processing/
├── SKILL.md # Overview and quick start
├── tables.md # Table extraction guide
├── forms.md # Form filling guide
└── reference.md # Complete API docs
```
**SKILL.md**:
```markdown
# PDF Processing
## Quick Start
[Brief overview]
## Text Extraction
[Common usage]
## Advanced Features
- **Table Extraction**: See [tables.md](tables.md)
- **Form Filling**: See [forms.md](forms.md)
- **Complete API**: See [reference.md](reference.md)
```
### Update Reference Files
When updating longer reference files (>100 lines), include a table of contents:
```markdown
# API Reference
## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples
## Authentication and Setup
...
## Core Methods
...
```
## Refactoring Patterns
### Make Skills More Concise
Remove unnecessary explanations:
**Before** (too verbose):
```markdown
JSON (JavaScript Object Notation) is a data format that is commonly used
for APIs and configuration files. It uses key-value pairs and is human-readable.
To parse JSON in Python, you'll need to import the json module, which is
part of the standard library so you don't need to install anything extra.
```
**After** (concise):
```markdown
Parse JSON:
```python
import json
with open('data.json') as f:
data = json.load(f)
```
```
### Improve Terminology Consistency
**Before** (inconsistent):
```markdown
Use the API endpoint to send a request to the URL. The route will return...
The path can be accessed via the API...
```
**After** (consistent):
```markdown
Use the API endpoint to send a request. The endpoint will return...
The endpoint can be accessed via...
```
(Always use "API endpoint", never mix with "URL", "route", "path")
### Add Workflows for Complex Tasks
When users struggle with multi-step processes:
````markdown
## Data Analysis Workflow
Copy this checklist and track your progress:
```
Task Progress:
- [ ] Step 1: Load and validate data
- [ ] Step 2: Clean and normalize data
- [ ] Step 3: Perform analysis
- [ ] Step 4: Generate visualizations
- [ ] Step 5: Export results
```
**Step 1: Load and validate data**
```python
import pandas as pd
df = pd.read_csv('data.csv')
assert len(df) > 0, "Data file is empty"
assert not df.isnull().all().any(), "Column has all null values"
```
**Step 2: Clean and normalize data**
[Detailed instructions...]
**Step 3: Perform analysis**
[Detailed instructions...]
**Step 4: Generate visualizations**
[Detailed instructions...]
**Step 5: Export results**
[Detailed instructions...]
Add Feedback Loops
For error-prone operations:
Before (no validation):
1. Make changes to config.json
2. Deploy application
3. Test in production
After (with validation loop):
1. Make changes to config.json
2. **Validate immediately**: `python scripts/validate_config.py`
3. If validation fails:
- Review error messages
- Fix issues in config.json
- Run validation again
4. **Only proceed when validation passes**
5. Deploy to staging
6. Test in staging environment
7. Deploy to production
Version Management
Document Changes
Add a version history section to track updates:
# My Skill
## Version History
- v2.1.0 (2025-10-16): Added batch processing support
- v2.0.0 (2025-10-01): Breaking changes to API
- v1.1.0 (2025-09-15): Added table extraction
- v1.0.0 (2025-09-01): Initial release
## Instructions
...
Deprecate Features
When removing old approaches:
## Current Method
Use the v2 API for all new integrations:
```python
from api.v2 import Client
client = Client(api_key="...")
Old Patterns
Legacy v1 API (deprecated 2025-08)
The v1 API used a different client:
from api.v1 import OldClient # Don't use
This API is no longer supported. Migrate to v2.
Testing Updates
1. Verify YAML Syntax
After updating frontmatter:
cat SKILL.md | head -n 10
Check:
- Opening
---on line 1 - Closing
---before markdown content - Valid YAML (no tabs, correct indentation)
- No special characters in unquoted strings
2. Test Description Changes
If you updated the description, test that Claude uses the skill appropriately:
Ask questions that match your new description and verify Claude activates the skill.
3. Check File References
If you added or renamed reference files, verify links work:
cd ~/.claude/skills/my-skill
# Check that referenced files exist
ls -l *.md
4. Verify Examples Run
If you added code examples, test them:
# Extract and run Python examples
python test_examples.py
Common Update Mistakes
❌ Forgetting to Restart
Problem: Updates don't appear after editing SKILL.md
Solution: Restart Claude Code to load changes
❌ Breaking YAML Frontmatter
Problem: Skill stops working after update
Check:
cat SKILL.md | head -n 10
Common issues:
- Missing closing
--- - Tabs instead of spaces
- Unquoted strings with colons
- Incorrect indentation
❌ Making Description Too Generic
Problem: Skill activates too often or not at all
Before:
description: Helps with files
After:
description: Analyzes log files and system metrics for performance monitoring, debugging, and diagnostics. Use when analyzing logs, system performance, or troubleshooting issues.
❌ Adding Too Much Content
Problem: SKILL.md becomes >500 lines
Solution: Use progressive disclosure:
- Keep core instructions in SKILL.md
- Move detailed content to separate reference files
- Link to reference files from SKILL.md
❌ Nested References
Problem: Claude doesn't find information in deeply nested files
Bad (too deep):
# SKILL.md → references advanced.md
# advanced.md → references details.md
# details.md → has the actual info
Good (one level):
# SKILL.md → directly references all docs
- advanced.md
- details.md
- examples.md
Rollback Strategy
Create Backup Before Major Changes
# Backup entire skill
cp -r ~/.claude/skills/my-skill ~/.claude/skills/my-skill.backup
# Or just backup SKILL.md
cp ~/.claude/skills/my-skill/SKILL.md ~/.claude/skills/my-skill/SKILL.md.backup
Restore from Backup
# Restore entire skill
rm -rf ~/.claude/skills/my-skill
mv ~/.claude/skills/my-skill.backup ~/.claude/skills/my-skill
# Or just restore SKILL.md
mv ~/.claude/skills/my-skill/SKILL.md.backup ~/.claude/skills/my-skill/SKILL.md
Use Version Control
For project skills (in git repositories):
# See what changed
git diff .claude/skills/my-skill/SKILL.md
# Revert changes
git checkout .claude/skills/my-skill/SKILL.md
# Commit updates
git add .claude/skills/my-skill/
git commit -m "Update my-skill: add batch processing support"
Team Collaboration
Communicate Changes
For project skills, notify team members:
git commit -m "Update PDF skill: add form filling capability
- Added form filling workflow
- Updated description to include 'forms' trigger
- Added forms.md reference guide
Team members should restart Claude Code to get updates."
git push
Review Process
For shared skills, consider a review process:
- Create feature branch
- Update skill
- Test thoroughly
- Create pull request
- Have teammate review
- Merge when approved
- Team members pull and restart