dev-skills

Appearance

Agent Instructions ​

Every repo carries its standing agent instructions in a single AGENTS.md at the repo root. CLAUDE.md is a one-line pointer to it, not a copy and not a symlink.

Why two files ​

  • AGENTS.md: the agent-agnostic instructions standard. Tools like Codex CLI read it natively, and adoption is growing across coding agents. It's the home for everything you'd otherwise repeat by hand: linting, PR process, addressing review comments, file-editing discipline, worktree rules.
  • CLAUDE.md: Claude Code's native instructions file. Rather than duplicate AGENTS.md into a second file that drifts out of sync, point Claude at the canonical one.

CLAUDE.md contents ​

A real file containing a single line:

IMPORTANT: Before doing anything else, read AGENTS.md in full. It contains
required instructions that govern all work in this repository and OVERRIDE your
default behavior. Follow them exactly.

The phrasing is deliberate:

  • Imperative and sequenced ("Before doing anything else") makes reading AGENTS.md the first action, not an afterthought.
  • "in full" discourages skimming.
  • "OVERRIDE your default behavior" mirrors the language Claude Code's own harness uses when it injects CLAUDE.md. That override framing is what makes the instructions reliably stick.

A bare Read AGENTS.md works, but the explicit version survives better when the pointer competes with everything else in context.

It's tempting to ln -s AGENTS.md CLAUDE.md so there's literally one source of truth. Don't. Symlinks are not reliably resolved in GitHub Actions. When the Claude GitHub Action checks out the repo, CLAUDE.md can be read as its literal symlink contents (a relative path string) instead of the target file. That throws an error and halts the entire action. A plain CLAUDE.md with the pointer line above works everywhere: locally, in CI, and across every agent.

Organizing AGENTS.md ​

Structure the instructions as a sequential workflow: the order an agent works through any task. A reader skimming top to bottom encounters rules in the order they need them.

A natural sequence:

  1. Understanding the repo. The facts to know, read, and check before starting: what the project is, where things live, how it builds and deploys.
  2. Working with GitHub issues. Find, read, and understand the issue that defines the task. This precedes implementation work. See the github skill.
  3. Setting up the environment. Before any code changes, get the workspace right: worktrees, branches, dependency installs.
  4. Edits and coding standards. File-editing discipline, code style, and comment conventions.
  5. PR and review workflow. GitHub Markdown, opening the PR, and addressing review comments. Fix all true-positive code style violations before opening the PR for review, then again after every change during the review process.
  6. Verification and cleanup. Verify the merge succeeded and that downstream processes like GitHub Pages ran successfully. Then tear down the worktree and branch.

Sourcing the content ​

Don't write AGENTS.md from imagination. A rule that was actually needed is worth encoding; a rule imagined as a might-need is noise. Source rules from real friction in the repo's history:

  1. Chat session history. The most direct signal: the times the human corrected you and said "no, do it this way." Past session transcripts are the richest single source of real corrections.
  2. Issues. Especially ones whose titles describe a convention or a class of mistake (formatting, broken links, CI, PR process).
  3. PR review comments. (Most important source.) A comment left on a PR is a correction that will recur. Recurring review nits are prime AGENTS.md material.
  4. CI config. What the pipeline already enforces (or fails to enforce) tells you which rules are load-bearing and where the manual-verification gaps are.

Rank by recurrence: a rule corrected five times belongs at the top. The highest-confidence signal is double-corroboration: a rule that appears in both session history and the issue/PR record. That is exactly how this repo's AGENTS.md content was assembled.

Prose rules vs enforceable checks ​

Sort every candidate by whether it can be automated:

  • Scriptable as a hard rule (broken links, backticks, line length, build is green): the real home is a CI check or lint script. AGENTS.md should point at the check, not just assert the rule. A check that runs beats a paragraph you skim.
  • Requires interpretation and judgment (comments say why not what, don't escalate destructive operations, reply to every reviewer): AGENTS.md prose, because you can't lint intent.

Anything computable as a hard rule should be scripted. Checks that require interpretation and judgment require an agent.

When a prose rule keeps getting violated, the fix is to make it runnable: either as an automated script or as an unavoidable agent check. Prose alone is weak enforcement: in this repo, "no broken links" lived in writing guidance for a long time and the site still broke repeatedly, because nothing ran the check.

Setup in a new repo ​

  1. Create AGENTS.md at the repo root. Structure it as the sequential workflow described above, with rules sourced from real friction in the repo's history.
  2. Create CLAUDE.md containing only the pointer line above.
  3. Do not symlink the two.
  4. Commit both.