# Add Guidance

> Fold a correction into durable agent guidance, or restructure a rules-and-examples guidance file into the adherence-optimized shape.

- Skill: `indiosmo/add-guidance` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add indiosmo/add-guidance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/indiosmo/add-guidance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: indiosmo (https://skillmd.com/u/indiosmo)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/indiosmo/add-guidance

---


# Add guidance

You corrected the agent; now make the correction stick. This skill turns a
one-off correction into a durable rule, written the way that makes a model
actually follow it -- and restructures existing guidance files into that same
shape.

## Why shape matters (read this first)

A guidance file teaches by demonstration. The model imitates the snippets it
sees, and it imitates them whether the label above says `Good:` or `Bad:` -- a
fluent, plausible code block is a strong signal; a one-word polarity header is a
weak one. So a bad example is never free: it teaches by contrast, but it also
primes the very pattern you are trying to suppress, and the priming can win.

That gives the whole skill its bias: **the good example is the asset; a bad
example is a cost that has to earn its place.** Lead with the good form, make it
complete and the last thing the reader sees, and add a `Bad:` block only where
the mistake is genuinely non-obvious from the good form alone. This is the shape
that won the adherence eval this skill is built from. The full reasoning and the
exact format a retained bad example must take live in
[`references/structuring-for-adherence.md`](references/structuring-for-adherence.md)
-- read it before restructuring a whole file, and any time you are unsure
whether a bad example is pulling its weight.

## Two modes

- **Add a correction** (the common case): something just happened in this
  session -- the agent wrote X, you said "no, do it like Y" -- and you want that
  captured. Start at "Add a correction" below.
- **Restructure a file**: take an existing guidance file and re-shape it into
  the adherence-optimized form (the "apply the same refactoring to our
  guidelines" task). Start at "Restructure a file" below.

---

## Add a correction

### 1. Recover the correction, and generalize it

Reconstruct three things from the recent conversation -- ask the user only for
what you genuinely cannot infer:

- **The idiom** -- the form you were corrected *toward*. This becomes the good
  example. State it as a positive: "derive the expected value from the domain,"
  not "stop deriving it from the implementation."
- **The tell** -- the specific, recognizable mistake you made. This is what a
  bad example, if any, would show, and what the rule is meant to catch.
- **The rule it generalizes to.** This is the load-bearing step. The correction
  happened on one file with one set of names, but the guidance will be read a
  thousand times across code you have never seen. Lift the principle out of the
  specifics: a fix to one `OrderId` accessor is really "give each domain field a
  strong type and access it through its named method." If you cannot name a
  general principle, the correction is a one-off preference -- say so and stop
  rather than minting a brittle rule (see "When not to add a rule").

### 2. Find where it belongs

Locate the guidance the project already ships. Look, in order, for: an existing
good/bad-example file (a `*-examples.md`, a coding-standards or style doc), a
rules/idioms section in `CLAUDE.md` / `AGENTS.md`, a `guidelines/` or `docs/`
directory, editor rule files (`.cursor/rules`, `.github/`). Many projects split
**rules prose** (a "context" file) from **examples** (a paired-snippet file); if
so, you will touch both. Confirm the target file with the user when more than one
plausibly fits, or when none exists and you would be creating one.

Then check whether the rule is already there. If an existing rule covers this,
**sharpen that rule** instead of adding a second one -- two rules teaching the
same tell multiply the primable surface without teaching more. Adding is the last
resort, not the first.

### 3. Write the good example and the rule prose

Match the file's existing conventions exactly -- section heading style, the
reserved markers it already uses (`Good:` / `Bad:`), and its placeholder
vocabulary (e.g. `lib::` stand-ins for project types). Do not introduce a synonym
marker like `Avoid:` or `Anti-pattern:` if the file uses `Bad:`.

- Write the **rule prose** as a positive instruction that names the idiom and
  says briefly *why* it holds. The model has good theory of mind; a reason it
  understands beats a bare prohibition it must obey on faith.
- Write the **good example** as the complete, imitable thing you want emitted --
  it should look like real, runnable code in the project's idiom, with no `...`
  in the part that carries the idiom. A reader who sees only this block should be
  able to reproduce the pattern.
- The good example comes first and the rule ends on it.

### 4. Decide whether a bad example earns its place

Default to **no bad example.** Add one only when the tell is not self-evident
from the good form -- when a reader could see the good example and still not
realize the specific trap you fell into. (East vs west const is non-obvious;
"don't leave a TODO" is obvious -- skip it.)

If you do add one, format it the way the evidence says negatives have to be
formatted to help, or it is pure liability:

- **Flagged** with the file's exact `Bad:` marker.
- **Reduced to the tell.** Strip every line of correct scaffolding around the one
  bad line -- a `Bad:` block full of good imports and good signatures is
  mostly-good code under a bad header, maximal contamination for minimal
  teaching. A single `BAD: T const&  ->  GOOD: const T&` contrast often beats a
  whole bad function.
- **One tell only.** If you are tempted to show three mistakes, that is three
  bad examples (or, better, one rule each).
- **Immediately corrected.** Follow the `Bad:` block right away with the `Good:`
  form of the same code, so the pair -- and the rule -- ends on what to write.
- **A short minority.** The bad block must be shorter than its good counterpart,
  and the file as a whole must stay well under half bad.

If the project keeps a tells / lint / "things we keep correcting" list, add this
tell to it in the same change and keep the mapping one-to-one (see Principle 4 in
the reference).

### 5. Verify before you finish

Re-read your edit cold against this checklist:

- The good half stands alone and fully specifies the idiom.
- The rule ends on the good form, not a bad block.
- If a bad block is present: it is shorter than the good block, shows exactly one
  tell, uses the exact reserved marker, and is immediately followed by the
  corrected good form.
- Deleting every bad block from the file would still leave valid, complete
  guidance.
- The rule prose reads coherently whether or not the examples are there.

Then tell the user what you changed and where, and -- briefly -- why you did or
did not add a bad example, so the judgment call is theirs to override.

---

## Restructure a file

Use this when an existing guidance file is in the wrong shape -- typically a
file that is roughly half `Bad:` blocks, ends rules on the bad form, or wraps its
anti-patterns in fluent scaffolding. The goal is to move it to the
adherence-optimized shape without changing what it teaches.

Read [`references/structuring-for-adherence.md`](references/structuring-for-adherence.md)
in full first -- the restructure leans on the whole principle set, not just the
summary. Then, rule by rule:

1. **Lead with the good form** and make it the complete, load-bearing element.
   If the good half only makes sense as "not the bad thing," rewrite it to stand
   on its own.
2. **Re-shape the rule prose** to name the idiom positively, not only to
   prohibit.
3. **Triage each bad block.** Drop it if its tell is self-evident from the good
   form. Keep it only where the tell is non-obvious -- and then reduce it to the
   fragment that carries the tell, ensure it is flagged, immediately corrected,
   and a short minority, and split any block showing more than one tell.
4. **End every rule on the good form.**
5. **Normalize the markers** to one exact reserved token per polarity so the
   file is cleanly machine-separable (a good-only variant should be derivable by
   deleting `Bad:` blocks, with no hand-editing).

Preserve the file's domain vocabulary and the rules' meaning; you are changing
arrangement and proportion, not the standard. When done, run the file-level
checks from the reference: bad code is a clear minority of example volume, every
tell has one canonical demonstration, and removing all bad blocks leaves valid
guidance. Summarize for the user what you dropped, what you kept and why, and the
rough before/after good-vs-bad balance.

---

## When not to add a rule

Push back instead of writing guidance when:

- **It is a one-off, not a principle.** A correction that only makes sense for
  this one file, with no general idiom behind it, will read as noise to a future
  agent and dilute the rules that matter. Name the missing general principle, or
  decline.
- **A rule already covers it.** Sharpen the existing rule; do not add a near
  duplicate. Duplicated demonstrations -- good or bad -- multiply primable
  surface without teaching more.
- **It contradicts an existing rule.** Surface the conflict to the user and
  resolve which wins before editing; do not silently leave two rules pulling in
  opposite directions.

A guidance file is read on every session it loads. Restraint about what goes in
is part of making the things that *are* in it land.

## Worked shape

What a single rule looks like in the target form -- good example first and last,
a bad block only because east-vs-west const is a non-obvious tell, reduced to the
fragment that carries it, immediately corrected:

> ## Const placement
>
> Place `const` to the left of the type (west const) so every declaration reads
> the same way and the qualifier is where readers scan for it.
>
> Good:
> ```cpp
> const order_book& book = session.book();
> ```
>
> East const reads backwards from the rest of the codebase and is easy to miss on
> a pointer.
>
> Bad:
> ```cpp
> order_book const& book = session.book();
> ```
>
> Good:
> ```cpp
> const order_book& book = session.book();
> ```