What is agent-md-creator?

A guide for creating and maintaining AGENTS.md or CLAUDE.md files, which give coding agents instructions that are loaded across tasks. It also explains when a rule belongs in a hook or an on-demand skill instead.

Use it to design, edit, review, remove, or debug agent instructions. It helps decide where a rule should live and how to keep the always-loaded guidance focused.

It helps prevent global instruction files from becoming bloated, unreliable, or filled with rules that should be enforced elsewhere. It addresses common failures in how coding agents follow prompts.

agent-md-creator — Skill for Claude Code and Codex by companion-inc

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Any agent

npx skills add companion-inc/introspect --skill agent-md-creator

Clone the repo

git clone --depth 1 https://github.com/companion-inc/introspect

Made for: Claude Code, Codex.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/skills/companion-inc/introspect/agent-md-creator/github.svg)](https://agentmods.dev/skills/companion-inc/introspect/agent-md-creator)

Your own site

<a href="https://agentmods.dev/skills/companion-inc/introspect/agent-md-creator"><img src="https://agentmods.dev/badge/skills/companion-inc/introspect/agent-md-creator/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/skills/companion-inc/introspect/agent-md-creator"><img src="https://agentmods.dev/badge/skills/companion-inc/introspect/agent-md-creator.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 60 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.

When invoked 2,064 The whole file, excluding the scripts and references it only reads on demand.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.00060	$0.02064
Opus 5.5	$0.00024	$0.00826
Sonnet 5.5	$0.00012	$0.00413
Haiku 4.5	$0.00006	$0.00206

Measured 2mo ago against content hash 952c5aae421e, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

agent-md-creator scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2mo ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

skills/agent-md-creator/SKILL.md · 77 lines

How it starts

The opening of the file, as written. The whole thing — 77 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Agent MD creator

The one truth everything follows from

A prompt is soft conditioning on a probability distribution, not control. An LLM is a next-token predictor trained by imitation (so it defaults to the modal / consensus continuation), then RLHF'd to maximize a proxy for human approval (so it agrees, looks-done, and capitulates under pushback), running stateless with no reliable metacognitive monitor (so it cannot feel its own memory or limits). Every common agent failure is one of these three facts seen from a different angle. Therefore a prompt can raise the probability of a behavior but never guarantee it, and adherence decays as the file grows. Design around this; don't fight it.

Layer map — put each rule where it can actually work

Prompt (advisory): judgment, approach, taste — "what good looks like." Followed most of the time, not all.
Hooks / harness (deterministic): non-negotiables that must happen every time. The only layer outside the sampled token stream, so the only one that enforces.
Skills (on-demand): workflows relevant only sometimes — keep them out of the always-loaded prompt.
Training: moves the floor. Not yours to change; the frontier failures (first-principles reasoning, self-monitoring, taste) live here — no prompt line fixes them.

If a rule must hold 100% of the time, it is a hook, not a prompt line.

Scope map — global, project, override, local

Codex global: ~/.codex/AGENTS.md, or ~/.codex/AGENTS.override.md when the entire global file must be replaced. Use only for cross-project invariants.
Codex project: AGENTS.md in the repo root or nested directory. Codex concatenates global, repo, and nested files; later/closer files win on conflicts.
Codex override: AGENTS.override.md replaces the regular AGENTS.md for that directory level. Use it only for a subtree that must not inherit that level's normal guidance.
Claude project: Claude reads CLAUDE.md, not AGENTS.md; create CLAUDE.md with @AGENTS.md when shared repo guidance should load in Claude, then append Claude-only additions below it.
Claude local: CLAUDE.local.md is private project-specific guidance and should be gitignored.
Project skills: Codex repo skills live under .agents/skills/<skill>/SKILL.md; Claude project skills live under .claude/skills/<skill>/SKILL.md. Use them for codebase-specific workflows that should not follow the user everywhere.

Read the full file on GitHub · 77 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

2mo ago First seen · 77 lines · 60 tokens per session scan A 952c5aae421e

Subscribe to this mod's changes

agent-md-creator is a skill published in the GitHub repository companion-inc/introspect (10 stars, last pushed 2mo ago), licensed MIT. It adds 60 tokens to every session and 2,064 once invoked, about $0.0002 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Building agents Writing and docs

agent-md-creator next to 6 skills from other repositories
Mod	Type	Stars	Last push	Licence	Scan	Tokens	Works with
agent-md-creatorcompanion-inc/introspect	Skill	10	2mo ago	MIT	A	60	Claude Code, Codex
imagegenopenai/codex	Skill	133k	yesterday	Apache-2.0	A	113	Codex
playwright-climicrosoft/playwright	Skill	99k	yesterday	Apache-2.0	A	19	Claude Code
local-ai-agentsmicrosoft/ai-agents-for-beginners	Skill	79k	4d ago	MIT	A	200	Claude Code, Codex
systematic-debuggingobra/superpowers	Skill	313k	3d ago	MIT	A	21	Claude Code
next-cache-components-adoptionvercel/next.js	Skill	143k	yesterday	MIT	A	95	Claude Code
next-partial-prefetching-adoptionvercel/next.js	Skill	143k	yesterday	MIT	A	103	Claude Code