---
description: "MiniMax M3 + Cursor 3.7 skill authoring: when to use skills, how to structure them, how to keep them deep without duplicating the core, and how to declare model assumptions."
alwaysApply: false
---

# Skill Authoring

Use this rule when creating, revising, or evaluating `.cursor/skills/*` content.

## Rule vs Skill

- Put durable, universal behavior in always-on rules.
- Use a skill for repeatable workflows, domain-specific heuristics, or tasks that need examples and reference material.
- If the content only matters for one file type or one domain, prefer a skill or requestable rule over expanding the core.

## Skill Shape

Each skill should clearly provide:

- what it is for
- when to use it
- what to inspect first
- the workflow or decision sequence
- any output or verification expectations

## Frontmatter Contract

Use YAML frontmatter on every `SKILL.md`.

Minimum:

```yaml
---
name: my-skill
description: >
  What this skill does and the user-language triggers for when to use it.
license: MIT
metadata:
  version: "1.0.0"
  category: workflow
  sources:
    - Official docs or standards
  model_assumptions: []   # optional; see below
---
```

Rules:
- `name` must match the directory name exactly.
- `description` must include concrete trigger language, not vague capability claims.
- `license` should be explicit so skills stay portable outside this repo.
- `metadata.version` should change when the skill meaningfully evolves.
- `metadata.category` should describe the domain or workflow.
- `metadata.sources` should name current authoritative sources when the skill depends on external behavior.
- `metadata.model_assumptions` (optional) should name the model capabilities the skill depends on, e.g.:
  - `multimodal-input: required` — the skill expects the user can attach images/video that the model can read natively
  - `long-context: recommended` — the skill expects a 1M-class context window for the loader to be useful
  - `cursor-3-runtime: required` — the skill expects the Cursor 3.7 / Agents Window surface

## Progressive Disclosure

- Keep `SKILL.md` focused on the main workflow.
- Move large examples, extended references, and category catalogs into companion files such as `reference.md`.
- Load deeper material only when the task actually needs it.

## Skill Contracts

- State concrete triggers in user-language, not vague capability claims.
- Define inputs, outputs, stop conditions, and common failure modes.
- Prefer one coherent workflow per skill over broad omnibus instructions.
- If a skill depends on multimodal input, name that in the frontmatter and in the opening paragraph so the agent does not try to use it in a text-only environment.

## Anti-Duplication

- Do not copy the always-on solver loop, status taxonomy, or generic tool discipline into every skill.
- Let skills deepen the task-specific method, not restate the global contract.
- Reference existing project patterns or rule files when they already cover shared behavior.

## Quality Bar

- Keep the opening concise enough that the agent can quickly decide whether to load the skill.
- Use examples only when they change behavior.
- Re-read the skill after writing it and remove filler, stale tool names, and redundant policy text.
- Prefer one small `SKILL.md` plus optional `reference.md` over one giant omnibus file.
- If the skill references scripts or helper assets, document where outputs go and how success is verified.