harden-instructions

Files (21)

• SKILL.md
• CLAUDE.md · self-test/01-generated-region-untouched/
• expected.md · self-test/01-generated-region-untouched/
• CLAUDE.md · self-test/02-enforced-rule-collapses/
• expected.md · self-test/02-enforced-rule-collapses/
• check-mutates.py · self-test/02-enforced-rule-collapses/scripts/
• test_check_mutates.py · self-test/02-enforced-rule-collapses/tests/
• CLAUDE.md · self-test/03-prohibition-becomes-reflex/
• expected.md · self-test/03-prohibition-becomes-reflex/
• CLAUDE.md · self-test/04-history-kept-when-unrecoverable/
• expected.md · self-test/04-history-kept-when-unrecoverable/
• CLAUDE.md · self-test/05-unproven-check-keeps-prose/
• expected.md · self-test/05-unproven-check-keeps-prose/
• check-mutates.py · self-test/05-unproven-check-keeps-prose/scripts/
• SKILL.md.input · self-test/06-skill-keeps-frontmatter-and-shape/
• expected.md · self-test/06-skill-keeps-frontmatter-and-shape/
• CLAUDE.md · self-test/07-pointer-kept-when-nothing-cut/
• expected.md · self-test/07-pointer-kept-when-nothing-cut/
• CLAUDE.md · self-test/08-reflex-keeps-scope/
• expected.md · self-test/08-reflex-keeps-scope/
• README.md · self-test/

SKILL.md (first lines)

# Harden Instructions

Revise an instruction file so each rule sits on the highest tier it can reach — enforced, derived, named or
stated — and whatever stays in prose is phrased for the model to recall rather than reinvent.

**Read `${CLAUDE_PLUGIN_ROOT}/rules/agent-instructions.md` first** — it is the standard every file gets, and
nothing loads it for you. A file's **profile** (below) adds a layout standard on top.

Every edit tightens the file and keeps every rule that still binds.

## Parse the Argument

`$ARGUMENTS` holds one or more paths, separated by spaces. A quoted path may contain spaces.

| Pattern | Type | Example |
|---------|------|---------|
| Names a file, whatever its name | File path | `CLAUDE.md`, `skills/foo/SKILL.md`, `~/other-repo/AGENTS.md` |
| Ends with `/` or is a directory | Directory path | `./`, `skills/`, `~/other-repo/` |
| Empty or omitted | Current directory | — |

Expand a leading `~` to the home directory. A path outside the current repository is valid; process it the same way. Report a path that does not exist and skip it.

## Pick the Profile

| Profile | The file is | Layout standard | Budget |
|---|---|---|---|
| **Project memory** | `CLAUDE.md`, `CLAUDE.local.md`, `.claude/CLAUDE.md`, `AGENTS.md` | `${CLAUDE_PLUGIN_ROOT}/rules/claude-md.md` | 200 lines, generated regions included |
| **Skill** | `SKILL.md` | `plugin-dev:skill-development`: imperative voice, detail in `references/` | Body 1,500–2,000 words; flag over 3,000 |
| **Agent** | a `.md` under an `agents/` directory | `plugin-dev:agent-development`: second person, addressing the agent | Body 500–3,000 characters; flag over 10,000 |
| **Command** | a `.md` under a `commands/` directory | `plugin-dev:command-development` | None |
| **Reference** | a `.md` under a `rules/` directory, a skill's `references/*.md`, any other file given by path | None | None |

**Shipped and local files.** Project memory runs in the repository it sits in. A skill, agent, command or plugin rule ships: it runs in a user's repository, not the one it was written in. Revision rules 2, 3 and the recovery pointer treat the two differently, as each says.

Read the profile's layout standard alongside `agent-instructions.md`. For a plugin-dev standard, Glob `~/.claude/plugins/cache/*/plugin-dev/*/skills/<name>/SKILL.md` and Read the file — never load it through the Skill tool, because `command-development` carries an inline shell example the Skill tool executes and fails on. When plugin-dev is not installed, say so in the report and apply `agent-instructions.md` alone.

**An `AGENTS.md` is read by agents other than Claude Code.** Skip the items only Claude Code honours: `CLAUDE.local.md`, `.claude/rules/`, Claude Code hooks and `@imports`.

## Find the Target's Repository

Every search and every git read runs against **the target's repository**, never the working directory:

```
git -C <target's directory> rev-parse --show-toplevel
```

Call the result the **root**. Search the root with Grep and Glob when judging a rule; pass `-C <root>` to every git read, with the target's path relative to the root.

