manage-skills

# Managing Claude Skills

## Before Creating a Skill

### Where does this skill belong?

**Firstloop shared skill** (default assumption):
- Skills for `core` or `monotemplate` plugins
- Improvements to existing shared skills
- → Create a GitHub issue in `firstloophq/claude-code-plugins` (see [meta-skill-management.md](meta-skill-management.md))

**Local project skill**:
- Project-specific workflows
- Custom skills for a single codebase
- User explicitly requests a "local skill"
- → Create directly in `.claude/skills/<skill-name>/SKILL.md`

### Quick Reference

| Scenario | Action |
|----------|--------|
| "Create a skill for monotemplate" | GitHub issue |
| "Improve the crud skill" | GitHub issue |
| "Add a docker skill to the plugin" | GitHub issue |
| "Create a local skill for this project" | Create in `.claude/skills/` |
| "Add a skill just for this repo" | Create in `.claude/skills/` |

## Creating Skills

### Quick Start

Create a skill by making a `SKILL.md` file in `.claude/skills/<skill-name>/`:

```markdown
---
name: my-skill-name
description: Brief description of what this skill does and when to use it.
---

# My Skill Name

## Instructions
[Your instructions here]
```

## Required Structure

Every skill needs:

1. **SKILL.md file** with YAML frontmatter
2. **name field**: lowercase letters, numbers, hyphens only (max 64 chars)
3. **description field**: what the skill does AND when to use it (max 1024 chars)

## Skill Directory Layout

```
.claude/skills/
└── my-skill/
    ├── SKILL.md          # Main instructions (required)
    ├── reference.md      # Additional details (optional)
    └── scripts/          # Utility scripts (optional)
        └── helper.py
```

## Writing the Description

The description is critical for skill discovery. Include:
- What the skill does
- When Claude should use it
- Key trigger words

**Good example:**
```yaml
description: Generate git commit messages by analyzing staged changes. Use when committing code, writing commit mess