Cursor rule

1---
2description: "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."
3alwaysApply: false
4---
5 
6# Skill Authoring
7 
8Use this rule when creating, revising, or evaluating `.cursor/skills/*` content.
9 
10## Rule vs Skill
11 
12- Put durable, universal behavior in always-on rules.
13- Use a skill for repeatable workflows, domain-specific heuristics, or tasks that need examples and reference material.
14- If the content only matters for one file type or one domain, prefer a skill or requestable rule over expanding the core.
15 
16## Skill Shape
17 
18Each skill should clearly provide:
19 
20- what it is for
21- when to use it
22- what to inspect first
23- the workflow or decision sequence
24- any output or verification expectations
25 
26## Frontmatter Contract
27 
28Use YAML frontmatter on every `SKILL.md`.
29 
30Minimum:
31 
32```yaml
33---
34name: my-skill
35description: >
36  What this skill does and the user-language triggers for when to use it.
37license: MIT
38metadata:
39  version: "1.0.0"
40  category: workflow
41  sources:
42    - Official docs or standards
43  model_assumptions: []   # optional; see below
44---
45```
46 
47Rules:
48- `name` must match the directory name exactly.
49- `description` must include concrete trigger language, not vague capability claims.
50- `license` should be explicit so skills stay portable outside this repo.
51- `metadata.version` should change when the skill meaningfully evolves.
52- `metadata.category` should describe the domain or workflow.
53- `metadata.sources` should name current authoritative sources when the skill depends on external behavior.
54- `metadata.model_assumptions` (optional) should name the model capabilities the skill depends on, e.g.:
55  - `multimodal-input: required` — the skill expects the user can attach images/video that the model can read natively
56  - `long-context: recommended` — the skill expects a 1M-class context window for the loader to be useful
57  - `cursor-3-runtime: required` — the skill expects the Cursor 3.7 / Agents Window surface
58 
59## Progressive Disclosure
60 
61- Keep `SKILL.md` focused on the main workflow.
62- Move large examples, extended references, and category catalogs into companion files such as `reference.md`.
63- Load deeper material only when the task actually needs it.
64 
65## Skill Contracts
66 
67- State concrete triggers in user-language, not vague capability claims.
68- Define inputs, outputs, stop conditions, and common failure modes.
69- Prefer one coherent workflow per skill over broad omnibus instructions.
70- 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.
71 
72## Anti-Duplication
73 
74- Do not copy the always-on solver loop, status taxonomy, or generic tool discipline into every skill.
75- Let skills deepen the task-specific method, not restate the global contract.
76- Reference existing project patterns or rule files when they already cover shared behavior.
77 
78## Quality Bar
79 
80- Keep the opening concise enough that the agent can quickly decide whether to load the skill.
81- Use examples only when they change behavior.
82- Re-read the skill after writing it and remove filler, stale tool names, and redundant policy text.
83- Prefer one small `SKILL.md` plus optional `reference.md` over one giant omnibus file.
84- If the skill references scripts or helper assets, document where outputs go and how success is verified.
85