create-skill

Files (2)

• SKILL.md
• authoring-guide.md · references/

SKILL.md (first lines)

# Creating Skills in Cursor

This skill guides you through creating effective Agent Skills for Cursor. Skills are markdown files that teach the agent how to perform specific tasks: reviewing PRs using team standards, generating commit messages in a preferred format, querying database schemas, or any specialized workflow.

## Check existing first

**Before creating a skill, check:**

1. **Check for existing skills:**
```bash
ls -la ~/.cursor/skills/*/SKILL.md 2>/dev/null
ls -la .cursor/skills/*/SKILL.md 2>/dev/null
```

2. **Check for similar functionality:**
```bash
grep -r "description:" ~/.cursor/skills/*/SKILL.md 2>/dev/null
```

3. **Consider extending vs creating:**
- Could an existing skill be enhanced?
- Would a rule be more appropriate than a skill?

**Why:** Avoid skill duplication. Skills should have clear, distinct purposes.

## Before You Begin: Gather Requirements

Before creating a skill, gather essential information from the user about:

1. **Purpose and scope**: What specific task or workflow should this skill help with?
2. **Target location**: Should this be a personal skill (~/.cursor/skills/) or project skill (.cursor/skills/)?
3. **Trigger scenarios**: When should the agent automatically apply this skill?
4. **Key domain knowledge**: What specialized information does the agent need that it wouldn't already know?
5. **Output format preferences**: Are there specific templates, formats, or styles required?
6. **Existing patterns**: Are there existing examples or conventions to follow?

### Inferring from Context

If you have previous conversation context, infer the skill from what was discussed. You can create skills based on workflows, patterns, or domain knowledge that emerged in the conversation.

### Gathering Additional Information

If you need clarification, use the AskQuestion tool when available:

```
Example AskQuestion usage:
- "Where should this skill be stored?" with options like ["Personal (~/.cursor/skills/)", "Project (.cursor/skills/)"]
- "Should this skill include executable scripts?" with options like ["Yes", "No"]
```

If the AskQuestion tool is not available, ask these questions conversationally.

---

## Skill File Structure

### Directory Layout

Skills are stored as directories containing a `SKILL.md` file:

```
skill-name/
├── SKILL.md              # Required - main instructions
├── reference.md          # Optional - detailed documentation
├── examples.md           # Optional - usage examples
└── scripts/              # Optional - utility scripts
    ├── validate.py
    └── helper.sh
```

### Storage Locations

| Type | Path | Scope |
|------|------|-------|
| Personal | ~/.cursor/skills/skill-name/ | Available across all your projects |
| Project | .cursor/skills/skill-name/ | Shared with anyone using the repository |

**IMPORTANT**: Never create skills in `~/.cursor/skills-cursor/`. This directory is reserved for Cursor's internal built-in skills and is managed automatically by the system.

### SKILL.md Structure

Every skill requires a `SKILL.md` file with YAML frontmatter and markdown body:

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

# Your Skill Name

## Instructions
Outcomes, constraints, and how to verify. Numbered steps only where order is load-bearing (destructive ops, auth, migrations).

## Examples
Concrete examples of using this skill.
```

### Required Metadata Fields

| Field | Requirements | Purpose |
|-------|--------------|---------|
| `name` | Max 64 chars, lowercase letters/numbers/hyphens only | Unique identifier for the skill |
| `description` | Max 320 chars in kenji (spec max 1024), non-empty | Helps agent decide when to apply the skill |

### Optional fields

Cursor ignores keys it does not list; Claude Code honors all of these. Any other key goes under `metadata`.

| Field | Hosts | Use |
|-------|-------|-----|
| `disable-model-invocation: true` | Cursor, Claude Code | User-initiated rituals. Also keeps the description out of the always-on skill roster that every request pays for. |
| `user-invocable: false` | Claude Code | Reference-only skill; hides the `/` entry. |
| `effort` | Claude Code | `low` / `medium` / `high` / `xhigh` / `max`. Opus 5.5 defaults to `medium`; declare `high` for audit, plan, judge, security, and architecture skills, `low` for mechanical, read-only, or handoff skills. Effort is the thinking control — prose cannot raise or lower it. |
| `context: fork` + `agent: <name>` | Claude Code | Run in a forked context so the output stays out of the main conversation; `agent: Explore` for read-only inventory. |
| `model`, `allowed-tools` | Claude Code | Pin a model; restrict tools. |
| `paths` | Cursor, Claude Code | Globs; the skill applies when matching files are in play. |

---

From kensaurus/skills, MIT.

More from kensaurus/skills