Skip to main content
skill CX Codex

create-skill · coco-research — Claude Code skill: what it does, how to install

create-skill guides you through authoring agent skills by defining directory layout, SKILL.md frontmatter, and precise description triggers.

MIT ★ 328 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add coco-research/coco --skill create-skill -a claude-code
Open on GitHub

What create-skill does

This skill walks you through four distinct phases: discovery, design, implementation, and verification. It enforces technical constraints for SKILL.md files, including a 64-character limit on the name, a 1024-character ceiling for the description, and a recommended 500-line limit for the main file. Detailed guides go into separate files like reference.md or examples.md, kept strictly one reference level deep.

Never place files inside ~/.cursor/skills-cursor/ because that folder is strictly reserved for internal editor routines. Instead, the guide routes your configurations either to personal user directories or directly into project repositories.

What it helps with

  • structure a new agent skill directory from scratch
  • write third-person trigger descriptions that activate reliably
  • organize reference files and helper scripts cleanly
  • verify SKILL.md files against core authoring checklists

Example prompts for the agent

  • Help me author a skill for database migrations with helper scripts
  • Review my draft SKILL.md and suggest better trigger phrases
  • Design a project-level skill for reviewing PRs against team guidelines

How to install create-skill

1Skills CLI (Vercel)

npx skills add coco-research/coco --skill create-skill -a claude-code

2Manually: put the files in place

~/.claude/skills/create-skill/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/create-skill/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about create-skill

How to install create-skill in Claude Code?

Run npx skills add coco-research/coco --skill create-skill -a claude-code in your terminal. You can also save the file directly to ~/.claude/skills/create-skill/SKILL.md.

What does create-skill do?

It guides the creation of agent skills by asking key questions about your workflow, choosing an autonomy level, and generating valid markdown structures.

What are the core requirements for skill descriptions?

Descriptions must stay under 1024 characters, use third-person phrasing, and detail both what the skill accomplishes and exact trigger scenarios.

Source text

SKILL.md · MIT
---
name: create-skill
description: Guides users through creating effective Agent Skills for Cursor. Use when the user wants 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.

## 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
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)

---

## 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.

### 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.

**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

| 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 for consistent results.

### Examples Pattern

For skills where output quality depends on seeing examples, provide concrete input/output pairs.

### Workflow Pattern

Break complex operations into clear steps with checklists.

### Feedback Loop Pattern

For quality-critical tasks, implement validation loops.

---

## Skill Creation Workflow

### Phase 1: Discovery
Gather purpose, location, triggers, requirements, existing patterns.

### Phase 2: Design
Draft name, description, outline sections, identify supporting files.

### Phase 3: Implementation
Create directory, write SKILL.md, create reference files and scripts.

### Phase 4: Verification
Check line count, description specificity, terminology consistency, file references.

---

## Summary Checklist

### 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

© coco-research · MIT · coco-research/coco

Similar skills

All skills for Agent setup: memory, context, orchestration →

create-skill by other authors comes first.

create-skill NeoLabHQ create-skill — a skill for Claude Code, Codex, Cursor and other agents that walks through writing a new skill using a TDD approach. CX Codex +1 1,300installs create-skill siviter-xyz create-skill is a Claude Code skill for building or revising skills that add capabilities to an agent. It guides requests about skill structure, instructions, and bundled resources. CX Codex +1 2,800installs create-skill SethGammon create-skill interviews you about a recurring workflow, compiles it into a structured SKILL.md file, and tests it against real project files. CX Codex +1 ★ 937repo stars create-skill aeonfun create-skill turns a one-line description into a finished skill: parses the request, checks for duplicates, researches the APIs and opens a pull request. CX Codex +1 ★ 797repo stars create-skill Samarth Gupta create-skill guides Claude Code through building a skill or slash command by clarifying its purpose and activation scenarios. Use it to draft a new instruction file. CX Codex +1 ★ 276repo stars convex-create-component convex convex-create-component is a Claude Code skill for building reusable Convex components with isolated tables and clear APIs, including extracting backend logic into a self-contained module. CX Codex +1 138,900installs recipe-create-meet-space official googleworkspace recipe-create-meet-space is a Claude Code skill that creates a Google Meet conference and emails the join link. It handles meeting setup and invitations from a development workflow. CX Codex +1 31,000installs create-payment-credential stripe create-payment-credential — a Claude Code skill that pulls payment credentials from a Link wallet and finishes the checkout. Also runs on Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. CX Codex +1 27,200installs create-auth better-auth create-auth — a skill that walks the agent through planning and wiring authentication in a TypeScript/JavaScript app with Better Auth, from codebase scan to sign-in pages. CX Codex +1 15,300installs create-game-assets gamedev-skills The create-game-assets skill for Claude Code plans, generates, and validates consistent game art. It runs when creating sprites, fixing transparency, or auditing assets. CX Codex +1 13,900installs create-prd phuryn create-prd — a skill that generates a concise, decision-ready Product Requirements Document using an eight-section template: summary, contacts, background, objective, market segments, value propositions (JTBD-based), solution, and release. CX Codex +1 11,300installs

From the same set82

The whole set →
database-architect Get database architecture recommendations, data models, and migration plans. Use the subagent when shaping a schema, scaling a system, or splitting data across services. CX Codex ★ 328repo stars tailwind-patterns The tailwind-patterns skill guides Tailwind CSS v4 setup, responsive layouts, and design tokens. Use it when starting a v4 project or moving one from v3. CX Codex +1 ★ 328repo stars c4-architecture c4-architecture generates architecture documentation using C4 model: system context, containers, components and deployment as Mermaid diagrams. CX Codex +1 ★ 328repo stars create-subagent create-subagent helps create isolated subagents with targeted system prompts and YAML configurations for code reviews, debugging, and data tasks. CX Codex +1 ★ 328repo stars ultra-think ultra-think is a Claude Code skill that examines architecture decisions from four viewpoints, compares approaches, and gives one recommendation. CX Codex +1 ★ 328repo stars generate-tests generate-tests writes tests for a file, module or component, after first detecting the project's framework and conventions. CX Codex +1 ★ 328repo stars m0-handoff m0-handoff saves session state into STATE.md and the local M0 daemon so another session or tool picks up right where you stopped. CX Codex +1 ★ 328repo stars goal goal stores a project objective in .goal.md and guides the agent through work that spans sessions. Use it to pick up an active task after a break. CX Codex +1 ★ 328repo stars

Project sponsors

Companies that keep this analytics open