---
name: setup-agent-skills
description: Configure AGENTS.md and docs/agents so engineering skills share an issue tracker, triage-label vocabulary, and domain-doc layout. Run once before using the other engineering workflow skills in a repo.
disable-model-invocation: true
---

# Setup Agent Skills

Scaffold the per-repo configuration used by the engineering skills:

- **Issue tracker** — where tickets live and how tracker operations work
- **Triage labels** — the strings used for the five canonical triage roles
- **Domain docs** — where `CONTEXT.md` and ADRs live

This is a prompt-driven skill. Explore first, recommend from the evidence, confirm with the user, then write.

## Process

### 1. Explore

Read the repo's existing state. Do not assume:

- `git remote -v` and `.git/config` — inventory GitHub, GitLab, and other hosted services, but do not select one only because a remote exists
- `.beads/`, `bd --help`, or `command -v bd` — is Beads already configured or available?
- `.sandcastle/` — does existing automation already select Beads or another tracker?
- `.scratch/` — is the local-Markdown convention already in use?
- `AGENTS.md` and `CLAUDE.md` — which instruction file exists, and is either a symlink to the other?
- `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/`, and any `src/*/docs/adr/` directories
- `docs/agents/` — has this skill run before?
- Whether the `triage` skill is installed
- Whether `to-qa` and `wayfinder` are installed
- Monorepo signals such as `pnpm-workspace.yaml`, a `workspaces` field in `package.json`, or populated `packages/*` directories with their own source trees

### 2. Present findings and ask

Summarise what exists and what is missing. Take the sections in order, one answer at a time. Lead with the recommended answer. Skip a question when exploration already settled it.

**Section A — Issue tracker.**

Use a local-first recommendation:

1. If `.beads/` exists or existing automation uses `bd`, recommend **Beads**.
2. Otherwise, if `.scratch/` already follows the local-Markdown convention, recommend **Local Markdown**.
3. Otherwise recommend **Local Markdown**, while naming any detected GitHub or GitLab remote as an explicit hosted option.

Never select a hosted tracker only because a Git remote exists. Offer these choices:

- **Beads** — tickets live in `.beads/` and use the `bd` CLI
- **Local Markdown** — tickets live under `.scratch/<feature>/`
- **GitHub** — tickets live in GitHub Issues and use the `gh` CLI
- **GitLab** — tickets live in GitLab Issues and use the `glab` CLI
- **Other** — ask the user to describe the workflow in one paragraph

Record the choice in `docs/agents/issue-tracker.md`. The GitHub and GitLab templates default external PRs or MRs as a request surface to **off**. Leave that default in place without adding another interview question; the user can change the flag in the generated file.

**Section B — Triage-label vocabulary.**

Skip this section if `triage` is not installed. Otherwise ask one question:

> Do you want to keep the default triage labels? (recommended: **yes**)

The five canonical roles are `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, and `wontfix`. On yes, keep those exact strings. Only collect overrides when the repo already uses different label names.

**Section C — Domain docs.**

Default to **single-context**: one root `CONTEXT.md` and `docs/adr/`. Write that choice without asking when the repo has no substantial monorepo structure.

Only when exploration finds genuine monorepo signals, offer **multi-context**: a root `CONTEXT-MAP.md` pointing to per-context `CONTEXT.md` files and ADR directories. Ask the user to confirm which layout fits.

### 3. Confirm and edit

Show the user a draft of:

- The `## Agent skills` block for the repo instruction file
- `docs/agents/issue-tracker.md`
- `docs/agents/domain.md`
- `docs/agents/triage-labels.md`, only when `triage` is installed

Let the user edit the draft before writing.

### 4. Write

Treat `AGENTS.md` as canonical when it exists:

- If `AGENTS.md` exists, edit it. If `CLAUDE.md` is a symlink to it, do not replace the symlink.
- Otherwise, if `CLAUDE.md` exists, edit it rather than creating a duplicate instruction file.
- If neither exists, ask the user which one to create.

Update an existing `## Agent skills` block in place and preserve surrounding content.

The block:

```markdown
## Agent skills

### Issue tracker

[one-line summary of where tickets are tracked]. See `docs/agents/issue-tracker.md`.

### Triage labels

[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.

### Domain docs

[one-line summary of the domain-doc layout]. See `docs/agents/domain.md`.
```

Omit the triage-label sub-block and file when `triage` is not installed.

Write the docs from these seed templates:

- [issue-tracker-beads.md](./issue-tracker-beads.md)
- [issue-tracker-local.md](./issue-tracker-local.md)
- [issue-tracker-github.md](./issue-tracker-github.md)
- [issue-tracker-gitlab.md](./issue-tracker-gitlab.md)
- [triage-labels.md](./triage-labels.md), only when `triage` is installed
- [domain.md](./domain.md)

Render tracker templates against the installed skills rather than copying unresolved placeholders:

- When `triage` is installed, replace every canonical triage-role label in the selected tracker template with the configured label from `triage-labels.md`.
- When `triage` is absent, omit triage-only queue operations and keep the canonical `ready-for-agent` and `ready-for-human` labels used by `to-tickets` and `wayfinder`.
- Keep the structured parent/child and completion contract required by `to-qa`, and keep separate AFK and HITL frontier operations required by `wayfinder`.

For another tracker, write `docs/agents/issue-tracker.md` from the user's description.

### 5. Done

Report what was configured and which engineering skills read the files. The user can edit `docs/agents/*.md` directly later; rerun setup only when switching workflows or rebuilding the configuration.