agent-skills-expert

Claude Code Agent 技能的创建与管理专家。使用 git 子模块 + sparse-checkout 创建技能以引用源代码，撰写 SKILL.md 并添加恰当的 frontmatter，遵循最佳实践。适用于创建新技能、为技能添加源代码引用或管理技能配置时使用。

SKILL.md

--- frontmatter

name: agent-skills-expert
description: Expert for creating and managing Claude Code Agent Skills. Create skills with git submodule + sparse-checkout for source references, write SKILL.md with proper frontmatter, and follow best practices. Use when creating new skills, adding source references to skills, or managing skill configurations.

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

code

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

yaml

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

bash

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

Step 2: Configure Sparse Checkout

bash

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

•Core source code - Main API implementation
•Documentation - README, docs directory
•Examples - examples directory
•Configuration files - pyproject.toml, package.json, etc.
•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:

bash

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

JavaScript/TypeScript Projects:

bash

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

Rust Projects:

bash

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

🛠️ Maintenance Operations

Update Submodule

bash

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

Modify Sparse Checkout Configuration

bash

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

bash

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

Troubleshooting Recovery

bash

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