> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zapier.com/llms.txt
> Use this file to discover all available pages before exploring further.

> [Meta] How to create, edit, and review Agent Skills for docs.zapier.com. Covers the universal-not-product-specific rule, cross-tool portability (Cursor and Claude), categories, SKILL.md structure, descriptions, and keeping SKILLS-INDEX and AGENTS.md in sync. Use when adding or editing a skill, auditing the skill system, or asking about skill best practices.

# SKILL

# 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](../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.

| Category         | Tag              | Purpose                                              | Examples                                                                                                          |
| ---------------- | ---------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Foundational** | `[Foundational]` | Always apply when writing content                    | writing-standards-dev-docs, accessibility-inclusivity, formatting-guidelines, code-examples, glossary-terminology |
| **Reference**    | `[Reference]`    | Specific guidance on a topic                         | dev-doc-types                                                                                                     |
| **Workflow**     | `[Workflow]`     | Multi-step documentation tasks                       | contribute-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 itself                        | create-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)

```yaml theme={null}
---
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](../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