{
  "id": "cursor-rules-that-load",
  "type": "loadout",
  "title": "Cursor rules that load",
  "summary": "How to decide between AGENTS.md, Cursor .mdc rules, skills and hooks, write front matter that loads, and check that a rule is really attached.",
  "description": "Most ignored rules are not ignored: they never loaded. Common causes are globs written as a YAML list, alwaysApply set\nalongside globs, descriptions that do not say when to use the rule, and legacy .cursorrules files. This loadout gives your agent a\ndecision table for where an instruction belongs, the four Cursor rule types with correct front matter, Copilot applyTo\nequivalents, and a skill that writes a rule and checks it attaches.\n",
  "highlights": [
    "Decision table: AGENTS.md vs scoped rule vs skill vs hook",
    "The four .mdc rule types with front matter that works",
    "Fix list for rules that never attach",
    "Copilot .instructions.md applyTo equivalent",
    "Auto-attached meta-rule for editing rules"
  ],
  "version": "1.0.0",
  "license": "MIT",
  "author": {
    "name": "Agent Loadout",
    "url": "https://loadout.jnw-it.com"
  },
  "credits": [
    {
      "title": "@iPuneetSingh: .mdc rule types and globs in practice",
      "url": "https://x.com/iPuneetSingh/status/2096461210594267540"
    },
    {
      "title": "Cursor docs: rules",
      "url": "https://cursor.com/docs/rules"
    },
    {
      "title": "GitHub docs: path-specific custom instructions",
      "url": "https://docs.github.com/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot"
    }
  ],
  "categories": [
    "ai-agents",
    "workflow"
  ],
  "stacks": [
    "any"
  ],
  "files": [
    {
      "path": "AGENTS.md",
      "role": "instructions",
      "description": "Where instructions belong and how Cursor rule types load.",
      "skill": null,
      "agent": null,
      "install_to": {
        "claude-code": "AGENTS.md",
        "codex": "AGENTS.md",
        "cursor": "AGENTS.md",
        "gemini-cli": "AGENTS.md",
        "antigravity-cli": "AGENTS.md",
        "copilot": "AGENTS.md"
      },
      "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/AGENTS.md",
      "raw_latest_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/latest/AGENTS.md",
      "bytes": 1883,
      "lang": "markdown",
      "content": "# AGENTS.md: writing agent rules that actually load\n\nRules only help if the agent loads them at the right moment. Decide where each instruction goes before writing it.\n\n## Pick the container\n| Instruction | Put it in |\n|---|---|\n| Applies to every task (build/test commands, hard constraints) | `AGENTS.md` |\n| Applies to some files (`*.tsx`, `migrations/**`) | Cursor rule with `globs`; Copilot `.instructions.md` with `applyTo`; or a nested `AGENTS.md` |\n| A procedure used sometimes (release, migration, triage) | A skill: `.agents/skills/<name>/SKILL.md` |\n| Must never happen (force-push, reading `.env`) | A hook or permission deny rule. Text rules are advice; hooks enforce |\n\n## Cursor rule types (`.cursor/rules/*.mdc`)\nFront matter has three keys only: `description`, `globs`, `alwaysApply`.\n- Always: `alwaysApply: true`. Use for very few rules; each costs context in every chat.\n- Auto-attached: `globs: src/**/*.tsx` and `alwaysApply: false`. Loads when a matching file is in context.\n- Agent-requested: `description` set, no `globs`, `alwaysApply: false`. The agent reads the description and decides; write the description as \"Use when …\".\n- Manual: no description, no globs. Loads only when someone types `@rule-name`.\n\n## Writing rules\n- One topic per rule file, under ~60 lines. Imperative sentences. Show the exact command or code shape.\n- Say what to do, not only what to avoid. Pair each \"never\" with the alternative.\n- Do not restate defaults the agent follows anyway.\n- `.cursorrules` is legacy. Move its content into `.cursor/rules/` or `AGENTS.md` and delete it.\n- `.cursor/rules` does not apply to Bugbot code review; review rules go in `.cursor/BUGBOT.md`.\n- Long rules that are really procedures become skills. Cursor's `/migrate-to-skills` converts agent-requested rules.\n\nUse the `write-cursor-rule` skill to add or fix a rule, and test that it loads.\n"
    },
    {
      "path": "CLAUDE.md",
      "role": "adapter",
      "description": "Imports AGENTS.md for Claude Code.",
      "skill": null,
      "agent": "claude-code",
      "install_to": {
        "claude-code": "CLAUDE.md",
        "codex": null,
        "cursor": null,
        "gemini-cli": null,
        "antigravity-cli": null,
        "copilot": null
      },
      "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/CLAUDE.md",
      "raw_latest_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/latest/CLAUDE.md",
      "bytes": 382,
      "lang": "markdown",
      "content": "# CLAUDE.md\n\n@AGENTS.md\n\n## Claude Code notes\n- Skills from this loadout live in `.claude/skills/`: `write-cursor-rule`. Use them when their description matches the task.\n- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.\n\n<!-- From the Agent Loadout \"Cursor rules that load\" v1.0.0 — https://loadout.jnw-it.com/loadouts/cursor-rules-that-load/ -->\n"
    },
    {
      "path": "GEMINI.md",
      "role": "adapter",
      "description": "Imports AGENTS.md for Gemini CLI.",
      "skill": null,
      "agent": "gemini-cli",
      "install_to": {
        "claude-code": null,
        "codex": null,
        "cursor": null,
        "gemini-cli": "GEMINI.md",
        "antigravity-cli": null,
        "copilot": null
      },
      "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/GEMINI.md",
      "raw_latest_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/latest/GEMINI.md",
      "bytes": 383,
      "lang": "markdown",
      "content": "# GEMINI.md\n\n@./AGENTS.md\n\n## Gemini CLI notes\n- Skills from this loadout live in `.agents/skills/`: `write-cursor-rule`. Use them when their description matches the task.\n- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.\n\n<!-- From the Agent Loadout \"Cursor rules that load\" v1.0.0 — https://loadout.jnw-it.com/loadouts/cursor-rules-that-load/ -->\n"
    },
    {
      "path": ".cursor/rules/rule-authoring.mdc",
      "role": "rules",
      "description": "Auto-attached rule for editing .mdc files.",
      "skill": null,
      "agent": null,
      "install_to": {
        "claude-code": null,
        "codex": null,
        "cursor": ".cursor/rules/rule-authoring.mdc",
        "gemini-cli": null,
        "antigravity-cli": null,
        "copilot": null
      },
      "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/.cursor/rules/rule-authoring.mdc",
      "raw_latest_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/latest/.cursor/rules/rule-authoring.mdc",
      "bytes": 670,
      "lang": "markdown",
      "content": "---\ndescription: Use when creating or editing Cursor rules, AGENTS.md files or skills in this repository.\nglobs: .cursor/rules/**/*.mdc\nalwaysApply: false\n---\n\n- Front matter keys: `description`, `globs`, `alwaysApply`. Nothing else is read.\n- Write `globs` as a comma-separated string of patterns (the documented form). If a rule never attaches, check for a YAML list first.\n- Auto-attached rules need `alwaysApply: false`; with `true` the globs are ignored.\n- Keep each rule to one topic and under ~60 lines. Move procedures into `.agents/skills/<name>/SKILL.md`.\n- After editing, check it loads: open a matching file, start a new chat and ask which rules are active.\n"
    },
    {
      "path": "skills/write-cursor-rule/SKILL.md",
      "role": "skill",
      "description": "Write or fix a rule and check it attaches.",
      "skill": "write-cursor-rule",
      "agent": null,
      "install_to": {
        "claude-code": ".claude/skills/write-cursor-rule/SKILL.md",
        "codex": ".agents/skills/write-cursor-rule/SKILL.md",
        "cursor": ".agents/skills/write-cursor-rule/SKILL.md",
        "gemini-cli": ".agents/skills/write-cursor-rule/SKILL.md",
        "antigravity-cli": ".agents/skills/write-cursor-rule/SKILL.md",
        "copilot": ".agents/skills/write-cursor-rule/SKILL.md"
      },
      "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/skills/write-cursor-rule/SKILL.md",
      "raw_latest_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/latest/skills/write-cursor-rule/SKILL.md",
      "bytes": 1457,
      "lang": "markdown",
      "content": "---\nname: write-cursor-rule\ndescription: Add, split or fix a Cursor rule (.mdc) so it loads at the right time, and check it loads. Use when asked to write a rule, when a rule is ignored, or when converting .cursorrules.\n---\n\n# Write a Cursor rule\n\n1. **Decide the container** with the table in AGENTS.md. If it belongs in `AGENTS.md`, a skill or a hook, do that instead and stop.\n2. **Pick the type**: always, auto-attached (globs), agent-requested (description) or manual. Default to auto-attached.\n3. **Write the file** at `.cursor/rules/<topic>.mdc`, using `references/examples.md` as the pattern. Topic names are kebab-case.\n4. **Check the front matter**: only `description`, `globs`, `alwaysApply`; globs as a comma-separated string.\n5. **Test it loads**: tell the human to open a file the globs match, start a new chat and ask \"Which rules are attached?\".\n   For agent-requested rules, ask a question the description covers and check the rule is pulled in.\n6. **Remove duplicates**: delete the same instruction from `AGENTS.md`, `.cursorrules` or other rules.\n\n## Fixing an ignored rule\n- `alwaysApply: true` with globs: globs do nothing. Pick one.\n- Globs written as a YAML list: rewrite as one string, `src/**/*.ts, src/**/*.tsx`.\n- Description that says what the rule is (\"TypeScript rules\") instead of when to use it (\"Use when editing API handlers\").\n- Rule too long or contradicting `AGENTS.md`: shorten, and make `AGENTS.md` the single source.\n"
    },
    {
      "path": "skills/write-cursor-rule/references/examples.md",
      "role": "reference",
      "description": "Example rules for each type, plus a Copilot equivalent.",
      "skill": "write-cursor-rule",
      "agent": null,
      "install_to": {
        "claude-code": ".claude/skills/write-cursor-rule/references/examples.md",
        "codex": ".agents/skills/write-cursor-rule/references/examples.md",
        "cursor": ".agents/skills/write-cursor-rule/references/examples.md",
        "gemini-cli": ".agents/skills/write-cursor-rule/references/examples.md",
        "antigravity-cli": ".agents/skills/write-cursor-rule/references/examples.md",
        "copilot": ".agents/skills/write-cursor-rule/references/examples.md"
      },
      "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/skills/write-cursor-rule/references/examples.md",
      "raw_latest_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/latest/skills/write-cursor-rule/references/examples.md",
      "bytes": 1117,
      "lang": "markdown",
      "content": "# Example rules\n\nAuto-attached, scoped to React components:\n\n```markdown\n---\ndescription: React component conventions.\nglobs: src/components/**/*.tsx\nalwaysApply: false\n---\n\n- Function components only; props typed with an exported `type <Name>Props`.\n- Data fetching lives in hooks under `src/hooks/`, never inside components.\n- Every new component gets a story in the same folder: `<Name>.stories.tsx`.\n```\n\nAgent-requested, no globs:\n\n```markdown\n---\ndescription: Use when writing or changing a database migration.\nalwaysApply: false\n---\n\n- Create migrations with `npm run db:new -- <name>`; never edit an applied migration.\n- Every migration is reversible: write the down step and run `npm run db:rollback` locally before committing.\n```\n\nAlways on (keep these rare and short):\n\n```markdown\n---\nalwaysApply: true\n---\n\n- Package manager is pnpm. Never run npm or yarn install.\n```\n\nCopilot equivalent of the first example, at `.github/instructions/components.instructions.md`:\n\n```markdown\n---\napplyTo: \"src/components/**/*.tsx\"\n---\n\n- Function components only; props typed with an exported `type <Name>Props`.\n```\n"
    }
  ],
  "requires": {
    "tools": [],
    "env": [],
    "mcp": []
  },
  "tested": {
    "status": "untested",
    "last_run": null,
    "fixture": null,
    "per_agent": {
      "claude-code": "untested",
      "codex": "untested",
      "cursor": "untested",
      "gemini-cli": "untested",
      "antigravity-cli": "untested",
      "copilot": "untested"
    }
  },
  "security": {
    "scanned": true,
    "scanner": "intake-precheck/1",
    "verdict": "clean",
    "network": false,
    "scripts": []
  },
  "featured": false,
  "deprecated": false,
  "last_checked": "2026-10-17",
  "published": "2026-10-17",
  "updated": "2026-10-17",
  "compatibility": {
    "claude-code": "native",
    "codex": "native",
    "cursor": "native",
    "gemini-cli": "native",
    "antigravity-cli": "native",
    "copilot": "native"
  },
  "counts": {
    "rules": 2,
    "skills": 1,
    "mcp": 0
  },
  "url": "https://loadout.jnw-it.com/loadouts/cursor-rules-that-load/",
  "api_url": "https://loadout.jnw-it.com/api/loadouts/cursor-rules-that-load.json",
  "verification": {
    "level": "verified-install",
    "status": "verified",
    "label": "Verified install",
    "verified": true,
    "checked_at": "2026-10-17T07:47:06Z",
    "commit": "316f4bcae9d3c1f64f8f5e32a12e27e0c36f13b5",
    "content_current": true,
    "agent_tests": "not-run",
    "counts": {
      "pass": 8,
      "fail": 0,
      "skip": 0,
      "not_applicable": 2
    },
    "meaning": "Level 1: automated checks on the files (parse, install paths, MCP config, safety scan, references, size, licence, starter build). No AI agent was run.",
    "checks": [
      {
        "id": "listing",
        "name": "Listing",
        "status": "pass",
        "summary": "Schema valid; 6 files declared, none missing or extra",
        "details": [
          "tested.status: untested (agent tests are separate from Level 1)"
        ]
      },
      {
        "id": "parse",
        "name": "Files parse",
        "status": "pass",
        "summary": "All 6 files parse; front matter valid",
        "details": []
      },
      {
        "id": "adapters",
        "name": "Adapters",
        "status": "pass",
        "summary": "CLAUDE.md and GEMINI.md import AGENTS.md and are up to date",
        "details": [
          "CLAUDE.md: matches the generator",
          "GEMINI.md: matches the generator"
        ]
      },
      {
        "id": "install-paths",
        "name": "Install paths",
        "status": "pass",
        "summary": "Correct paths for all 6 agents; layouts re-discovered",
        "details": [
          "Claude Code: 4 files, 1 skill in .claude/skills/",
          "Codex CLI: 3 files, 1 skill in .agents/skills/",
          "Cursor: 4 files, 1 skill in .agents/skills/, 1 rule",
          "Gemini CLI: 4 files, 1 skill in .agents/skills/",
          "Antigravity CLI: 3 files, 1 skill in .agents/skills/",
          "GitHub Copilot: 3 files, 1 skill in .agents/skills/"
        ]
      },
      {
        "id": "mcp",
        "name": "MCP config",
        "status": "n/a",
        "summary": "No MCP servers in this loadout",
        "details": []
      },
      {
        "id": "safety",
        "name": "Safety scan",
        "status": "pass",
        "summary": "Clean: no credentials, risky shell or hidden text",
        "details": [
          "Scanner intake-precheck/1: verdict clean; network no (listing says no)"
        ]
      },
      {
        "id": "references",
        "name": "References",
        "status": "pass",
        "summary": "4 references between files resolve for every agent",
        "details": []
      },
      {
        "id": "size",
        "name": "Size limits",
        "status": "pass",
        "summary": "6 files, 5.8 KB total; largest AGENTS.md 1.8 KB",
        "details": [
          "Limits: 30 files, 32 KB per file, 128 KB total, 500 lines per skill or rule"
        ]
      },
      {
        "id": "licence",
        "name": "Licence",
        "status": "pass",
        "summary": "MIT, by Agent Loadout; text in the repository LICENSE",
        "details": []
      },
      {
        "id": "starter-build",
        "name": "Starter build",
        "status": "n/a",
        "summary": "Not applicable: rule-writing guidance with no project or code to build",
        "details": [
          "The loadout is guidance, one auto-attached .mdc rule and examples; whether a rule attaches can only be observed inside Cursor.",
          "The .mdc front matter is still checked for valid keys.",
          "Every other Level 1 check still runs on this loadout."
        ]
      }
    ]
  },
  "install": {
    "claude-code": {
      "files": [
        {
          "path": "AGENTS.md",
          "target": "AGENTS.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/AGENTS.md",
          "role": "instructions"
        },
        {
          "path": "CLAUDE.md",
          "target": "CLAUDE.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/CLAUDE.md",
          "role": "adapter"
        },
        {
          "path": "skills/write-cursor-rule/SKILL.md",
          "target": ".claude/skills/write-cursor-rule/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/skills/write-cursor-rule/SKILL.md",
          "role": "skill"
        },
        {
          "path": "skills/write-cursor-rule/references/examples.md",
          "target": ".claude/skills/write-cursor-rule/references/examples.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/skills/write-cursor-rule/references/examples.md",
          "role": "reference"
        }
      ],
      "manual_steps": [],
      "zip_url": "https://loadout.jnw-it.com/download/cursor-rules-that-load/claude-code.zip"
    },
    "codex": {
      "files": [
        {
          "path": "AGENTS.md",
          "target": "AGENTS.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/AGENTS.md",
          "role": "instructions"
        },
        {
          "path": "skills/write-cursor-rule/SKILL.md",
          "target": ".agents/skills/write-cursor-rule/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/skills/write-cursor-rule/SKILL.md",
          "role": "skill"
        },
        {
          "path": "skills/write-cursor-rule/references/examples.md",
          "target": ".agents/skills/write-cursor-rule/references/examples.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/skills/write-cursor-rule/references/examples.md",
          "role": "reference"
        }
      ],
      "manual_steps": [],
      "zip_url": "https://loadout.jnw-it.com/download/cursor-rules-that-load/codex.zip"
    },
    "cursor": {
      "files": [
        {
          "path": "AGENTS.md",
          "target": "AGENTS.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/AGENTS.md",
          "role": "instructions"
        },
        {
          "path": ".cursor/rules/rule-authoring.mdc",
          "target": ".cursor/rules/rule-authoring.mdc",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/.cursor/rules/rule-authoring.mdc",
          "role": "rules"
        },
        {
          "path": "skills/write-cursor-rule/SKILL.md",
          "target": ".agents/skills/write-cursor-rule/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/skills/write-cursor-rule/SKILL.md",
          "role": "skill"
        },
        {
          "path": "skills/write-cursor-rule/references/examples.md",
          "target": ".agents/skills/write-cursor-rule/references/examples.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/skills/write-cursor-rule/references/examples.md",
          "role": "reference"
        }
      ],
      "manual_steps": [],
      "zip_url": "https://loadout.jnw-it.com/download/cursor-rules-that-load/cursor.zip"
    },
    "gemini-cli": {
      "files": [
        {
          "path": "AGENTS.md",
          "target": "AGENTS.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/AGENTS.md",
          "role": "instructions"
        },
        {
          "path": "GEMINI.md",
          "target": "GEMINI.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/GEMINI.md",
          "role": "adapter"
        },
        {
          "path": "skills/write-cursor-rule/SKILL.md",
          "target": ".agents/skills/write-cursor-rule/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/skills/write-cursor-rule/SKILL.md",
          "role": "skill"
        },
        {
          "path": "skills/write-cursor-rule/references/examples.md",
          "target": ".agents/skills/write-cursor-rule/references/examples.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/skills/write-cursor-rule/references/examples.md",
          "role": "reference"
        }
      ],
      "manual_steps": [],
      "zip_url": "https://loadout.jnw-it.com/download/cursor-rules-that-load/gemini-cli.zip"
    },
    "antigravity-cli": {
      "files": [
        {
          "path": "AGENTS.md",
          "target": "AGENTS.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/AGENTS.md",
          "role": "instructions"
        },
        {
          "path": "skills/write-cursor-rule/SKILL.md",
          "target": ".agents/skills/write-cursor-rule/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/skills/write-cursor-rule/SKILL.md",
          "role": "skill"
        },
        {
          "path": "skills/write-cursor-rule/references/examples.md",
          "target": ".agents/skills/write-cursor-rule/references/examples.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/skills/write-cursor-rule/references/examples.md",
          "role": "reference"
        }
      ],
      "manual_steps": [],
      "zip_url": "https://loadout.jnw-it.com/download/cursor-rules-that-load/antigravity-cli.zip"
    },
    "copilot": {
      "files": [
        {
          "path": "AGENTS.md",
          "target": "AGENTS.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/AGENTS.md",
          "role": "instructions"
        },
        {
          "path": "skills/write-cursor-rule/SKILL.md",
          "target": ".agents/skills/write-cursor-rule/SKILL.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/skills/write-cursor-rule/SKILL.md",
          "role": "skill"
        },
        {
          "path": "skills/write-cursor-rule/references/examples.md",
          "target": ".agents/skills/write-cursor-rule/references/examples.md",
          "raw_url": "https://loadout.jnw-it.com/raw/cursor-rules-that-load/1.0.0/skills/write-cursor-rule/references/examples.md",
          "role": "reference"
        }
      ],
      "manual_steps": [],
      "zip_url": "https://loadout.jnw-it.com/download/cursor-rules-that-load/copilot.zip"
    }
  },
  "source_zip_url": "https://loadout.jnw-it.com/download/cursor-rules-that-load/source.zip"
}