Agent Skills Expert

Expert for creating and managing Claude Code Agent Skills. Helps create skills that follow official specifications, including using Git Submodule + Sparse Checkout for source code references.

📚 Core Concepts

What is an Agent Skill?

Agent Skill is an extensible capability module for Claude Code, containing:

• SKILL.md – Skill definition file (required)
• Supporting files – Documentation, scripts, templates, etc. (optional)
• source/ – Source code reference directory (optional, using git submodule)

Skill Storage Locations

• Personal Skills: ~/.claude/skills/skill-name/
• Project Skills: .claude/skills/skill-name/

🔧 Skill Creation Workflow

1. Basic Skill Structure

skill-name/
├── SKILL.md              # Required: Skill definition
├── examples.md           # Optional: Example code
├── quick-reference.md    # Optional: Quick reference
├── SOURCE_STRUCTURE.md   # Optional: Source structure documentation
├── scripts/              # Optional: Helper scripts
└── source/               # Optional: Source code references
    └── repo-name/        # Git Submodule

2. SKILL.md Specification

---
name: skill-name                    # Required: lowercase letters, numbers, hyphens, max 64 chars
description: Brief description...   # Required: Skill description, max 1024 chars
allowed-tools: Read, Grep, Glob     # Optional: Restrict available tools
---

# Skill Name

## Instructions
Clear usage instructions...

## Examples
Concrete usage examples...

Description Best Practices:

• Explain what the skill does
• Explain when to use the skill
• Include keywords for Claude to discover

3. Adding Source References (Git Submodule + Sparse Checkout)

Step 1: Add Submodule

cd ~/.claude/skills
git submodule add https://github.com/org/repo.git skill-name/source/repo-name

Step 2: Configure Sparse Checkout

cd skill-name/source/repo-name

# Initialize sparse-checkout
git sparse-checkout init --no-cone

# Set content to keep
git sparse-checkout set \
    /README.md \
    /docs/ \
    /src/ \
    /examples/

Step 3: Create SOURCE_STRUCTURE.md

Document the source structure, including:

• Sparse checkout configuration
• Directory structure explanation
• Key file locations
• Maintenance guide

📋 Sparse Checkout Configuration Guide

Principles for Selecting Content to Keep

1. Core source code – Main API implementation
2. Documentation – README, docs directory
3. Examples – examples directory
4. Configuration files – pyproject.toml, package.json, etc.
5. Tests – Test cases showing usage patterns

Content to Exclude

• Large resource files (images, videos)
• Build artifacts
• CI/CD configuration (usually not needed)
• Historical release notes

Common Sparse Checkout Patterns

Python Projects:

git sparse-checkout set \
    /README.md \
    /LICENSE \
    /src/ \
    /docs/ \
    /examples/ \
    /tests/ \
    /pyproject.toml

JavaScript/TypeScript Projects:

git sparse-checkout set \
    /README.md \
    /LICENSE \
    /src/ \
    /docs/ \
    /examples/ \
    /package.json \
    /tsconfig.json

Rust Projects:

git sparse-checkout set \
    /README.md \
    /LICENSE \
    /src/ \
    /docs/ \
    /examples/ \
    /Cargo.toml

🛠️ Maintenance Operations

Update Submodule

cd skill-name/source/repo-name
git pull origin main

Modify Sparse Checkout Configuration

cd skill-name/source/repo-name

# Add new directory
git sparse-checkout add /new-dir/

# Reconfigure
git sparse-checkout set /dir1/ /dir2/ /file.md

View Configuration

cd skill-name/source/repo-name
git sparse-checkout list
du -sh .  # Check size

Troubleshooting Recovery

# Completely reset submodule
cd ~/.claude/skills
git submodule deinit -f skill-name/source/repo-name
rm -rf .git/modules/skill-name/source/repo-name
git submodule update --init skill-name/source/repo-name

# Reconfigure sparse-checkout
cd skill-name/source/repo-name
git sparse-checkout init --no-cone
git sparse-checkout set /directories-to-keep/

📝 Template Files

SKILL.md Template

See templates/SKILL_TEMPLATE.md

SOURCE_STRUCTURE.md Template

See templates/SOURCE_STRUCTURE_TEMPLATE.md

✅ Checklist

Creating New Skill

• Create skill directory mkdir -p ~/.claude/skills/skill-name
• Create SKILL.md (with correct frontmatter)
• Write clear description (include trigger keywords)
• Add usage instructions and examples
• Test that skill is correctly discovered

Adding Source References

• Add git submodule
• Configure sparse-checkout
• Verify reasonable size (typically <100MB)
• Create SOURCE_STRUCTURE.md
• Update source access instructions in SKILL.md
• Commit all changes

Maintenance

• Regularly update submodule
• Check if sparse-checkout configuration is still appropriate
• Update documentation to reflect latest structure

🔗 Related Resources

• GIT_SPARSE_CHECKOUT_TUTORIAL.md – Detailed Sparse Checkout tutorial
• CLAUDE_CODE_SKILL_TUTORIAL.md – Official skill tutorial
• Agent Skills Official Documentation

📊 Existing Skills Reference

Last updated: 2024-12-23