#Building AGENTS.md files Thread...
honest mica
So I created this very cool utility that assembles a single high-level AGENTS.md from a collection of templates. It's sort of the reverse of Skills.
In my scenario, I have different OS, Local/Remote, Cloud, WSL, specific criteria for individual systems, and then general material that applies to all systems. It's been extremely difficult to manage the high-level AGENTS.md file across all of these environments - a single change can require manual edits in all of the systems.
With this new system, the file is built from templates, so from the CLI or a script I build for the OS, Location, Environment, and System, and it pulls in the directives appropriate for that configuration.
Next steps:
- Auto-generate all files whenever a change is made to any of the templates.
- Push generated files to gist.
- Have OS-level boot (or similar init) for each system pull in the gist for the next Codex session.
- Break down the AGENTS.md into Skills.md and Agents.md.
- Refine instructions for small text blocks that are in OpenAI GUI for account-level Custom Instructions, Project Instructions, and Codex Cloud Instructions, and Codex App Instructions. (And oh I wish they'd centralize this stuff.)
Future:
- I'm thinking this can be used for any content that has common components across different environments. For example, to change a dependency version across a bunch of projects, have projects regenerate their config files (like package.json) from templates that pull in the version from a single source of truth.
- There are contract management applications that do this document assembly from templates, so the concept is sound, but I'm content with continuing to use this just for building documentation and maybe config files for now.
edgy quail
It's for sure not gonna be deprecated. I do think the ultimate solution is combining a really lightweight AGENTS.md with a moderately stacked skill set. The biggest pitfall you can run into is having more documentation than actual code, and having documentation drift from repo reality.
To keep the skills and the AGENTS.md from getting too heavy, drop a
Use unit tests and integration tests to understand the architecture of the application. Tests are authoritative and are the spec of the application.
Now, rather than maintaining docs about the code, you're maintaining tests that collectively describe the behavior and the architecture.
The AI assistants, when they look at a unit test, they see what you and I would see in a markdown instantly. It kills 2 birds: confirms the software works the way it's supposed to, and describes the software.
honest mica
(Sincere thanks for your time and notes - I was wondering if this was a waste and someone was just going to say "Use Yeoman, dummy!".)
combining a really lightweight AGENTS.md with a moderately stacked skill set.
As you know, I'm going in that direction. This concept of building AGENTS files can apply to smaller targeted files as well. For now I'm just testing with big system ones.
Your suggestion about content for skills and agents is subjective. For this challenge I'm focused on assembling documents with any content. I know you know that, so thanks. 🙂
edgy quail
Hey, I have a couple AGENTS.md myself! One in ~/.codex/AGENTS.md, tells em to not run broad find or grep commands in my home folder (because it takes quite literally 20 minutes to scan several terabytes worth of tiny files), and one in my repos that is a short list of "absolutely never do this" stuff. The rest is skills and system prompts for specific roles.
Another trick you can try is composing instructions into -c developer_instructions="$COMPOSED", then you can write some script that pulls from multiple AGENTS.md files and does this:
codex -c developer_instructions="$(compose-instructions ui.md backend.md local.md)"
merge them on demand for that one agent. Then the AGENTS.md is generalized, but you want that one agent to be a local agent that works on the UI and the backend so it gets special additional instructions stacked on top of it!
Idk how that'd work on cloud though 😛
honest mica
Confirming that smaller agents are better, when augmented by skills.
Your "codex -c" example is pretty much what this utility does, except rather than doing it dynamically it generates static files. Your backend.md and local.md examples are spot on - what if those are similar or the same in several systems and then you want to change them or add some new file. That requires going into every system and finding all of the configs to modify. This utility centralizes most of that (maybe "all of that" soon).
This is also cross-platform, so once the instruction components are established, it takes one build operation per system to pull in all of the right instructions for that OS and it's local/remote environment conditions.
So with a single change to a well-structured set of files (like skills!) in my system, I can regen all of the agents files for Windows, Linux, MacOS, local and remote Raspberry Pi, Codex Cloud, etc.
edgy quail
That's cool! I didn't even think about platform agnosticism, where there's different instructions for doing stuff in powershell versus bash. That does sound handy!