meta
- Repo stars 330
- License MIT
- Author repo claude-skill-registry
- Domain
- Data
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @majiayu000 · MIT
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Env read
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Description examples
❌ Bad: "Helps with data" ✅ Good: "Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with .xlsx files." ❌ Bad: "Manages configuration" ✅ Good: "Read and update YAML/JSON config files. Use when modifying settings, environment variables, or application configuration."
# Writing effective Claude Code skills
## Required structure
```
skill-name/
├── SKILL.md (required)
├── reference.md (optional)
├── scripts/ (optional)
└── templates/ (optional)
```
## SKILL.md frontmatter
```yaml
---
name: lowercase-with-hyphens
description: Explain WHAT it does AND WHEN to use it. Include trigger terms users would say.
allowed-tools: [Read, Write, Bash] # optional: restrict permissions
---
```
## Critical best practices
1. **Keep skills focused** - one capability per skill
2. **Write specific descriptions** - include actual terms users would mention
3. **Test activation** - verify Claude invokes it when expected
4. **Use allowed-tools** - restrict permissions for security
## Description examples
❌ Bad: "Helps with data"
✅ Good: "Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with .xlsx files."
❌ Bad: "Manages configuration"
✅ Good: "Read and update YAML/JSON config files. Use when modifying settings, environment variables, or application configuration."
## Debugging checklist
If Claude doesn't use your skill:
- Description lacks trigger terms users would say
- YAML syntax errors (check `---` markers, indentation)
- Description not specific enough about WHEN to use it
- Wrong file path or permissions
### Finding and fixing frontmatter issues
**Check if frontmatter exists:**
```bash
# View first 10 lines of SKILL.md
head -10 ~/.claude/skills/*/SKILL.md
```
**Common frontmatter problems:**
1. **Missing frontmatter block** - File starts with `#` instead of `---`
- Fix: Add YAML block at top of file
2. **Missing closing `---`** - Only one `---` marker
- Fix: Ensure both opening and closing markers exist
3. **Missing required fields** - No `name:` or `description:`
- Fix: Add both required fields
4. **Wrong indentation** - YAML is indentation-sensitive
- Fix: Use 2 spaces, no tabs
5. **Missing description trigger terms** - Generic description
- Fix: Add specific keywords users would say
**Validation script:**
```bash
# Check all skills for frontmatter
for skill in ~/.claude/skills/*/SKILL.md; do
echo "=== $skill ==="
if head -1 "$skill" | grep -q "^---$"; then
echo "✓ Has frontmatter"
else
echo "✗ Missing frontmatter"
fi
done
```
## Systematic skill debugging workflow
When debugging skills that aren't working:
1. **List all skills** - Verify skill exists
```bash
ls -la ~/.claude/skills/
```
2. **Check frontmatter** - Validate YAML structure
```bash
head -10 ~/.claude/skills/skill-name/SKILL.md
```
3. **Verify required fields** - Ensure name and description exist
- `name:` must match directory name
- `description:` must include trigger terms
4. **Test description specificity** - Does it explain WHEN to use?
- Include file types, actions, or domain terms
- Avoid generic phrases like "helps with" or "manages"
5. **Check allowed-tools** - If restricted, verify needed tools included
```yaml
allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
```
6. **Review content** - Ensure instructions are clear and actionable
## Skills vs slash commands
**Use skills for:**
- Complex workflows with multiple files
- Automatic contextual invocation
- Comprehensive capabilities
**Use slash commands for:**
- Simple single prompts
- Manual explicit control
- Quick frequently-used operations
Sections and files
Listed in source order.
sections -> Required structure → SKILL.md frontmatter → Critical best practices → Description examples → Debugging checklist → Finding and fixing frontmatter issues
terms -> Keep skills focused · Write specific descriptions · Test activation · Use allowed-tools · Check if frontmatter exists · Common frontmatter problems · Missing frontmatter block · Missing closing ---
files/cmd -> --- · instead of · name: · description:
body sha256 -> 5f4f99846580
Critical best practices
Keep skills focused - one capability per skill Write specific descriptions - include actual terms users would mention Test activation - verify Claude invokes it when expected Use allowed-tools - restrict permissions for security
Description examples
❌ Bad: "Helps with data" ✅ Good: "Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with .xlsx files." ❌ Bad: "Manages configuration" ✅ Good: "Read and update YAML/JSON config files. Use when modifying settings, environment variables, or application configuration."
Debugging checklist
If Claude doesn't use your skill: Description lacks trigger terms users would say YAML syntax errors (check
---markers, indentation) Description not specific enough about WHEN to use it Wrong file path or permissionsFinding and fixing frontmatter issues
Check if frontmatter exists: Common frontmatter problems: Missing frontmatter block - File starts with
#instead of---Fix: Add YAML block at top of file Missing closing---- Only one---markerSystematic skill debugging workflow
When debugging skills that aren't working: List all skills - Verify skill exists Check frontmatter - Validate YAML structure Verify required fields - Ensure name and description exist
name:must match directory name