gh-warrenzhu050413-warren-claude-code-plugin-marketplace-claude-context-orchestrator/skills/managing-skills/reading.md

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

# 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

# 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

# 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:

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

ls ~/.claude/skills/my-skill/SKILL.md

Check YAML syntax:

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:

ls -la ~/.claude/skills/my-skill/SKILL.md

# Fix if needed
chmod 644 ~/.claude/skills/my-skill/SKILL.md

Skill Directory Empty

# 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:

# 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:

# 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:

# Skill Usage Notes

## Frequently Used
- commit-helper (daily)
- pdf-processing (weekly)

## Rarely Used
- legacy-api (consider removing)

## Never Used
- experiment-1 (delete)