awesome-agent-skills: Instructions file for Codex

AGENTS.md

Rules for this repository, on top of whatever global guidance an agent already loads.

Examples in a skill are abstract, never real

A skill teaches a rule; it never carries a sample of anyone's actual work. Every example in SKILL.md and in references/ is a shape or a placeholder — what the sentence does, not the sentence itself.

Never a real post, a real account, a real person's text, a captured run, a screenshot of one, or anything copied from the author's own published writing. Two reasons, each sufficient: that material is private and does not belong in a published skill, and a sentence printed in a skill comes back verbatim in the next run's output.

Evals measure a description, and they live outside the skill

A rule a skill states is proved by reading it, and a check it prescribes is proved by running it on the work in hand. Neither settles the one question reading cannot reach: whether a description fires on the prompts it should and stays quiet on the ones it should not. With forty-odd skills whose boundaries touch each other, that is decided by measurement or it is not decided at all. So evals are allowed, on these terms.

A set lives where the convention puts it, inside the skill it measures. <skill>/evals/eval_queries.json holds the trigger set, <skill>/evals/evals.json the output cases. That is what the published practice specifies and what the tooling that runs these loops looks for, and a set that travels with its skill cannot drift away from the description it was written against. Those two filenames are the entire allowance: no third file, no files/ fixtures, nothing that executes. What an installed user gains is a few kilobytes of text that no run ever opens - the body still loads at activation, references/ still loads on demand, and evals/ is read by nobody but the maintainer measuring a description.

Run output is not repository content. Iterations, gradings, benchmarks, transcripts, and any input file a case needs stay outside the clone, in the agent's own scratch folder. They go stale the moment a model version moves, they carry whatever the run happened to read, and a committed fixture is the exact thing the first rule of this file forbids.