---
source_keys:
  - claude-code-memory-docs
---

# What belongs in an instructions file

Reached from `SKILL.md` Step 2. Claude reads instructions as context, not as enforced configuration, so a rule only helps if it is specific, short and not contradicted elsewhere.

## Write rules an agent can check

| Weak | Checkable |
|---|---|
| Format code properly | Use 2-space indentation |
| Test your changes | Run `npm test` before committing |
| Keep files organized | API handlers live in `src/api/handlers/` |

Group related bullets under a short heading. Give the reason when a rule looks arbitrary; a rule with a stated reason survives the edge case.

## Keep

- Conventions that differ from the tool's default.
- Pitfalls the agent would walk into, with the reason.
- Build, test and lint commands; where things live when a path cannot be guessed.

## Cut

- What the agent can read from the code: directory listings, dependency lists, architecture overviews.
- Anything stated in another file that loads alongside this one. Two copies drift, and contradictory rules are followed arbitrarily.
- Generalities ("write clean code").

## Right artifact?

| The content is | Put it in |
|---|---|
| A rule for part of the codebase | This file, with a quoted `applyTo` |
| A rule for every session | This file without `applyTo`, or `AGENTS.md` (`agentsmd-author`) |
| A multi-step procedure or one task's guidance | A skill (`skill-author`) |
| Something that must run at a fixed point or be blocked | A hook, or a `permissions.deny` setting; an instruction is not enforcement |

If the answer is not this file, say so to the user and stop; do not bend the content into a rule.