zhongwei/gh-warrenzhu050413-warren-claude-code-plugin-marketplace-claude-context-orchestrator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:05:19 +08:00
commit 09fec2555b
96 changed files with 24269 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

545
skills/managing-skills/updating.md Normal file
View File

@@ -0,0 +1,545 @@
# Updating Skills
Guidance for modifying and maintaining existing Agent Skills in Claude Code.
## Quick Update Process
### 1. Locate the Skill
```bash
# 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
```bash
# 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**:
```yaml
description: Helps with PDFs
```
**After**:
```yaml
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):
```markdown
## Instructions
Process the data and generate output.
```
**After** (specific):
```markdown
## Instructions
1. Load data from CSV file using pandas:
```python
import pandas as pd
df = pd.read_csv('data.csv')
```
2. Clean data:
- Remove null values
- Normalize formats
- Validate ranges
3. Generate summary statistics:
```python
summary = df.describe()
```
4. Export results to Excel:
```python
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:
```python
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):
```markdown
1. Make changes to config.json
2. Deploy application
3. Test in production
```
**After** (with validation loop):
```markdown
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:
```markdown
# 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:
```markdown
## Current Method
Use the v2 API for all new integrations:
```python
from api.v2 import Client
client = Client(api_key="...")
```
## Old Patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API used a different client:
```python
from api.v1 import OldClient # Don't use
```
This API is no longer supported. Migrate to v2.
</details>
```
## Testing Updates
### 1. Verify YAML Syntax
After updating frontmatter:
```bash
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:
```bash
cd ~/.claude/skills/my-skill
# Check that referenced files exist
ls -l *.md
```
### 4. Verify Examples Run
If you added code examples, test them:
```bash
# 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**:
```bash
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**:
```yaml
description: Helps with files
```
**After**:
```yaml
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):
```markdown
# SKILL.md → references advanced.md
# advanced.md → references details.md
# details.md → has the actual info
```
**Good** (one level):
```markdown
# SKILL.md → directly references all docs
- advanced.md
- details.md
- examples.md
```
## Rollback Strategy
### Create Backup Before Major Changes
```bash
# 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
```bash
# 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):
```bash
# 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:
```bash
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:
1. Create feature branch
2. Update skill
3. Test thoroughly
4. Create pull request
5. Have teammate review
6. Merge when approved
7. Team members pull and restart