Skip to content

AndrewBrown-USDA/aigb-skills-usda / skills/agent-onboarding

agent-onboarding

Verified

Create and maintain AGENTS.md files for project onboarding and grounding. Use when initialized in a new project, when project structure changes significantly, or when creating subfolder-level AGENTS.md files for complex monorepos.

Agent Onboarding

Generate AGENTS.md files that ground agents in project structure -- not in volatile state.

Commands

Create a new AGENTS.md:

/agent-onboarding create

Update an existing AGENTS.md after structural changes:

/agent-onboarding update

Create or update AGENTS.md for a subfolder (monorepo):

/agent-onboarding subfolder <path>

Philosophy: Catalog to Compass

AGENTS.md is a navigation map, not a snapshot of current state. It answers "where is X?" and "how do I do Y?" -- not "what are we working on today?"

Directory map, not content inventory

Show where things live. Directory structure is stable; contents change. Agents can ls to see what's inside.

  • Don't: "Dashboard components (currently 12 files, 3 pending refactor)"
  • Do: "src/dashboard/components/ -- run ls to see them"

Process, not state

Document how artifacts flow through their lifecycle, not their current status.

  • Don't: "API auth refactor (50% done), dashboard redesign (in review)"
  • Do: "Add work to TODO.md -> check off when done -> archive -> repeat"

Stable infrastructure, not ephemeral status

Record commands, file paths, port numbers. Don't record "current priorities" or "today's focus."

  • Don't: "We're fixing a latency regression discovered yesterday"
  • Do: "npm test --performance -> results in dist/benchmarks/"

Reference skills, not re-encode them

Point to skill files (/plan.md, SKILL.md). They are the source of truth. Don't duplicate.

  • Don't: Re-explain testing strategy in AGENTS.md
  • Do: "See [testing-strategy] for the full protocol"

Commands, not explanations

Show what to type. Agents can read the source if they need to understand internals.

  • Don't: "Webpack bundles TypeScript modules via a custom loader that extracts metadata..."
  • Do: "npm run build -> output in dist/"

AGENTS.md Structure

Organize in this order (commands and discovery first):

  1. Quick Start -- Essential commands to build, test, run, deploy
  2. Find Things -- Where code, config, and docs live (directory map)
  3. Workflows -- Lifecycle of tasks, artifacts, releases
  4. Infrastructure -- Stable file paths, ports, commands, configuration
  5. References -- Links to detailed skills or documentation

Use AGENTS_template.md as a starting point.

When to Create or Update

  • Create: New project with no AGENTS.md
  • Update: Project structure has changed (new directories, removed modules, moved entry points)
  • Don't update for: Changes to task status, current priorities, or file contents -- these are transient

Root vs. Subfolder

  • Root AGENTS.md: High-level map, workspace-wide commands, primary entry points
  • Subfolder AGENTS.md (monorepo): Independent context for a module or package (e.g., src/services/billing/AGENTS.md)

Detect the Ecosystem

Use patterns.md to identify language and architecture:

EcosystemSignaturesReference
Pythonpyproject.toml, setup.py, requirements.txtpatterns.md#python
JavaScript/Nodepackage.json, tsconfig.jsonpatterns.md#javascript
RustCargo.toml, Cargo.lockpatterns.md#rust
RDESCRIPTION, NAMESPACE, renv.lockpatterns.md#r
C/C++CMakeLists.txt, *.h, *.cpppatterns.md#cpp
JuliaProject.toml, Manifest.tomlpatterns.md#julia

Extract commands from build files (package.json, Makefile, pyproject.toml, Cargo.toml). They are the invariants of the project.

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall