---
name: "Package a Cursor SKILL.md (discover → activate → scripts)"
description: "Use when packaging a Cursor SKILL.md (discover → activate → scripts)."
---

# Package a Cursor SKILL.md (discover → activate → scripts)

## When
Use when a workflow needs a folder with SKILL.md, then references/ and scripts/ on demand.

## Stop
Never bloat the body if the Agent skips the skill — fix description first. Never leave Cloud Agents without a repo copy.

## Steps
1. Fast path: in Agent chat type `/create-skill`, describe the workflow, save under `.cursor/skills/<name>/`. `name` must match the folder (lowercase, digits, hyphens).
2. Manual: `mkdir .cursor/skills/your-skill-name/` and write `SKILL.md` with YAML `name` + `description`. Description is the router — name the user phrasings and the output.
3. Project skills: `.cursor/skills/` or `.agents/skills/` (commit them). Personal: `~/.cursor/skills/` or `~/.agents/skills/` (not copied to Cloud Agents / remote workers — bake those into the repo or the worker image).
4. Optional `paths:` globs so the skill only surfaces on matching files. Nested `.cursor/skills/` under `apps/web/` auto-scopes to that subtree.
5. Put repeatable commands in `scripts/` and tell the body when to run them and how to roll back. Keep `SKILL.md` short; dump long reference into `references/`.
6. Acceptance test: run a real task. If the Agent skips the skill, fix `description` before bloating the body. Also loads `.claude/skills/` and `.codex/skills/` for compatibility.

## Load
.cursor/skills/ or .agents/skills/. Optional paths globs.