Playbook: Add a Skill
Skills convert repeated AI instructions into a reusable, token-efficient document. When you find yourself typing the same guidance to the AI more than once a day, that's a skill.
When to Create a Skill
Create a skill when:
- You repeat the same instructions daily or more often
- A workflow has 3+ distinct steps that the AI needs to know
- A domain has specific 3Lens commands, file patterns, or contract references
- You want a named entry point in Cursor Settings → Skills
Criterion: "If you keep typing the same instructions, it's a skill."
Skill File Structure
Create the file at: .cursor/skills/[name]-operations/SKILL.md
# Skill: [Name] Operations
[One sentence: what this skill is for.]
## When to Use This Skill
- [Scenario 1]
- [Scenario 2]
## Prerequisites
- [Tool or context required]
## Workflow
### Step 1: [Action]
[Description]
```bash
[command]
Step 2: [Action]
[Description]
Examples
Example: [Scenario name]
[example commands]
Key Rules
- [Rule 1]
- [Rule 2]
Related Resources
- Commands:
.cursor/commands/[related].md - Contracts:
.cursor/contracts/[relevant].md - Skills: [cross-references]
---
## Step-by-Step
### 1. Identify the repeated task
Write one sentence describing what you keep doing.
Example: "I keep running trace commands and asking the AI to interpret the output."
### 2. Name the skill
Use the format `[domain]-operations`. Keep it lowercase with hyphens.
Examples: `analytics-operations`, `deploy-operations`, `asset-operations`
### 3. Create the directory and file
.cursor/skills/[name]-operations/SKILL.md
### 4. Fill in the SKILL.md
Minimum required sections:
- **When to Use This Skill** — specific trigger scenarios
- **Workflow** — numbered steps with commands
- **Examples** — at least one concrete example
- **Related Resources** — links to contracts and commands
### 5. Add to the Skills README
Add an entry to `.cursor/skills/README.md`:
```markdown
- **[name]-operations** – [one-line description]
6. (Optional) Add a command shortcut
If the skill has a primary CLI command, create .cursor/commands/[name].md:
# Command: [Name]
[Description]
## Usage
```bash
[command with common flags]
---
## Existing Skills for Reference
| Skill | Domain |
|-------|--------|
| `analytics-operations` | Interpreting trace/query output |
| `diff-operations` | Comparing traces and frames |
| `trace-operations` | Recording and replaying traces |
| `query-operations` | Running analytical queries |
| `validation-operations` | Contract validation |
| `scaffold-operations` | Generating boilerplate |
| `inspector-operations` | Navigating entities |
---
## Related Resources
- Skills directory: `.cursor/skills/`
- Commands directory: `.cursor/commands/`
- Worktree docs: `.cursor/README.md`