Run only `rev-parse`, `status`, `log` and `check-ignore`. The grant admits any `git -C` call; this skill reads and never writes through git.

With no root — `~/.claude/CLAUDE.md`, an unversioned directory — skip revision rules 2 and 3 and keep every rule they would have judged, flagged in the report.

---

## File Path

1. Read the target file. Resolve a symlink and process the file it points to once.
2. Pick the profile and read its standards.
3. Find the root.
4. Set aside the **frozen parts**: frontmatter and generated regions (see Safety).
5. Check whether history can be recovered (see **Recoverability**).
6. Run the **audit**.
7. Apply the **revision rules**.
8. **Report**.

## Directory Path

1. Glob the given directory — not the root — for `**/CLAUDE.md`, `**/CLAUDE.local.md`, `**/AGENTS.md`, `**/SKILL.md`, `**/skills/*/references/*.md`, and `**/*.md` under any `agents/`, `commands/` or `rules/` directory that sits at the root, in `.claude/`, or beside a `.claude-plugin/` directory. A `docs/agents/` folder is not an agents directory.
2. Drop every match under `self-test/`, `node_modules/`, `vendor/` or `.git/`. Self-test inputs are flawed on purpose; a run that "fixes" them destroys the test. Drop any other match that `git -C <root> check-ignore -q <rel>` reports ignored, except `CLAUDE.local.md`, which is ignored by design.
3. With no matches left, report that and stop.
4. With only project-memory matches, apply the **File Path** process to each and report per file.
5. Otherwise list every match by profile, with its line and word counts, edit nothing and stop. A directory can hold dozens of skills and rules; the user reruns with the paths to process.

---

## Recoverability

Run, with `<rel>` the target's path relative to the root:

```
git -C <root> status --porcelain --ignored -- <rel>
git -C <root> log -1 --format=%h -- <rel>
```

- **Empty status and a hash** → the pre-revision text sits at that commit. History may be cut — any text rules 2–4 remove that is not itself a rule: an incident beyond its one-line wound, a rationale, a mechanism, a dated decision trail. Name `git show <hash>:<rel>` in the report. For project memory only, when this run cuts history, also leave it as the file's last line, outside every frozen part — `Rationale and history cut <date>: git show <hash>:<rel>` — replacing any earlier line of that form. The version it names carries the earlier line, so each cut stays one hop from the last. A run that cuts no history leaves an existing pointer byte-for-byte unchanged. This pointer is the one line the skill may add. A shipped file gets no pointer: its body is prompt text, and the hash names a repository its users do not have.
- **Anything else** — modified, untracked, ignored, no root, or an error → cut no history. Compress each wound to one line and keep the rest, flagged in the report as recoverable nowhere.

---

## Audit

Score the file against each criterion. Flag violations before editing.

### Placement — every profile
- [ ] A rule a tested check enforces takes one bullet: reflex, limits, check
- [ ] A mechanically checkable rule with no check is flagged for one
- [ ] The model learns its position from disk or forge state, never a remembered step number
- [ ] Each non-obvious rule leads with its reflex and carries at most one line of wound
- [ ] Prohibitions name their alternative, or become reflexes
- [ ] A described protocol is named instead (Makefile, circuit breaker, `Key: Value`, EBNF)
- [ ] No invented tags or sigils
- [ ] No numbered workflow with "go back to step N" routing
- [ ] Someone other than the maker verifies each gate

### Writing — every profile
- [ ] Each bullet states one instruction
- [ ] Imperative mood ("Run X", not "You should run X") — an agent's body addresses the agent in the second person instead
- [ ] Specific over vague ("2-space indent", not "consistent formatting")
- [ ] No platitudes ("write clean code")
- [ ] No stale instructions for removed files, commands or features

### Layout — per profile
- **Project memory:** at most two IMPORTANT markers, and the Structure, Content and Scoping items in `rules/claude-md.md` — one or two lines of project context, then build and test; build and test commands present; nothing Claude infers from code; personal preferences in `CLAUDE.local.md`; path-specific rules in `.claude/rules/`; workflows in skills; deterministic rules in hooks.
- **Skill:** body within budget; detail that is reference material, not procedure, named for `references/`; every bundled file the body names exists.
- **Agent, Command:** the body is instructions for the model, not documentation for a human.
- **Reference:** no layout items.

---

From pmvanev/phil-claude-plugin, MIT.

More from pmvanev/phil-claude-plugin