create-skill

name	create-skill
description	Guides users through creating effective Agent Skills for Cursor. Use when you want to create, write, or author a new skill, or asks about skill structure, best practices, or SKILL.md format.

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.

Default: mirror personal skills everywhere

When the user wants a personal (global) skill—not something checked into a single repo—treat “create this skill” as “create it for Cursor, Claude Code, Codex, and Agents” unless they explicitly narrow scope (examples: “Cursor only”, “don’t touch ~/.agents”, “repo skill only”).

Mirror targets (same directory layout: skill-name/SKILL.md). Write one canonical SKILL.md, then install identical copies under:

#	Path	Load by
1	~/.cursor/skills/skill-name/	Cursor (personal)
2	~/.claude/skills/skill-name/	Claude Code (user)
3	~/.codex/skills/skill-name/	Codex
4	~/.agents/skills/skill-name/	Agents layouts that read ~/.agents/skills

~/.codex/skills/.system/ is bundled—never mirror into .system/; only into sibling skill-name/ folders.

Implementation habit: after authoring SKILL.md, run mkdir -p for each path above and copy the same file (or write once and cp to each root). If a directory does not exist yet, create it—avoid leaving a skill in only one tree.

Default: project skills triple mirror (repo)

When creating a new project skill (checked into a repository), always install the same SKILL.md (and any reference.md / scripts/ siblings) in all of:

#	Path	Tool
1	.cursor/skills/skill-name/	Cursor
2	.claude/skills/skill-name/	Claude Code
3	.agents/skills/skill-name/	Codex (Agents convention in this repo)

Skip a path only when the user explicitly narrows scope (e.g. “Cursor only in this repo”).

kokoro-coreml: .cursor/skills and .agents/skills are symlinks to .claude/skills (see ls -la .cursor/skills .agents/skills). Edit only under .claude/skills/—Cursor and Agents resolve the same files; do not maintain duplicate trees. If either mirror is missing or wrong after a checkout, run scripts/ensure_repo_skill_symlinks.sh from the repo root.

Project skills (repo) do not automatically go under ~/ unless the user asks. In kokoro-coreml, adding a skill means creating it under .claude/skills/ only (Cursor/Agents paths are symlinks). In other repos, use the triple mirror above—one source of truth, identical copies or symlinks.

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: Personal → default mirror everywhere. Project → default triple mirror (.cursor/, .claude/, .agents/); do not install under ~/ unless the user asks. Confirm any explicit single-tool exception before skipping a mirror path.
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—mirror Cursor + Claude + Codex + ~/.agents (default)", "Project—triple mirror .cursor + .claude + .agents (default)", "Single-tool exception (explicit)"]
- "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/	Cursor (repo; shared with team)
Project	.claude/skills/skill-name/	Claude Code (repo; shared with team)
Project	.agents/skills/skill-name/	Codex / Agents (repo; same files as .claude when symlinked)

Project default: When adding a new checked-in skill, create it in Cursor, Claude Code, and Codex locations above (see Default: project skills triple mirror (repo)).

IMPORTANT: Never create your skills in ~/.cursor/skills-cursor/. That directory is for Cursor-shipped defaults (including this create-skill document). Cursor may replace files there on upgrade—if you customize something under skills-cursor, keep a backup or maintain your own copy under ~/.cursor/skills/.

Same skill in Claude Code, Codex, or Agents

Other assistants use their own user-level trees (same layout: skill-name/SKILL.md):

Tool	Typical user skills path	Notes
Claude Code	~/.claude/skills/skill-name/	Repo-specific skills can also live in .claude/skills/ inside a project
Codex	~/.codex/skills/skill-name/	Often alongside ~/.codex/skills/.system/ (bundled); do not edit .system
Agents	~/.agents/skills/skill-name/	Separate tree from Codex; not every install has it

For personal skills, follow Default: mirror personal skills everywhere: repo-agnostic text when the skill should work in any checkout, then identical SKILL.md in each user-level path (not “on request”—unless the user opted out of a tool).

SKILL.md Structure

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

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

# Your Skill Name

## Instructions
Clear, step-by-step guidance for the agent.

## 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 1024 chars, non-empty	Helps agent decide when to apply the skill

---

Writing Effective Descriptions

The description is critical for skill discovery. The agent uses it to decide when to apply your skill.

Description Best Practices

1. Write in third person (the description is injected into the system prompt):

   • ✅ Good: "Processes Excel files and generates reports"
   • ❌ Avoid: "I can help you process Excel files"
   • ❌ Avoid: "You can use this to process Excel files"

