Skills are **maps, not territory**. They load relevant knowledge into context at the right moment without bloating the initial system prompt. A skill should provide enough context to work effectively without trying to be comprehensive documentation.

- **Purpose**: Progressive disclosure - load context on demand

- **Length**: Usually 60-100 lines of focused content

- **Structure**: Minimal front matter, practical content, pointers to where knowledge lives

**Project-specific skills** (in repository `.claude/skills/`):

- Live in this project's repository

- Scope: Document this project's specific patterns, tools, and conventions (not generic best practices)

- Freely create, update, and maintain these skills

- To see what's available: `ls -la .claude/skills/`

**Globally-installed skills** (system-wide):

- Broader scope: Generic tools and workflows

- May be used across different projects and harnesses

**Finding a skill's base path**: When you invoke any skill, the skill harness prints the base directory at the start (e.g., "Base directory for this skill: /path/to/skill-name"). Use this to navigate to and edit the skill's files.

**Workflow for improving skills**:

- **Project-specific skills**: Update directly as needed to improve the project

- **Globally-installed skills**: Suggest improvements to the user and ask for confirmation before modifying, since these skills may be used across different projects and environments

Create a project-specific skill when:

- Multiple agents will benefit from the same specialized knowledge

- The knowledge is project-specific (not generic tutorials)

- It addresses a common workflow or pattern (testing, i18n, deployment, etc.)

- It would otherwise be repeated across multiple system prompts

Update a project-specific skill when:

- Important patterns or workflows change

- Configuration files are updated

- New project conventions are established

- Existing guidance is incorrect or outdated

- **DO**: "Study existing tests in `spec/controllers/` to understand patterns"

- **DON'T**: Include code examples that can become outdated

- **Exception**: Very short, unchanging snippets (bash commands, command syntax) are OK

- **Why**: Live code is authoritative; examples rot

- **DO**: Point to files where patterns are defined (`spec/rails_helper.rb`, `playwright.config.ts`, etc.)

- **DO**: Note important configuration details from actual files

- **DON'T**: Include line numbers (they change, create false precision)

- **Why**: Readers can verify and understand context

- **Before writing**: Read actual configuration files and code

- **When uncertain**: Check the implementation rather than making assumptions

- **Test claims**: Ensure stated behavior matches actual behavior

- **Why**: Misinformation spreads through skills; verification prevents it

- **DO**: Use more words if it increases clarity

- **DO**: Distinguish between similar concepts clearly

- **DON'T**: Sacrifice precision for snappiness

- **Why**: "Queuing without executing" is clearer than "just queuing them"

- **DO**: Document how YOUR project does things ("we access helpers via App getters")

- **DON'T**: Include generic best practices ("separate your concerns")

- **DO**: Explain implementation details that aren't obvious from code

- **Why**: Generic advice is everywhere; project specifics are valuable

- **DO**: Say "study X to understand conventions"

- **DO**: Explain where to find patterns ("study existing files in in `spec/controllers/`")

- **DON'T**: Prescribe rules as if they're laws

- **Why**: Real learning happens when agents explore actual code

name: skill-name

```

**Important**: The `name` must exactly match the folder name (e.g., folder `playwright-testing` → name `playwright-testing`).

- **Start with context** - What is this skill about? When should it be used? What problems does it solve?

- **Organize by workflow or concept** - Use clear section headers, group related information, build from simple to complex

- **Point to implementation** - Reference actual files, directories, and where configuration lives

- **Suggest what to study** - Direct readers to real code patterns before working

- **End with important details** - Configuration notes, common patterns, edge cases, or constraints

1. **Over-Specification** - Don't include line numbers or overly specific implementation details that will change. Point to files and patterns instead.

2. **Stale Examples** - Don't include code examples in the body. Point readers to actual implementations to study.

3. **Generic Advice** - Don't include universal best practices. Document domain-specific patterns and conventions.

4. **Missing Context** - Always clarify why something is done a certain way, not just what to do.

5. **Ignoring Reality** - Verify all claims against actual code before writing. Misinformation spreads through skills.

1. **Study existing skills** - Before creating a new skill, review existing skills in the project to understand conventions, style, and structure. This ensures consistency and prevents duplicating existing content.

2. **Understand the domain** - Study existing code, configuration, and patterns in the project

3. **Identify scope** - What specific knowledge should this skill contain?

4. **Map to sources** - Where in the codebase or documentation does this knowledge live?

5. **Write minimally** - What's the smallest amount of context needed?

6. **Verify claims** - Check that everything stated matches reality by reading actual code

7. **Cite sources** - Point readers to where they can learn more (files, directories, configurations)

8. **Study-driven guidance** - Direct people to real implementations, don't prescribe rules

Skills should be updated when:

- Configuration files change (update file references, configuration notes)

- Patterns evolve (update guidance on how things are done)

- New tools or approaches are adopted (add sections for new workflows)

- Guidance is found to be incorrect (verify, fix, and understand why it was wrong)

Always verify changes against actual code before updating a skill.