#harnessed.md

Guides are the instructions that steer an agent before it acts — the highest-leverage part of the harness. A well-configured guide layer determines whether your agent produces useful work on the first attempt or burns cycles on wrong approaches.

##AGENTS.md

AGENTS.md is an open, tool-agnostic standard for guiding coding agents. It lives at your project root and is read by Codex, Cursor, Gemini CLI, GitHub Copilot, and others. It’s backed by the Linux Foundation’s Agentic AI Foundation with support from OpenAI, Anthropic, Google, and AWS.

Claude Code reads CLAUDE.md. If you use multiple tools, write an AGENTS.md as your cross-tool base and symlink CLAUDE.md to it:

ln -s AGENTS.md CLAUDE.md

This keeps a single source of truth — Git tracks it natively, and both tools read the same file.

What to include — from GitHub’s analysis of 2,500+ repos:

• Commands — build, test, lint, deploy
• Testing — how to run tests, preferred frameworks
• Project structure — key directories and their purpose
• Code style — only rules that differ from defaults
• Git workflow — branch naming, PR conventions
• Boundaries — “always do”, “ask first”, “never do”

Keep it short. For each line, ask: “would removing this cause the agent to make mistakes?” If not, cut it. A focused 50-line file outperforms a comprehensive 500-line file — important rules get lost in noise.

##The config stack

AGENTS.md is just one layer. Modern agent tools support progressive disclosure — information loads only when relevant, keeping the agent’s context clean.

The key distinction: AGENTS.md is advisory — the agent reads it but may not follow it perfectly. Hooks are deterministic — they run scripts that enforce behaviour mechanically. If something must happen every time (formatting, linting, blocking commits to main), use a hook, not a rule.

##Skills

Skills extend what an agent can do. A skill is a folder with a SKILL.md file containing instructions the agent loads on demand — domain knowledge, workflows, or repeatable tasks you invoke with /skill-name.

The Agent Skills open standard works across Claude Code, Codex, Cursor, VS Code Copilot, and others. Skills are how you teach an agent about your domain without bloating every session’s context.

Examples of useful skills:

• Workflows — /deploy, /fix-issue 1234, /review-pr
• Domain knowledge — API conventions, database patterns, legacy system context
• Compound loops — Every’s compound engineering plugin uses skills to implement plan/work/review/compound cycles

##Hooks

Hooks run scripts at specific points in the agent’s lifecycle — before a tool runs, after a file edit, when a session starts. Unlike rules which are advisory, hooks guarantee the action happens.

Common hooks:

• Run a linter after every file edit
• Block commits to main or production
• Auto-format code on save
• Validate that migrations have a corresponding rollback

The rule of thumb: if you’ve written a rule in AGENTS.md and the agent keeps ignoring it, convert it to a hook. A PostToolUse hook that runs your verification suite on every edit is six lines of config:

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npm test && npm run lint" }]
      }
    ]
  }
}

The agent sees the failure in its next turn and fixes it before you read the diff.

##Context tiers

Most people put everything in AGENTS.md and wonder why the agent ignores half of it. The problem is context — agents perform best with the smallest possible set of high-signal tokens.

Think about your guides in three tiers:

• Hot memory (always loaded) — AGENTS.md, path-scoped rules. Keep this minimal: only what applies to every session.
• Domain specialists (invoked per task) — skills and subagents. Domain knowledge, workflows, and focused expertise that loads when relevant.
• Cold memory (retrieved on demand) — design docs, past learnings, architectural decisions. The agent searches for these when it needs them.

When you notice your AGENTS.md growing past ~100 lines, move domain-specific knowledge to skills and project documentation to cold storage. The agent will find it when it needs it.