Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

create-skill

Create Cursor Agent Skills. Use when authoring a new skill or asking about SKILL.md structure.

thedesignproject · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add thedesignproject/agent-skills --skill create-skill

About this skill


name: create-skill description: >- Create Cursor Agent Skills. Use when authoring a new skill or asking about SKILL.md structure.

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.

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?

Verbatim text from the user

If the user includes exact wording to use in the skill, respect it and use it verbatim in SKILL.md (same words, same order). Do not paraphrase, soften, or expand their copy, and do not add unrequested headings or commentary around it.

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

TypePathScope
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:

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

# Your Skill Name

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

## Examples
Concrete examples of using this skill.

Default disable-model-invocation: true so the skill only loads when named explicitly. Omit it only when the agent should auto-invoke from ambient context.

Required Metadata Fields

FieldRequirementsPurpose
nameMax 64 chars, lowercase letters/numbers/hyphens onlyUnique identifier for the skill
descriptionMax 1024 chars, non-emptyHelps 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()
\`\`
Read the complete source ↗