AGENTS.md Architect

What it does

A short instructions file from your real repo.

Your agent loads it when the user writes, rewrites or audits CLAUDE.md, AGENTS.md or rules files. It carries 5 rules and reads a profile.md with your details before it starts, so the output matches your brand and project.

SKILL.md, first 40 lines

---
name: agents-md-architect
description: "Use when the user asks to write, rewrite, shorten, audit or fix a CLAUDE.md, AGENTS.md, GEMINI.md or Cursor rules file, says 'set up my agent for this repo', 'the agent keeps ignoring my instructions', 'init this project' or 'my CLAUDE.md is huge', or starts a project that has no agent instructions. Builds the file from the real repo (commands, layout, conventions, gotchas), keeps it short, and cuts everything the agent can learn by reading the code. Reads profile.md for agents, project, stack and team size."
---

# AGENTS.md Architect

Write the instructions file an agent reads at the start of every session. Every line is paid for in tokens on every task, so every line has to earn its place.

An agent that reads a 400-line rules file follows the first 40 lines well and the rest at random. A 50-line file that is all true and all non-obvious gets followed. Write that one.

## Before you start

Read `profile.md` in this folder:

| profile.md line | Use |
|---|---|
| **Agents** | Which files to write (table below) |
| **Project** | One-line description at the top of the file |
| **Stack** | Cross-check against what the repo actually uses; the repo wins |
| **Team size** | Solo: about 40 lines, personal taste allowed. 2-10: about 60 lines, shared conventions. 10+: short root file plus nested files per package |

If a line says "not set", ask once, write the answer into profile.md, continue.

| Agent | Reads | Notes |
|---|---|---|
| Claude Code | CLAUDE.md (nested ones load when working in that folder) | Can import other files with an @path line. Check its docs for the current syntax. |
| Codex | `AGENTS.md` | Nested `AGENTS.md` files apply to their folder. |
| Cursor | `AGENTS.md` and the `.cursor/rules` folder | Rule files can be scoped to globs; put scoped detail there. |
| Gemini CLI | `GEMINI.md` | Can be pointed at another filename in its settings. Check its docs. |

With more than one agent: write `AGENTS.md` as the single source of truth, then make each other file a one-line pointer or import to it. Two diverging copies rot within a month. If unsure how an agent imports files, say so and use the plain pointer sentence "Read AGENTS.md first."

## Workflow

1. **Find what exists.** Look for current agent files, the README, CI config, the task runner and the package manifest. If an instructions file exists, record its line count and token estimate (chars / 4) as the "before".
2. **Read the repo like a new hire.** Directory tree two levels deep, the manifest scripts, test config, lint and format config, `git log --oneline -30` for commit style, one representative source file per layer. Say in one line what you read.
3. **Run the commands.** Install, build, typecheck, lint and test, narrowest scope first. Record the exact command that works, how long it takes, and what it needs (env vars, services, a seeded database). A command you did not run does not go in the file.
4. **Collect gotchas.** Ask the user once, in a single message: "What does the agent get wrong in this repo? What would you tell a new teammate on day one?" Also look for generated files that must not be edited, lockfile rules, required env var names, slow or flaky tests, and folders that look dead but are live.
5. **Filter every candidate line** with the test below. Delete what fails.

Install

One command, in your project folder. It detects your agent; add --agent all for every agent.

npx proskills-cli add agents-md-architect

Or copy the skill folder (the one holding SKILL.md) into the directory your agent reads, then restart it or start a new session.

More from Agent Ops

• Context Diet$9Cut token waste, with before and after numbers.
• Subagent Designer$9Split work into agents that earn their keep.
• Skill Author$12Write skills that score 90+ on the scanner.