create-rule

Files (4)

• SKILL.md
• evals.json · evals/
• examples.md · references/
• placement.md · references/

SKILL.md (first lines)

# Create Rule

Turn a convention into guidance that coding agents will actually follow. Write
[AGENTS.md](https://agents.md/) for standing orders and a skill for on-demand
playbooks. Do not create `.cursor/rules/` or `.mdc` files unless the user
insists after you have explained the mapping.

Cursor rules are editor-specific. AGENTS.md and skills are the portable
equivalents: AGENTS.md is always (or path) loaded, skills load when the task
matches.

## Inspect first

Before asking questions or writing files, look at the repo:

- Existing `AGENTS.md` files (root and nested)
- Existing skill roots (`skills/`, `.agents/skills/`, `.claude/skills/`,
  `.codex/skills/`, `.cursor/skills/`)
- Generated markers (`lat gen`, `BEGIN:`/`END:`, "do not edit")
- Whether the request is already covered (update that section or skill
  instead of adding a duplicate)

Match the project's existing voice and placement. One concern lives in one
place.

## Choose the artifact

| Intent                                                                     | Cursor equivalent                     | Write                                                                                                    |
| -------------------------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Standing order for every session in this repo                              | `alwaysApply: true`                   | Section in root `AGENTS.md`                                                                              |
| Standing order for one app, package, or directory                          | `globs: apps/web/**`                  | Nested `AGENTS.md` in that directory                                                                     |
| File-type convention that is not a single directory (`**/*.tsx` scattered) | `globs: **/*.tsx`                     | A skill whose description names the file type, or a short root AGENTS.md section if it must always apply |
| Task-specific procedure, framework playbook, or "only when doing X"        | Agent-requested / apply intelligently | Skill (`SKILL.md`)                                                                                       |
| Personal preference for every repo on this machine                         | User/global rule                      | Global AGENTS.md (`~/.fx/AGENTS.md` or the user's agent equivalent) only when they ask for global        |

AGENTS.md is a README for agents: setup, commands, invariants, safety,
verification. It is loaded often, so keep it short. Skills are playbooks
loaded on demand, so they can be longer and more specific.

Prefer a skill when the guidance is a workflow the agent would otherwise
reinvent (how to write a procedure, how to run a release). Prefer AGENTS.md
when ignoring the guidance would be wrong even for unrelated tasks (always
use bun, never commit secrets, always run this check).

If the user said "create a Cursor rule" or mentioned `.mdc`, still write
AGENTS.md or a skill and tell them the mapping. Only write `.cursor/rules`
if they insist they want Cursor-only files.

If they need a full skill with scripts, evals, or an iteration loop, use
`skill-creator` instead of drafting a thin SKILL.md here.

Read [references/placement.md](references/placement.md) when choosing paths
or migrating `.cursor/rules`.

## Gather only what you still need

Infer purpose, scope, and examples from this conversation first. A correction
("no, we use bun") is already the rule. Do not re-ask what was just said.

If scope is still unclear, ask one question:

- Always-on for the whole repo?
- Only when working in a specific directory?
- Only when doing a specific kind of task?

Suggest the default from the table above. Ask for file patterns only when
they said "specific files" but did not name a directory or glob.

Ask whether it is project-local or global only when they talk about "all my
projects" or "every repo". Default to the current project.

Do not ask about file format or where the file lives. You decide that.

## Write the guidance

Keep each AGENTS.md section under ~50 lines and about one concern. Split
unrelated concerns into separate sections or a nested file. Write like
internal docs: imperative, concrete, with a good and bad example when the
wrong form is tempting.

Explain why the rule exists in one sentence. Models follow "why" better than
a bare ALWAYS/NEVER. Save ALL CAPS for true safety or data-loss cases.

Do not put secrets, tokens, or unrelated private data in AGENTS.md or skills.
Those files enter model context.

### AGENTS.md

Plain markdown. No required frontmatter. Headings should name the concern.

- Update an existing section when the concern is already there.
- Add a new heading when it is a new concern.
- Create a nested `AGENTS.md` when the concern is path-scoped and no file
  exists yet.
- Leave generated regions untouched. If the whole root file is generated
  (`lat gen agents.md`, a full-file codegen banner), put new standing orders
  in a nested `AGENTS.md` or a skill rather than appending to generated
  output.

Nested files add path-scoped instructions. On conflict, the narrower file
wins. Direct user requests still beat both. Do not copy root instructions
into every nested file.

### Skills

Create `<skill-root>/<name>/SKILL.md` with YAML frontmatter:

```markdown
---
name: kebab-case-name
description: What it does and when to use it. Name trigger phrases.
---

# Title

Instructions for the agent.
```

`name` matches the directory. `description` is the trigger: include both

From brianrabil/skills, MIT.

More from brianrabil/skills