425 lines
8.2 KiB
Markdown
425 lines
8.2 KiB
Markdown
# Reading Skills
|
|
|
|
Guidance for listing, viewing, and inspecting Agent Skills in Claude Code.
|
|
|
|
## Quick Reference
|
|
|
|
### List All Available Skills
|
|
|
|
Ask Claude:
|
|
```
|
|
What skills are available?
|
|
```
|
|
|
|
or
|
|
|
|
```
|
|
List all available skills
|
|
```
|
|
|
|
Claude will show all skills from:
|
|
- Personal skills (`~/.claude/skills/`)
|
|
- Project skills (`.claude/skills/`)
|
|
- Plugin skills (from installed plugins)
|
|
|
|
### View Specific Skill
|
|
|
|
```bash
|
|
# Personal skill
|
|
cat ~/.claude/skills/my-skill/SKILL.md
|
|
|
|
# Project skill
|
|
cat .claude/skills/my-skill/SKILL.md
|
|
|
|
# Open in editor
|
|
code ~/.claude/skills/my-skill/SKILL.md
|
|
```
|
|
|
|
## Filesystem Commands
|
|
|
|
### List Personal Skills
|
|
|
|
```bash
|
|
# List all personal skills
|
|
ls ~/.claude/skills/
|
|
|
|
# List with details
|
|
ls -la ~/.claude/skills/
|
|
|
|
# Show skill names only
|
|
ls -1 ~/.claude/skills/
|
|
```
|
|
|
|
### List Project Skills
|
|
|
|
```bash
|
|
# From project root
|
|
ls .claude/skills/
|
|
|
|
# Find all project skills recursively
|
|
find . -path "*/.claude/skills/*/SKILL.md"
|
|
```
|
|
|
|
### View Skill Metadata
|
|
|
|
Extract name and description from YAML frontmatter:
|
|
|
|
```bash
|
|
# View frontmatter
|
|
head -n 10 ~/.claude/skills/my-skill/SKILL.md
|
|
|
|
# Extract just description
|
|
grep "description:" ~/.claude/skills/my-skill/SKILL.md
|
|
```
|
|
|
|
### Check Skill Structure
|
|
|
|
```bash
|
|
# List all files in skill directory
|
|
ls -la ~/.claude/skills/my-skill/
|
|
|
|
# Show directory tree
|
|
tree ~/.claude/skills/my-skill/
|
|
|
|
# Or without tree command
|
|
find ~/.claude/skills/my-skill/ -type f
|
|
```
|
|
|
|
## Inspection Patterns
|
|
|
|
### View Complete Skill Content
|
|
|
|
```bash
|
|
# View entire SKILL.md
|
|
cat ~/.claude/skills/my-skill/SKILL.md
|
|
|
|
# View with pagination
|
|
less ~/.claude/skills/my-skill/SKILL.md
|
|
|
|
# View with line numbers
|
|
cat -n ~/.claude/skills/my-skill/SKILL.md
|
|
```
|
|
|
|
### View Skill Supporting Files
|
|
|
|
```bash
|
|
# List all markdown files
|
|
ls ~/.claude/skills/my-skill/*.md
|
|
|
|
# View reference file
|
|
cat ~/.claude/skills/my-skill/reference.md
|
|
|
|
# View examples
|
|
cat ~/.claude/skills/my-skill/examples.md
|
|
```
|
|
|
|
### Search Within Skills
|
|
|
|
```bash
|
|
# Search for keyword in specific skill
|
|
grep -r "PDF" ~/.claude/skills/pdf-processing/
|
|
|
|
# Search across all personal skills
|
|
grep -r "authentication" ~/.claude/skills/
|
|
|
|
# Case-insensitive search
|
|
grep -ri "docker" ~/.claude/skills/
|
|
```
|
|
|
|
### Check Skill Size
|
|
|
|
```bash
|
|
# Size of SKILL.md
|
|
wc -l ~/.claude/skills/my-skill/SKILL.md
|
|
|
|
# Total size of skill directory
|
|
du -sh ~/.claude/skills/my-skill/
|
|
|
|
# Detailed size breakdown
|
|
du -h ~/.claude/skills/my-skill/*
|
|
```
|
|
|
|
## Finding Skills
|
|
|
|
### By Name Pattern
|
|
|
|
```bash
|
|
# Find skills with "pdf" in name
|
|
ls ~/.claude/skills/ | grep -i pdf
|
|
|
|
# Find all skills with "processing" in name
|
|
find ~/.claude/skills/ -type d -name "*processing*"
|
|
```
|
|
|
|
### By Description Content
|
|
|
|
```bash
|
|
# Find skills mentioning "Excel"
|
|
grep -l "Excel" ~/.claude/skills/*/SKILL.md
|
|
|
|
# Find skills with "API" in description
|
|
grep "description:.*API" ~/.claude/skills/*/SKILL.md
|
|
```
|
|
|
|
### By Trigger Terms
|
|
|
|
```bash
|
|
# Find which skill handles "docker"
|
|
for skill in ~/.claude/skills/*/SKILL.md; do
|
|
if grep -qi "docker" "$skill"; then
|
|
echo "Found in: $(dirname $skill)"
|
|
grep "description:" "$skill"
|
|
fi
|
|
done
|
|
```
|
|
|
|
## Understanding Skill Structure
|
|
|
|
### Check if Skill Has allowed-tools
|
|
|
|
```bash
|
|
# Check frontmatter for allowed-tools
|
|
head -n 15 ~/.claude/skills/my-skill/SKILL.md | grep "allowed-tools"
|
|
```
|
|
|
|
If present, the skill restricts which tools Claude can use.
|
|
|
|
### Identify Progressive Disclosure
|
|
|
|
```bash
|
|
# Check if skill references other files
|
|
grep -E "\[.*\]\(.*\.md\)" ~/.claude/skills/my-skill/SKILL.md
|
|
|
|
# List referenced files
|
|
ls ~/.claude/skills/my-skill/*.md
|
|
```
|
|
|
|
Skills with multiple .md files use progressive disclosure.
|
|
|
|
### Check for Scripts
|
|
|
|
```bash
|
|
# Check if skill has scripts
|
|
ls ~/.claude/skills/my-skill/scripts/
|
|
|
|
# Check for templates
|
|
ls ~/.claude/skills/my-skill/templates/
|
|
```
|
|
|
|
## Comparing Skills
|
|
|
|
### Compare Two Skill Descriptions
|
|
|
|
```bash
|
|
# View both descriptions
|
|
echo "=== Skill A ==="
|
|
head -n 10 ~/.claude/skills/skill-a/SKILL.md
|
|
|
|
echo "=== Skill B ==="
|
|
head -n 10 ~/.claude/skills/skill-b/SKILL.md
|
|
```
|
|
|
|
### Find Overlapping Skills
|
|
|
|
```bash
|
|
# Check if two skills have similar descriptions
|
|
skill_a_desc=$(grep "description:" ~/.claude/skills/skill-a/SKILL.md)
|
|
skill_b_desc=$(grep "description:" ~/.claude/skills/skill-b/SKILL.md)
|
|
|
|
echo "Skill A: $skill_a_desc"
|
|
echo "Skill B: $skill_b_desc"
|
|
```
|
|
|
|
If descriptions overlap significantly, consider consolidating.
|
|
|
|
### Diff Two Skills
|
|
|
|
```bash
|
|
# Compare skill structures
|
|
diff ~/.claude/skills/skill-a/SKILL.md ~/.claude/skills/skill-b/SKILL.md
|
|
|
|
# Or use a better diff tool
|
|
code --diff ~/.claude/skills/skill-a/SKILL.md ~/.claude/skills/skill-b/SKILL.md
|
|
```
|
|
|
|
## Validation Checks
|
|
|
|
### Verify YAML Frontmatter
|
|
|
|
```bash
|
|
# Check frontmatter syntax
|
|
head -n 15 ~/.claude/skills/my-skill/SKILL.md
|
|
|
|
# Verify required fields present
|
|
head -n 10 ~/.claude/skills/my-skill/SKILL.md | grep -E "(name:|description:)"
|
|
```
|
|
|
|
Required fields:
|
|
- `name:` - Skill name
|
|
- `description:` - What it does and when to use it
|
|
|
|
### Check File Existence
|
|
|
|
```bash
|
|
# Verify SKILL.md exists
|
|
test -f ~/.claude/skills/my-skill/SKILL.md && echo "✓ SKILL.md exists" || echo "✗ SKILL.md missing"
|
|
|
|
# Check for broken references
|
|
for ref in $(grep -oE "\[.*\]\((.*\.md)\)" ~/.claude/skills/my-skill/SKILL.md | grep -oE "\(.*\.md\)" | tr -d '()'); do
|
|
if [ -f "~/.claude/skills/my-skill/$ref" ]; then
|
|
echo "✓ $ref exists"
|
|
else
|
|
echo "✗ $ref missing"
|
|
fi
|
|
done
|
|
```
|
|
|
|
### Validate Description Length
|
|
|
|
```bash
|
|
# Check description character count
|
|
desc=$(grep "description:" ~/.claude/skills/my-skill/SKILL.md | cut -d':' -f2-)
|
|
echo "Description length: ${#desc} characters (max 1024)"
|
|
|
|
if [ ${#desc} -gt 1024 ]; then
|
|
echo "⚠️ Description too long!"
|
|
fi
|
|
```
|
|
|
|
## Organizing Skill Information
|
|
|
|
### Create Skill Inventory
|
|
|
|
```bash
|
|
# Generate list of all skills with descriptions
|
|
for skill in ~/.claude/skills/*/SKILL.md; do
|
|
skill_name=$(dirname $skill | xargs basename)
|
|
description=$(grep "description:" "$skill" | cut -d':' -f2-)
|
|
echo "- **$skill_name**: $description"
|
|
done
|
|
```
|
|
|
|
### Export Skill Documentation
|
|
|
|
```bash
|
|
# Create markdown file with all skill info
|
|
{
|
|
echo "# Personal Skills Inventory"
|
|
echo ""
|
|
for skill in ~/.claude/skills/*/SKILL.md; do
|
|
echo "## $(grep "name:" $skill | cut -d':' -f2-)"
|
|
echo ""
|
|
echo "**Description**: $(grep "description:" $skill | cut -d':' -f2-)"
|
|
echo ""
|
|
echo "**Location**: $skill"
|
|
echo ""
|
|
echo "---"
|
|
echo ""
|
|
done
|
|
} > ~/skills-inventory.md
|
|
```
|
|
|
|
### Generate Skills Summary
|
|
|
|
```bash
|
|
# Count skills by location
|
|
personal_count=$(ls ~/.claude/skills/ 2>/dev/null | wc -l)
|
|
project_count=$(ls .claude/skills/ 2>/dev/null | wc -l)
|
|
|
|
echo "Skills Summary:"
|
|
echo " Personal: $personal_count"
|
|
echo " Project: $project_count"
|
|
echo " Total: $((personal_count + project_count))"
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Skill Not Appearing
|
|
|
|
**Check if file exists**:
|
|
```bash
|
|
ls ~/.claude/skills/my-skill/SKILL.md
|
|
```
|
|
|
|
**Check YAML syntax**:
|
|
```bash
|
|
head -n 10 ~/.claude/skills/my-skill/SKILL.md
|
|
```
|
|
|
|
**Verify location**:
|
|
- Personal: `~/.claude/skills/skill-name/SKILL.md`
|
|
- Project: `.claude/skills/skill-name/SKILL.md`
|
|
|
|
### Cannot Read Skill File
|
|
|
|
**Check permissions**:
|
|
```bash
|
|
ls -la ~/.claude/skills/my-skill/SKILL.md
|
|
|
|
# Fix if needed
|
|
chmod 644 ~/.claude/skills/my-skill/SKILL.md
|
|
```
|
|
|
|
### Skill Directory Empty
|
|
|
|
```bash
|
|
# Check if skills directory exists
|
|
ls -la ~/.claude/skills/
|
|
|
|
# Create if missing
|
|
mkdir -p ~/.claude/skills/
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### Regular Skill Audits
|
|
|
|
Periodically review your skills:
|
|
|
|
```bash
|
|
# List all skills with last modified date
|
|
ls -lt ~/.claude/skills/*/SKILL.md
|
|
|
|
# Find skills not modified in 90 days
|
|
find ~/.claude/skills/ -name "SKILL.md" -mtime +90
|
|
```
|
|
|
|
Consider updating or removing stale skills.
|
|
|
|
### Document Your Skills
|
|
|
|
Maintain a skills inventory:
|
|
|
|
```markdown
|
|
# My Claude Code Skills
|
|
|
|
## Active Skills
|
|
- **pdf-processing**: Extract and manipulate PDFs
|
|
- **data-analysis**: Analyze CSV and Excel files
|
|
- **commit-helper**: Generate git commit messages
|
|
|
|
## Experimental
|
|
- **new-skill**: Testing new approach
|
|
|
|
## Deprecated
|
|
- **old-skill**: Replaced by new-skill
|
|
```
|
|
|
|
### Track Skill Usage
|
|
|
|
Note which skills you use frequently:
|
|
|
|
```markdown
|
|
# Skill Usage Notes
|
|
|
|
## Frequently Used
|
|
- commit-helper (daily)
|
|
- pdf-processing (weekly)
|
|
|
|
## Rarely Used
|
|
- legacy-api (consider removing)
|
|
|
|
## Never Used
|
|
- experiment-1 (delete)
|
|
```
|