version: "1.6"

2. **Generalise the instruction** — if the instruction you received is highly specific (names an exact function, file, or code object), lift it to a transferable principle before writing the skill content. See "Generalising incoming instructions" below.

3. Make the necessary content changes to the skill.

4. Increment the version number in the YAML frontmatter `metadata.version` field.

5. Verify the YAML frontmatter is valid (all required fields present, version is quoted).

You will often receive instructions that are phrased in terms of a specific situation:

"add guidance about function X", "mention that file Y must be updated", or "note that

class Z behaves this way". Before writing this into a skill, lift the instruction to a

more abstract principle.

Ask: **What general rule does this specific case illustrate?** A skill should remain

useful as the codebase evolves. If the specific function, file, or class mentioned in

the instruction were renamed or removed, would the guidance still be relevant? If not,

rewrite it so it would be.

| Specific instruction received | Generalised skill content |

| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| "Add a note that `foo_helper()` must be called before `bar()`." | "Certain setup steps must be completed before the main operation — check the API contract for ordering requirements." |

| "Note that `config.toml` must be updated when adding a new flag." | "When adding a feature that introduces new configuration, update all files that declare or document available options." |

| "Warn that `TypeAdapter.validate_python` is banned, use `validate_or_raise`." | "Some standard-library or third-party APIs may be banned by project convention — consult the linter configuration or project documentation before reaching for them." |

Avoid adding guidance that:

- Names specific functions, classes, or files unless the principle is **only** about

that specific thing (e.g. a skill about a single tool's CLI interface).

- Reads like a changelog or incident report ("we discovered that X did Y").

- Would become incorrect or confusing if the named entity were refactored.

- **Keep content general.** Write instructions that remain valid as the codebase evolves. Avoid embedding specific file paths, class names, or constants unless strictly necessary. See "Generalising incoming instructions" above.

- **Never reference memories.** Skill content is read with no access to agent session history or stored memories. Do not write phrases like "as noted in a previous session" or "per the stored memory about X". Everything the reader needs must be present in the skill itself.