Skip to main content

​
Create and edit skills

How to create and maintain Agent Skills in this repo’s .cursor/skills/ system so they work coherently and stay portable across tools. The single source of truth for what exists is SKILLS-INDEX.md.

​
When to use

  • Creating a new skill or editing an existing one
  • Auditing the skill system for duplicates, overlaps, or conflicts
  • Asking about skill structure, descriptions, or best practices
  • Updating SKILLS-INDEX or the repo-root AGENTS.md after a change

​
Two hard rules for this repo

  1. Skills are universal, never product-specific. Every skill must apply across all of docs.zapier.com — integrations, SDK, MCP, Powered by Zapier, and white-label. Do not create a “write the SDK docs” or “write the MCP docs” skill. If guidance only applies to one section, fold it into a universal skill as a clearly scoped subsection instead.
  2. Skills must be tool-agnostic (Cursor + Claude). The same SKILL.md is used in both tools, so:
    • Do not name tool-specific tools in the body (write “read the file”, “run pnpx mintlify broken-links”, not “use the Read tool”).
    • Use standard frontmatter only (name, description).
    • Route entry through AGENTS.md; keep cross-links relative.
    • Put any executable logic in scripts/.

​
Cross-tool distribution

Skills are authored once in .cursor/skills/ and mirrored to .claude/skills/ so Cursor and Claude users share one source of truth.
  • After adding or editing a skill, run pnpm run sync-skills to mirror .cursor/skills/ into .claude/skills/.
  • The sync is additive: it copies the universal skills and leaves other Claude-only skills in place.
  • CLAUDE.md imports AGENTS.md, so the router and standards load in both tools.

​
Keep skill folders flat — do not nest

Put every skill directly under .cursor/skills/<skill-name>/ — do not group skills inside category subfolders. Claude Code only discovers skills at the top level of .claude/skills/; a skill nested under a category folder (e.g. templates/template-tutorial/) would never be found in Claude. Folders also do not affect skill routing in either tool — the model selects a skill from its name and description, never its path. Organize by the category tag in the description and the naming prefix instead (see below).

​
Categories

A skill’s category is conveyed by the tag at the start of its description (and the template-* naming prefix for templates), not by a folder.
CategoryTagPurposeExamples
Foundational[Foundational]Always apply when writing contentwriting-standards-dev-docs, accessibility-inclusivity, formatting-guidelines, code-examples, glossary-terminology
Reference[Reference]Specific guidance on a topicdev-doc-types
Workflow[Workflow]Multi-step documentation taskscontribute-docs
Template[Template]Page-type structure with starter .mdx in assets/template-tutorial, template-how-to, template-concept, template-reference
Meta[Meta]About the skill system itselfcreate-edit-skills
Before creating a skill, read SKILLS-INDEX and decide which category it belongs to. If it overlaps an existing skill, extend that skill or split scope by trigger rather than duplicating.

​
File structure and naming

  • Path: .cursor/skills/<skill-name>/SKILL.md — flat, one folder per skill, no category nesting.
  • Folder: kebab-case, no spaces or capitals (e.g. code-examples).
  • Main file: exactly SKILL.md.
  • Optional: references/ for long detail, scripts/ for runnable helpers, assets/ for example .mdx.
  • Keep SKILL.md under ~500 lines; move long material to references/.

​
Frontmatter (required)

---
name: your-skill-name
description: "[Category] What it does. Use when [trigger phrases or scenarios]."
---
  • name: kebab-case, matches the folder.
  • description: includes (1) what it does and (2) when to use it; under 1024 characters; no angle brackets; leads with the category tag. If a skill should not fire in some cases, say so.

​
Body

Use clear Markdown. Recommended sections: When to use, then Instructions / Workflow (numbered steps, tables, or decision trees), Examples, and Related. Put critical rules at the top. Link to other skills with ../<skill-name>/SKILL.md, to a rule with ../../rules/<rule>.mdc, and to the index with ../SKILLS-INDEX.md.

​
Finding best practices

When creating, editing, or auditing skills, you may search the web for current guidance. Be discerning about sources:
  1. Primary — Anthropic / Claude: official Agent Skills documentation and guides. Treat as authoritative when sources disagree.
  2. Secondary — Cursor: adopt only portable, interoperability-friendly guidance (SKILL.md format, frontmatter, markdown). Do not adopt Cursor-only features that would lock skills to one tool.
  3. Other: only when clearly aligned with the above (open standards, portable formats).

​
Keeping the system coherent

When you add, rename, or remove a skill:
  1. Update the correct category table in SKILLS-INDEX.md and the Quick Reference table.
  2. Update the relevant table in the repo-root AGENTS.md (workflow, standards, doc-type, or reference).
  3. Add cross-references from related skills (a new foundational skill should be linked from the others that apply it; a new workflow from AGENTS.md).
  4. Run pnpm run sync-skills.

​
Auditing the system

When asked to review the system, map all skills, then check for duplicates, overlaps, conflicts, and out-of-date index entries. Present each finding with a concrete suggestion and get agreement before applying — work one item at a time, do not batch-apply.

​
Checklist before finalizing

  • Skill is a flat folder under .cursor/skills/; folder is kebab-case; SKILL.md named exactly
  • Frontmatter has name + description with a category tag; no angle brackets
  • Skill is universal (not product-specific) and tool-agnostic
  • One category; no duplicate scope; triggers distinct
  • Cross-links (../<skill>/SKILL.md) resolve
  • SKILLS-INDEX and AGENTS.md updated
  • pnpm run sync-skills run