Setup Agents — Reference Index

Routes to mode-specific reference files. Only load what the mode needs.

Mode routing

Mode	Load
generate	setup-agents-build.md, setup-agents-prompts.md, setup-agents-schemas.md, setup-agents-template.md
upgrade	setup-agents-build.md, setup-agents-prompts.md, setup-agents-schemas.md, setup-agents-template.md
add	setup-agents-add.md, setup-agents-prompts.md, setup-agents-schemas.md
review	setup-agents-review.md

Signal → Roster Decision Table

Signal	Confidence	Agent
Terraform / CDK / SAM / Pulumi + deploy workflow	HIGH	infra
FastAPI / Express / Rails / Spring / Spring Boot / Django	HIGH	app
build.gradle.kts / settings.gradle.kts / Kotlin source in src/main/kotlin/	HIGH	app (Kotlin/Spring Boot)
pom.xml or build.gradle with spring-boot-starter dependency	HIGH	app (Spring Boot)
GHA workflows are the product (reusable/composite)	HIGH	platform
pytest / jest / go test / rspec / JUnit / Kotest	MEDIUM	test-writer (offer)
Airflow / Prefect / dbt / Glue / Step Functions	HIGH	data-pipeline
torch / sklearn / sagemaker / mlflow	HIGH	ml
Any repo	ALWAYS	navigator (offer)
boto3 only, no IaC, no framework	AMBIGUOUS	ask 1 question
Monorepo with 3+ signals	MINIMUM SET	generate confident + ask team ownership

AGENTS.md — hand-authored detection

Line 1 check: <!-- generated by platform-skills -->

• Present → managed; overwrite freely
• Absent → hand-authored; read for context, append only

A marker check applies to every per-tool agent file too, but the marker is not always on line 1 — frontmatter formats (.agent.md, .mdc) carry it on line 2 so --- can stay at byte 0. Use the managed() helper (head -3) rather than a hand-rolled head -1. See references/setup-agents-schemas.md → "Managed-file marker" for the per-format rule — that file is the single source of truth for this rule.

.platform-skills/ — commit this directory

The .platform-skills/ directory is structural metadata — commit it. It is not personal state.

• Commit: manifest — defines which tool targets were generated; scripts/verify-agents.sh reads it. If gitignored, CI will silently skip all tool-target checks and report 0 issues.
• Nothing to exclude: the directory contains only the manifest — no secrets, no personal state. If .platform-skills/ is gitignored (e.g. via a .* glob), remove the exclusion.

.platform-skills/manifest — format

One token per line. Lines starting with # are comments. Blank lines ignored.

Valid tokens:

Token	File verified
copilot-vscode	.github/agents/<role>.agent.md — one per roster entry
copilot-cloud	.github/agents/<role>.agent.md — one per roster entry (cloud target)
copilot-app	.github/workflows/copilot-setup-steps.yml
cursor	.cursor/rules/*.mdc
claude	CLAUDE.md contains a ## Agent Context section
codex	agents/openai.yaml — setup-agents tooling metadata, not Codex config
windsurf	.windsurfrules
vscode-mcp	.vscode/mcp.json (servers key) or .vscode/settings.json (github.copilot.chat.mcpServers key)

copilot-vscode and copilot-cloud verify the same path. Listing both is valid; verify-agents.sh runs the shared Copilot check once, not twice.

There is no token for Codex-the-editor — Codex support is AGENTS.md, which the first check already covers. The codex token only says "this repo keeps the agents/openai.yaml roster/model record", which verify-agents.sh and upgrade mode consume. See references/setup-agents-schemas.md → "agents/openai.yaml — setup-agents tooling metadata".

Example:

# generated by platform-skills setup-agents
copilot-vscode
claude
codex

scripts/verify-agents.sh reads this file to know which checks to run. generate writes it at Step 9. add appends to it at Step 7. upgrade reads it to know which tool paths to scan.

The manifest says which targets; the ## Agent roster table in AGENTS.md says which agents. verify-agents.sh needs both to assert one file per agent per target. With an unparseable roster table it warns and falls back to presence-only checks, which pass as long as a single agent file survives.