Agent File Architecture Skill

Agent File Architecture is an agent skill for Codex and other AI coding assistants. It establishes a lean, maintainable structure for repository guidance: a concise root AGENTS.md and selectively loaded detail guides under .agent/agent-file-extensions/.

It is useful when a repository's agent instructions are becoming too large, when detailed guidance needs clear subject-specific routing, or when an agent should load only the instructions relevant to its current work.

Why This Matters

Agent guidance may be re-read after context compression, session changes, or when work resumes. A small AGENTS.md lets an agent recover the essential project rules quickly and leaves more context for the actual task.

Detailed guidance stays in focused extensions and is loaded only when relevant. This makes instructions easier to maintain, avoids repeating the same rules, and gives both people and agents a clear place to find the right level of detail.

Installing Agent File Architecture

Install the skill with npx:

npx skills add https://github.com/Gucky/AgentFileArchitecture --skill agent-file-architecture

To install it globally for Codex:

npx skills add https://github.com/Gucky/AgentFileArchitecture --skill agent-file-architecture --agent codex --global

For a specific agent:

npx skills add https://github.com/Gucky/AgentFileArchitecture --skill agent-file-architecture --agent claude-code

For all supported agents:

npx skills add https://github.com/Gucky/AgentFileArchitecture --skill agent-file-architecture --agent '*'

Using Agent File Architecture

In Codex, trigger the skill directly:

$agent-file-architecture

Or ask naturally:

Use Agent File Architecture to split this oversized AGENTS.md into a lean entry point and focused guidance files.

The skill helps agents to:

• keep human-facing README material separate from agent-facing instructions;
• route agents from a concise AGENTS.md to only relevant detail guides;
• preserve context for the current work by keeping the entry-point instructions small; and
• keep reusable agent guidance separate from generated output and session-specific material.

Scope and Safety

The skill adapts to existing project conventions rather than replacing them. It does not prescribe a technology stack, rewrite source code, or place credentials, generated output, or session-specific material in agent instruction extensions.

Requirements

• Node.js for npx installation
• An AI coding assistant that supports agent skills

License

Agent File Architecture was created by Wolfgang Muhsal. It is available under the MIT License.