2. Be specific and include trigger terms:

   • ✅ Good: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
   • ❌ Vague: "Helps with documents"

3. Include both WHAT and WHEN:

   • WHAT: What the skill does (specific capabilities)
   • WHEN: When the agent should use it (trigger scenarios)

Description Examples

# PDF Processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

# Excel Analysis
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

# Git Commit Helper
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

# Code Review
description: Review code for quality, security, and best practices following team standards. Use when reviewing pull requests, code changes, or when the user asks for a code review.

---

Core Authoring Principles

1. Concise is Key

The context window is shared with conversation history, other skills, and requests. Every token competes for space.

Default assumption: The agent is already very smart. Only add context it doesn't already have.

Challenge each piece of information:

• "Does the agent really need this explanation?"
• "Can I assume the agent knows this?"
• "Does this paragraph justify its token cost?"

Good (concise):

## Extract PDF text

Use pdfplumber for text extraction:

\`\`\`python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
\`\`\`

Bad (verbose):

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but we
recommend pdfplumber because it's easy to use and handles most cases well...

2. Keep SKILL.md Under 500 Lines

For optimal performance, the main SKILL.md file should be concise. Use progressive disclosure for detailed content.

3. Progressive Disclosure

Put essential information in SKILL.md; detailed reference material in separate files that the agent reads only when needed.

# PDF Processing

## Quick start
[Essential instructions here]

## Additional resources
- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

Keep references one level deep - link directly from SKILL.md to reference files. Deeply nested references may result in partial reads.

4. Set Appropriate Degrees of Freedom

Match specificity to the task's fragility:

Freedom Level	When to Use	Example
High (text instructions)	Multiple valid approaches, context-dependent	Code review guidelines
Medium (pseudocode/templates)	Preferred pattern with acceptable variation	Report generation
Low (specific scripts)	Fragile operations, consistency critical	Database migrations

---

Common Patterns

Template Pattern

Provide output format templates:

## Report structure

Use this template:

\`\`\`markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
\`\`\`

Examples Pattern

For skills where output quality depends on seeing examples:

## Commit message format

**Example 1:**
Input: Added user authentication with JWT tokens
Output:
\`\`\`
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
\`\`\`

**Example 2:**
Input: Fixed bug where dates displayed incorrectly
Output:
\`\`\`
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
\`\`\`

Workflow Pattern

Break complex operations into clear steps with checklists:

## Form filling workflow

Copy this checklist and track progress:

\`\`\`
Task Progress:
- [ ] Step 1: Analyze the form
- [ ] Step 2: Create field mapping
- [ ] Step 3: Validate mapping
- [ ] Step 4: Fill the form
- [ ] Step 5: Verify output
\`\`\`

**Step 1: Analyze the form**
Run: \`python scripts/analyze_form.py input.pdf\`
...

Conditional Workflow Pattern

Guide through decision points:

## Document modification workflow

1. Determine the modification type:

   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

2. Creation workflow:
   - Use docx-js library
   - Build document from scratch
   ...

Feedback Loop Pattern

For quality-critical tasks, implement validation loops:

## Document editing process

1. Make your edits
2. **Validate immediately**: \`python scripts/validate.py output/\`
3. If validation fails:
   - Review the error message
   - Fix the issues
   - Run validation again
4. **Only proceed when validation passes**

---

Utility Scripts

Pre-made scripts offer advantages over generated code:

• More reliable than generated code
• Save tokens (no code in context)
• Save time (no code generation)
• Ensure consistency across uses

## Utility scripts

**analyze_form.py**: Extract all form fields from PDF
\`\`\`bash
python scripts/analyze_form.py input.pdf > fields.json
\`\`\`

**validate.py**: Check for errors
\`\`\`bash
python scripts/validate.py fields.json
# Returns: "OK" or lists conflicts
\`\`\`

Make clear whether the agent should execute the script (most common) or read it as reference.

---

Anti-Patterns to Avoid

1. Windows-Style Paths

• ✅ Use: scripts/helper.py
• ❌ Avoid: scripts\helper.py

2. Too Many Options

# Bad - confusing
"You can use pypdf, or pdfplumber, or PyMuPDF, or..."

# Good - provide a default with escape hatch
"Use pdfplumber for text extraction.
For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."

3. Time-Sensitive Information

# Bad - will become outdated
"If you're doing this before August 2025, use the old API."

# Good - use an "old patterns" section
## Current method
Use the v2 API endpoint.

## Old patterns (deprecated)
<details>
<summary>Legacy v1 API</summary>
...
</details>

4. Inconsistent Terminology

Choose one term and use it throughout:

• ✅ Always "API endpoint" (not mixing "URL", "route", "path")
• ✅ Always "field" (not mixing "box", "element", "control")

5. Vague Skill Names

• ✅ Good: processing-pdfs, analyzing-spreadsheets
• ❌ Avoid: helper, utils, tools

---

Skill Creation Workflow

When helping a user create a skill, follow this process:

Phase 1: Discovery

Gather information about:

1. The skill's purpose and primary use case
2. Storage location (personal → confirm default full mirror vs explicit single-tool exception; project → default triple mirror unless explicit exception)
3. Trigger scenarios
4. Any specific requirements or constraints
5. Existing examples or patterns to follow

If you have access to the AskQuestion tool, use it for efficient structured gathering. Otherwise, ask conversationally.

Phase 2: Design

1. Draft the skill name (lowercase, hyphens, max 64 chars)
2. Write a specific, third-person description
3. Outline the main sections needed
4. Identify if supporting files or scripts are needed

Phase 3: Implementation

1. Create the directory structure
2. Write the SKILL.md file with frontmatter
3. Create any supporting reference files
4. Create any utility scripts if needed
5. Personal skills: mirror the skill directory (at minimum SKILL.md; include reference.md / scripts/ if present) to ~/.cursor/skills/, ~/.claude/skills/, ~/.codex/skills/, and ~/.agents/skills/, unless the user specified an exception. Do not stop after the first path.
6. Project skills: mirror to .cursor/skills/, .claude/skills/, and .agents/skills/ at the repository root (identical SKILL.md), unless the user specified an exception. Do not stop after the first path. If .agents/skills symlinks to .claude/skills, confirm the new skill is visible under both paths.

Phase 4: Verification

1. Verify the SKILL.md is under 500 lines
2. Check that the description is specific and includes trigger terms
3. Ensure consistent terminology throughout
4. Verify all file references are one level deep
5. Personal skills: confirm the same SKILL.md exists in every mirror path (no stray single-tool install)
6. Project skills: confirm the same SKILL.md exists under .cursor/skills/, .claude/skills/, and .agents/skills/ (or symlink equivalence for .agents)
7. Test that the skill can be discovered and applied

---

Complete Example

Here's a complete example of a well-structured skill:

Directory structure:

code-review/
├── SKILL.md
├── STANDARDS.md
└── examples.md

SKILL.md:

---
name: code-review
description: Review code for quality, security, and maintainability following team standards. Use when reviewing pull requests, examining code changes, or when the user asks for a code review.
---

# Code Review

## Quick Start

When reviewing code:

1. Check for correctness and potential bugs
2. Verify security best practices
3. Assess code readability and maintainability
4. Ensure tests are adequate

## Review Checklist

- [ ] Logic is correct and handles edge cases
- [ ] No security vulnerabilities (SQL injection, XSS, etc.)
- [ ] Code follows project style conventions
- [ ] Functions are appropriately sized and focused
- [ ] Error handling is comprehensive
- [ ] Tests cover the changes

## Providing Feedback

Format feedback as:
- 🔴 **Critical**: Must fix before merge
- 🟡 **Suggestion**: Consider improving
- 🟢 **Nice to have**: Optional enhancement

## Additional Resources

- For detailed coding standards, see [STANDARDS.md](STANDARDS.md)
- For example reviews, see [examples.md](examples.md)

---

Summary Checklist

Before finalizing a skill, verify:

Core Quality

• Description is specific and includes key terms
• Description includes both WHAT and WHEN
• Written in third person
• SKILL.md body is under 500 lines
• Consistent terminology throughout
• Examples are concrete, not abstract

Structure

• File references are one level deep
• Progressive disclosure used appropriately
• Workflows have clear steps
• No time-sensitive information

Personal (global) skills

• Mirrored to ~/.cursor/skills/, ~/.claude/skills/, ~/.codex/skills/, and ~/.agents/skills/ unless the user explicitly excluded a target

Project (repo) skills

• Identical SKILL.md under .cursor/skills/, .claude/skills/, and .agents/skills/ (or confirm .agents/skills → .claude/skills symlink so one write covers Claude + Codex)

If Including Scripts

• Scripts solve problems rather than punt
• Required packages are documented
• Error handling is explicit and helpful
• No Windows-style paths