# Agent Instructions

> Write and maintain the repository instruction file an AI coding agent loads every session (CLAUDE.md, AGENTS.md or equivalent), and decide what belongs there versus in an on-demand skill. Use when setting one up, when an agent keeps repeating a mistake the file was supposed to prevent, or when the file has grown past the point of being read.

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

---


# Repository instructions for agents

The instruction file is loaded into every session, whether or not it is
relevant. That makes it the most expensive text in the repository, and the rule
that follows from it: **every line must change what an agent does.**

## 1. Write the hazards, not the tour

An agent can read the code. It cannot know what happened the last time someone
ran the obvious command.

| Belongs in the file | Does not |
|---|---|
| "Never run `x` directly — it bypasses the deploy lock" | "The frontend is in `frontend/`" |
| "Scripts default to staging; production must be named" | A list of the main components |
| "This directive is inert on this API; use the other one" | "We use TypeScript and React" |
| "Cross-module type imports must use `import type` or the app serves blank" | Coding style a linter enforces |

The test for a line: **would a competent engineer get this wrong on their first
day, in a way the code does not warn them about?** If not, cut it. Architecture
descriptions, folder tours and stack lists are re-derivable in seconds and
consume the budget that the hazards need.

## 2. Every prohibition carries its consequence

"Never run `npm run build` directly" gets optimised away by a reader who has a
good reason and no information. "Never run `npm run build` directly — it bakes
`.env.local` localhost URLs into the production bundle, silently" does not,
because now the reader can see what they would be trading.

The consequence is also what lets an agent reason about the edge case you did
not anticipate. A rule with no reason is only ever followed literally.

## 3. State defaults out loud, especially inverted ones

Anything where the safe option is not what happens by default deserves its own
line, in plain language, including which way round it is:

> `deploy.sh` defaults to **production**. `scripts/*` default to **staging**.
> They are opposite, and the mismatch has shipped the wrong build.

A rule that contradicts intuition needs restating more than a rule that agrees
with it.

## 4. Keep it short enough to be read whole

A long file is skimmed, and skimming defeats the purpose. Aim for something a
person would read in full before starting work.

When it grows, the answer is not smaller fonts — it is moving material out:

- **Standing facts and hazards** stay in the instruction file. Always loaded.
- **Task procedures** move to a skill, loaded only when that task comes up. "How
  to review content", "how to author a lesson", "how to cut a release" are
  skills. "Never deploy from a stale worktree" is an instruction.
- **Reference material** moves to a doc, with a one-line pointer from the
  instruction file saying when to read it.

The pointer matters: `read Docs/branching.md before you deploy or cut a branch`
is a line that earns its place, because it fires at the right moment.

## 5. Stale instructions are worse than none

An instruction file is trusted. When it is wrong, it produces confident wrong
work, and the error is hard to find because the agent is doing exactly what it
was told.

- Put a date on anything time-sensitive, and write dates absolutely. "Since
  2026-09-12, production deploys are manual" stays true; "recently" does not.
- When a rule changes, edit the file **in the same commit** as the change. A
  follow-up commit does not happen.
- Delete rules whose hazard no longer exists. A guard now enforced in CI does
  not need a paragraph; one line saying the guard exists is enough.
- Periodically check each claim against the repo. Named scripts, flags and paths
  are the things that rot first.

## 6. Where the file lives, and how many

- One per repository at the root, named whatever the tools in use expect. If
  several agents are used, keep one canonical file and have the others point to
  it or mirror it — two drifting copies is worse than one imperfect file.
- Subdirectory files for genuinely separate concerns in a monorepo, kept short.
- Never put credentials, tokens or customer data in it. It is committed, it is
  read by tooling, and it is quoted back in transcripts. Say "ask the owner"
  and name what is needed.

## 7. Descriptions are triggers, not summaries

For any skill you factor out, the description is the only thing read when
deciding whether to load it. Write the *situations*, in the words that will
appear in a request:

```
Bad:  Documentation for our content review process.

Good: Audit course content for a year level or path, produce ranked findings,
      and drive fixes through dry-run scripts. Use for any request to review,
      audit, check or find gaps in content, decks, questions or exams.
```

Name the verbs and the nouns a person would actually use. A skill that never
triggers is worth nothing however good its body is.

## 8. Test it by starting fresh

The only real check. Open a new session with no context and ask for something
the file is supposed to govern.

- Did it take the safe path without being told?
- Did it look for the thing the file says exists?
- Did it repeat a mistake the file was written to prevent? Then the line is
  missing, buried, or too polite. Sharpen it and put it higher.

When an agent makes the same mistake twice, that is not an agent problem. It is
a missing or weak line, and the fix belongs in the file — that is how the file
grows honestly.

## 9. The instruction file is a record of scar tissue

Its best form is a list of things that have actually gone wrong, each with what
to do instead. It reads oddly to a newcomer — a strange mix of the specific and
the severe — and that is correct. It is not documentation. It is the set of
things that cost someone a day.

## Checklist

- [ ] Every line changes what an agent does; tours and stack lists removed
- [ ] Every prohibition states its consequence
- [ ] Inverted or surprising defaults stated explicitly
- [ ] Short enough to read whole; procedures moved to skills, reference to docs
- [ ] Pointers to docs say *when* to read them
- [ ] Dates absolute; rules updated in the same commit as the change
- [ ] Obsolete rules deleted; named paths and flags verified against the repo
- [ ] One canonical file; no credentials
- [ ] Skill descriptions written as triggers, in the requester's words
- [ ] Tested from a fresh session; repeated mistakes turned into new lines