# Agents Init

> Initialize AGENTS.md for a new repo or workspace (including empty folders and polyrepo workspaces with frontend+backend). Generates a short, operational file aligned to GitHub Actions checks.

- Skill: `askaret/agents-init` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add askaret/agents-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/askaret/agents-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: askaret (https://skillmd.com/u/askaret)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/askaret/agents-init

---


# Goal
Create an `AGENTS.md` that makes the agent effective on day 1:
- Clear repo/workspace map
- "Golden commands" that match CI
- Conventions + guardrails
- Consistent task wrap-up expectations

# Supported scenarios
## A) Existing repo (single git root)
- Detect build/test/lint/format/run commands from the repo.
- Summarize CI-required checks from `.github/workflows/*`.
- Write/overwrite `<repo>/AGENTS.md` using the templates in `references/`.

## B) Empty repo (or too little signal)
- Ask the user a short questionnaire (below).
- Create a minimal `AGENTS.md` with explicit TODOs (no vague placeholders).

## C) Polyrepo workspace (e.g. `<root>/frontend` and `<root>/backend` are separate git repos)
- Treat the current directory as **workspace root** if it is not itself a git root.
- Detect child repos by locating `.git` markers under immediate subfolders.
- Generate:
  1) `<workspace>/AGENTS.md` (cross-cutting rules + repo map)
  2) Optional: `<workspace>/frontend/AGENTS.md` and `<workspace>/backend/AGENTS.md` (repo-specific commands)

# Discovery algorithm (do this, in order)
1. Determine scope:
   - Try `git rev-parse --show-toplevel`.
     - If it succeeds, you are in scenario A.
     - If it fails, you are in scenario B or C. Use the current directory as workspace root.
2. Detect language/tooling per folder:
   - .NET: `.sln`, `*.csproj`, `global.json`
   - Node: `package.json`, lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`)
   - Python/others: only if present; otherwise ignore.
3. Extract "golden commands":
   - Prefer commands found in CI or repo scripts over inventing new ones.
   - For Node, read `package.json` scripts.
   - For .NET, prefer solution/project commands that run fast and match CI.
4. Extract CI quality gates:
   - Inspect `.github/workflows/*.yml` for: build, test, lint, format, CodeQL, dependency review, SBOM/provenance attestations.
   - Reflect them as a checklist in `AGENTS.md` (only what exists today).
5. Generate `AGENTS.md`:
   - Use a template from `references/` and fill it with concrete commands and paths.
   - Keep the file short (~150-200 lines). Prefer links to docs over copy-pasting.
6. Validate:
   - If any key command is unknown (especially "Run"/"Dev"), ask the user to provide it.
   - Never leave "(fill in ...)" placeholders; use explicit `TODO:` bullets.

# Questionnaire (only ask if needed)
Ask the minimum number of questions to remove ambiguity:
1) Is this a **single repo** or a **workspace containing multiple repos**?
2) What are the main parts? (e.g. backend .NET, frontend React)
3) For each part:
   - Package manager (`npm`/`pnpm`/`yarn`) or `.NET` tooling
   - Golden commands: install/restore, build, test, lint/format, dev/run
4) Anything special: DB migrations, codegen (OpenAPI), infra (Terraform), container runtime.

# Hard rules to include in the generated AGENTS.md
- Align with GitHub Actions: prefer commands that CI actually runs.
- Security basics: never echo secrets; never commit secrets; avoid adding deps without approval.
- Output expectations: summary + commands run + tests + manual verification steps.

# Deliverables
- Write the appropriate `AGENTS.md` file(s).
- If polyrepo: ensure workspace `AGENTS.md` explains how to run commands per repo folder.
- If you created repo-level `AGENTS.md` too, keep them narrower and point to workspace/global rules.

Finish with:
- What files were created/updated (paths)
- The key commands captured
- Any remaining TODOs/questions for the user