Agent Startup Map

Stop dumping everything into AGENTS.md.

Agent Startup Map is a small Codex skill for keeping global agent instructions short, durable, and easy for coding agents to load.

Created by AmazingPeach.

The core idea is progressive disclosure: the global agent file should be a startup map and router, while long procedures live in project AGENTS.md files, skills, templates, references, or a knowledge base.

Why This Exists

Long-running coding agents get worse when every rule, workflow, preference, project note, and checklist is pasted into one giant context file.

This skill helps decide what belongs in the startup map and what should move deeper into the agent harness.

Before / After

Before:

AGENTS.md
- global preferences
- project rules
- migration checklist
- one-off notes
- old commands
- long examples
- stale context

After:

~/agent.md
- stable global rules
- important paths
- skill triggers
- pointers to deeper files

project/AGENTS.md
- local project conventions

skills/*/SKILL.md
- repeatable workflows

Use Cases

• Decide whether an instruction belongs in a global agent map or a deeper workflow file
• Keep ~/agent.md short and stable
• Turn repeated workflows into reusable skills
• Prevent agent context files from becoming large, stale documentation dumps

Quickstart

Copy this directory into your Codex skills directory, then trigger it with requests such as:

Save this as a reusable agent instruction.
Should this go in agent.md or a project AGENTS.md?
Turn this workflow into an agent startup map entry.

Background

This skill is a practical application of agent harness engineering. The key idea is that long-running agents need external structure: durable files, concise maps, task-specific instructions, logs, feedback loops, and progressive disclosure.

In this framing, ~/agent.md is not a knowledge base. It is the entrypoint into a larger harness: it tells the agent what stable rules exist, where project-specific rules live, which skills should be loaded, and which deeper references should be opened only when needed.

Privacy Notes

This public version uses generic paths such as ~/agent.md and does not include personal vault paths, account identifiers, or private workflow details.

See PRIVACY_CHECKLIST.md before publishing your own adapted version.

References

• Harness engineering for coding agent users: feedforward guides, feedback sensors, and the idea that users can improve agent outcomes by shaping the surrounding harness.
• Effective harnesses for long-running agents: feature lists, progress logs, and persistent task state for long-running agent work.
• The Anatomy of an Agent Harness: the model-plus-harness view of agents, including filesystems, sandboxes, tools, and memory.
• Improving Deep Agents with harness engineering: self-verification, tracing, and context optimization as practical harness levers.
• Harness Engineering: Leveraging Codex in an Agent-First World: agent-readable codebases, plain-text coordination files, and the shift from writing every line to shaping the agent's working environment.