Setup Aclarify Skills
Writes the per-repository configuration the other skills read, and gets the
tools they depend on installed:
- Issue tracker: where issues live (GitHub by default; GitLab and local markdown supported).
- Triage labels: the label string for each triage role, when
triage is installed.
- Domain docs: the glossary file and layout, and where decision records go.
- Workspace: the scratch folder, an optional conventions folder, eval cases, code review.
- Tools: the
ocr CLI and its per-repository init, plus gh/glab where the tracker needs them; then, as its own question, OCR's two-reviewer default team.
Paths below are relative to this skill's directory; resolve them to absolute
paths before running anything. Commands that inspect the repository run from the
repository root.
This is a prompt-driven skill. Explore, present what you found, confirm with the
user, then write. With the argument check, run only step 1's tooling check and
step 2's Section E, and change nothing else.
1. Explore
Read what exists; assume nothing.
git remote -v: GitHub, GitLab, another host, or none?
AGENTS.md, CLAUDE.md and GEMINI.md at the root: which exist, whether one
is a symlink to another, whether CLAUDE.md/GEMINI.md already import
@AGENTS.md, and whether an ## Agent skills section exists in any of them.
docs/agents/: this skill's earlier output.
- Glossary files at the root:
GLOSSARY.md, GLOSSARY-MAP.md, CONTEXT.md, CONTEXT-MAP.md.
- Decision folders:
docs/adr/, docs/decisions/, decisions/, and src/*/docs/adr/.
- Scratch folders:
.scratchpad/, .scratch/; whether .gitignore covers them.
.ocr/ and .evals/.
- Which of this catalog's skills are installed, by name in your available skills
or as sibling skill folders: in particular
triage, wayfinder,
ocr-review-loop, harness-eval, watch-ci. A section for an uninstalled
skill is skipped.
- Monorepo signals:
pnpm-workspace.yaml, a workspaces field in
package.json, nx.json, or a populated packages/* with its own sources.
- Tooling: run
scripts/doctor.sh from the repository root and keep its output.
2. Present findings and ask
Summarise what is present and what is missing, then take the sections in order:
one section, one answer, then the next. Lead each with the recommended answer so
the user can accept it in a word. Skip a section when exploration already
settled it. To ask, use your structured-question tool if you have one;
otherwise list numbered options in plain text and stop until the user replies.
Section A: Issue tracker. Skills such as wayfinder, triage and
to-questionnaire read from and write to it, so they need to know whether to
call gh issue create, glab issue create, write a markdown file, or follow
another workflow. Propose GitHub when the remote is GitHub and GitLab when it is
GitLab. Otherwise offer:
- GitHub: issues in the repository's GitHub Issues, through
gh.
- GitLab: issues in GitLab Issues, through
glab.
- Local markdown: issue files under
.scratch/<feature>/, committed with the
repository so the whole team sees them. This is not the git-ignored scratch
folder of Section D, which holds one person's working files.
- Other (Jira, Linear, …): the user describes the workflow in a paragraph,
recorded as prose.
The GitHub and GitLab templates carry a "PRs as a request surface" flag,
defaulted off. Leave it off and don't raise it.
Section B: Triage labels. Only when triage is installed. Ask exactly one
question: keep the default labels (needs-triage, needs-info,
ready-for-agent, ready-for-human, wontfix)? Recommended: yes. On no,
collect the overrides so triage applies existing labels rather than creating
duplicates.
Section C: Domain docs. Default to single-context: one glossary file at the
root and one decision folder. If a glossary or decision folder already exists,
propose keeping its name and location (a repository with CONTEXT.md keeps
CONTEXT.md); otherwise GLOSSARY.md and docs/adr/. Offer multi-context (a
root map file pointing at one glossary per context) only when exploration found
monorepo signals.
Section D: Workspace. Propose, in one message:
- Scratch folder
.scratchpad/ (or the one that exists), added to .gitignore.
- Conventions folder: none, unless one exists (
docs/standards/,
docs/engineering/standards/, CONVENTIONS.md).
- Brand kit: none, unless a brand folder exists (
docs/brand/, brand/), only
when get-brand-kit, brand-review, create-html-slides or design-expert
is installed.
- Eval cases
.evals/cases/, only when harness-eval is installed.
- Checks before commit: the command
AGENTS.md, the contributing guide or CI
already runs (npm test, make check, …), if exactly one is evident.
- Code review: Open Code Review, only when
ocr-review-loop is installed.
Section E: Tools. Each line of the doctor output starts with a status:
ok; missing; outdated (older than a skill needs); absent (only needed for
an option this repository may not use); and, for ocr-team only, default
(OCR's own stock team) or custom (a team the repository chose: other personas
or counts, a pinned model, a custom name, or its own comment).
List each missing or outdated tool that an installed skill needs, with the
reason and the exact install command. Ask once which to install. Then, for each
the user agreed to:
ocr: run scripts/doctor.sh install ocr.
- OCR in this repository (
ocr-init missing): ask which agent tools to
configure, recommending the one you are running in plus any whose config
folder exists (.claude/, .codex/, .cursor/, .gemini/, .github/,
.opencode/, .windsurf/). Run scripts/doctor.sh init-ocr <ids> with the
comma-separated ids the doctor output lists. The new .ocr/config.yaml holds
OCR's stock team, so re-run scripts/doctor.sh and take the review team below.
gh, glab, Node.js: show the install line; the user runs it. gh auth login
is always the user's to run.
The review team is a separate question, because it changes how this
repository is reviewed rather than upgrading a tool. Agreeing to install or
initialise OCR does not answer it. Ask it once, after the installs, from the
ocr-team line of the latest doctor output:
ocr-team default: OCR's stock team, which every ocr init writes. Ask
whether to cap reviews at two reviewers, one principal and one architect, where
a better-fitting lens is swapped in, never added. Tell the user what the cap
overrides, in this sentence: "The cap overrides OCR's auto-added security and
testing reviewers: a review gets two reviewers even on auth, API, data or
logic-heavy changes." Recommend the cap. Only on a yes, run
scripts/doctor.sh set-ocr-team. It sets default_team in
.ocr/config.yaml to one principal and one architect, with a comment stating
the cap.
ocr-team custom: the repository already chose its own team. Ask whether to
replace it with the capped principal plus architect, with the same sentence;
recommend keeping it. Only on a yes, run scripts/doctor.sh set-ocr-team --force.
ocr-team ok: the cap is already set; ask nothing.
If an install fails, print the command for the user to run and carry on with
the rest. Re-run scripts/doctor.sh at the end and show the result.
3. Confirm
Show the user a draft of:
- the
## Agent skills block (step 4);
docs/agents/issue-tracker.md, docs/agents/domain.md,
docs/agents/workspace.md, and docs/agents/triage-labels.md when Section B ran.
Let them edit before anything is written.
4. Write
The instructions file. AGENTS.md holds the block, because every harness
reads it or can import it.
- If
AGENTS.md exists, edit it.
- If only
CLAUDE.md exists, ask whether to create AGENTS.md (recommended)
or put the block in CLAUDE.md. Codex and Cline do not read CLAUDE.md.
- If neither exists, ask which to create; recommend
AGENTS.md.
- When
AGENTS.md holds the block and CLAUDE.md exists but neither is a
symlink to the other nor imports it, add a line @AGENTS.md to CLAUDE.md.
Do the same for GEMINI.md.
If an ## Agent skills section exists, update it in place. Never touch the
surrounding sections.
## Agent skills
### Issue tracker
[one line: where issues are tracked]. See `docs/agents/issue-tracker.md`.
### Triage labels
[one line: the label vocabulary]. See `docs/agents/triage-labels.md`.
### Domain docs
[one line: single- or multi-context, glossary file, decision folder]. See `docs/agents/domain.md`.
### Workspace
[one line: scratch folder, conventions folder, code review]. See `docs/agents/workspace.md`.
Include ### Triage labels only when Section B ran.
The docs files. Write them from the seed templates, adjusting names and paths
to the answers:
templates/issue-tracker-github.md, templates/issue-tracker-gitlab.md,
templates/issue-tracker-local.md: the chosen tracker. For "other", write
docs/agents/issue-tracker.md from the user's description.
templates/triage-labels.md: only when Section B ran.
templates/domain.md: replace GLOSSARY.md, GLOSSARY-MAP.md and
docs/adr/ with the chosen glossary file, map file and decision folder.
templates/workspace.md: drop the lines for skills that are not installed.
When Section B ran on GitHub or GitLab, create each configured label the tracker
lacks (gh label create / glab label create).
Add the scratch folder to .gitignore when it is not covered.
5. Done
Tell the user which skills now read which file, the final tooling status, and
anything left for them to run themselves. They can edit docs/agents/*.md
directly later; re-running this skill is only needed to switch trackers, install
tools, or start over.
1---2name: setup-aclarify-skills3description: "Configure this repository for the Aclarify skills: where issues, the glossary, decision records and scratch files live, then check and install the tools some skills need, such as the ocr CLI for code review. Run once per repository before first use, and again with `check` to re-verify the tooling."4disable-model-invocation: true5argument-hint: "[check]"6license: MIT7metadata:8 source: https://skillmd.com/skills/spencermarx/setup-aclarify-skills9 credits: "Adapted from Matt Pocock's setup-matt-pocock-skills, https://github.com/mattpocock/skills (MIT)"10---1112# Setup Aclarify Skills1314Writes the per-repository configuration the other skills read, and gets the15tools they depend on installed:1617- **Issue tracker:** where issues live (GitHub by default; GitLab and local markdown supported).18- **Triage labels:** the label string for each triage role, when `triage` is installed.19- **Domain docs:** the glossary file and layout, and where decision records go.20- **Workspace:** the scratch folder, an optional conventions folder, eval cases, code review.21- **Tools:** the `ocr` CLI and its per-repository init, plus `gh`/`glab` where the tracker needs them; then, as its own question, OCR's two-reviewer default team.2223Paths below are relative to this skill's directory; resolve them to absolute24paths before running anything. Commands that inspect the repository run from the25repository root.2627This is a prompt-driven skill. Explore, present what you found, confirm with the28user, then write. With the argument `check`, run only step 1's tooling check and29step 2's Section E, and change nothing else.3031## 1. Explore3233Read what exists; assume nothing.3435- `git remote -v`: GitHub, GitLab, another host, or none?36- `AGENTS.md`, `CLAUDE.md` and `GEMINI.md` at the root: which exist, whether one37 is a symlink to another, whether `CLAUDE.md`/`GEMINI.md` already import38 `@AGENTS.md`, and whether an `## Agent skills` section exists in any of them.39- `docs/agents/`: this skill's earlier output.40- Glossary files at the root: `GLOSSARY.md`, `GLOSSARY-MAP.md`, `CONTEXT.md`, `CONTEXT-MAP.md`.41- Decision folders: `docs/adr/`, `docs/decisions/`, `decisions/`, and `src/*/docs/adr/`.42- Scratch folders: `.scratchpad/`, `.scratch/`; whether `.gitignore` covers them.43- `.ocr/` and `.evals/`.44- Which of this catalog's skills are installed, by name in your available skills45 or as sibling skill folders: in particular `triage`, `wayfinder`,46 `ocr-review-loop`, `harness-eval`, `watch-ci`. A section for an uninstalled47 skill is skipped.48- Monorepo signals: `pnpm-workspace.yaml`, a `workspaces` field in49 `package.json`, `nx.json`, or a populated `packages/*` with its own sources.50- Tooling: run `scripts/doctor.sh` from the repository root and keep its output.5152## 2. Present findings and ask5354Summarise what is present and what is missing, then take the sections in order:55one section, one answer, then the next. Lead each with the recommended answer so56the user can accept it in a word. Skip a section when exploration already57settled it. To ask, use your structured-question tool if you have one;58otherwise list numbered options in plain text and stop until the user replies.5960**Section A: Issue tracker.** Skills such as `wayfinder`, `triage` and61`to-questionnaire` read from and write to it, so they need to know whether to62call `gh issue create`, `glab issue create`, write a markdown file, or follow63another workflow. Propose GitHub when the remote is GitHub and GitLab when it is64GitLab. Otherwise offer:6566- **GitHub:** issues in the repository's GitHub Issues, through `gh`.67- **GitLab:** issues in GitLab Issues, through `glab`.68- **Local markdown:** issue files under `.scratch/<feature>/`, committed with the69 repository so the whole team sees them. This is not the git-ignored scratch70 folder of Section D, which holds one person's working files.71- **Other** (Jira, Linear, …): the user describes the workflow in a paragraph,72 recorded as prose.7374The GitHub and GitLab templates carry a "PRs as a request surface" flag,75defaulted off. Leave it off and don't raise it.7677**Section B: Triage labels.** Only when `triage` is installed. Ask exactly one78question: keep the default labels (`needs-triage`, `needs-info`,79`ready-for-agent`, `ready-for-human`, `wontfix`)? Recommended: yes. On no,80collect the overrides so `triage` applies existing labels rather than creating81duplicates.8283**Section C: Domain docs.** Default to single-context: one glossary file at the84root and one decision folder. If a glossary or decision folder already exists,85propose keeping its name and location (a repository with `CONTEXT.md` keeps86`CONTEXT.md`); otherwise `GLOSSARY.md` and `docs/adr/`. Offer multi-context (a87root map file pointing at one glossary per context) only when exploration found88monorepo signals.8990**Section D: Workspace.** Propose, in one message:9192- Scratch folder `.scratchpad/` (or the one that exists), added to `.gitignore`.93- Conventions folder: none, unless one exists (`docs/standards/`,94 `docs/engineering/standards/`, `CONVENTIONS.md`).95- Brand kit: none, unless a brand folder exists (`docs/brand/`, `brand/`), only96 when `get-brand-kit`, `brand-review`, `create-html-slides` or `design-expert`97 is installed.98- Eval cases `.evals/cases/`, only when `harness-eval` is installed.99- Checks before commit: the command `AGENTS.md`, the contributing guide or CI100 already runs (`npm test`, `make check`, …), if exactly one is evident.101- Code review: Open Code Review, only when `ocr-review-loop` is installed.102103**Section E: Tools.** Each line of the doctor output starts with a status:104`ok`; `missing`; `outdated` (older than a skill needs); `absent` (only needed for105an option this repository may not use); and, for `ocr-team` only, `default`106(OCR's own stock team) or `custom` (a team the repository chose: other personas107or counts, a pinned model, a custom name, or its own comment).108109List each `missing` or `outdated` tool that an installed skill needs, with the110reason and the exact install command. Ask once which to install. Then, for each111the user agreed to:112113- `ocr`: run `scripts/doctor.sh install ocr`.114- OCR in this repository (`ocr-init` missing): ask which agent tools to115 configure, recommending the one you are running in plus any whose config116 folder exists (`.claude/`, `.codex/`, `.cursor/`, `.gemini/`, `.github/`,117 `.opencode/`, `.windsurf/`). Run `scripts/doctor.sh init-ocr <ids>` with the118 comma-separated ids the doctor output lists. The new `.ocr/config.yaml` holds119 OCR's stock team, so re-run `scripts/doctor.sh` and take the review team below.120- `gh`, `glab`, Node.js: show the install line; the user runs it. `gh auth login`121 is always the user's to run.122123**The review team** is a separate question, because it changes how this124repository is reviewed rather than upgrading a tool. Agreeing to install or125initialise OCR does not answer it. Ask it once, after the installs, from the126`ocr-team` line of the latest doctor output:127128- `ocr-team` default: OCR's stock team, which every `ocr init` writes. Ask129 whether to cap reviews at two reviewers, one principal and one architect, where130 a better-fitting lens is swapped in, never added. Tell the user what the cap131 overrides, in this sentence: "The cap overrides OCR's auto-added security and132 testing reviewers: a review gets two reviewers even on auth, API, data or133 logic-heavy changes." Recommend the cap. Only on a yes, run134 `scripts/doctor.sh set-ocr-team`. It sets `default_team` in135 `.ocr/config.yaml` to one principal and one architect, with a comment stating136 the cap.137- `ocr-team` custom: the repository already chose its own team. Ask whether to138 replace it with the capped principal plus architect, with the same sentence;139 recommend keeping it. Only on a yes, run `scripts/doctor.sh set-ocr-team --force`.140- `ocr-team` ok: the cap is already set; ask nothing.141142If an install fails, print the command for the user to run and carry on with143the rest. Re-run `scripts/doctor.sh` at the end and show the result.144145## 3. Confirm146147Show the user a draft of:148149- the `## Agent skills` block (step 4);150- `docs/agents/issue-tracker.md`, `docs/agents/domain.md`,151 `docs/agents/workspace.md`, and `docs/agents/triage-labels.md` when Section B ran.152153Let them edit before anything is written.154155## 4. Write156157**The instructions file.** `AGENTS.md` holds the block, because every harness158reads it or can import it.159160- If `AGENTS.md` exists, edit it.161- If only `CLAUDE.md` exists, ask whether to create `AGENTS.md` (recommended)162 or put the block in `CLAUDE.md`. Codex and Cline do not read `CLAUDE.md`.163- If neither exists, ask which to create; recommend `AGENTS.md`.164- When `AGENTS.md` holds the block and `CLAUDE.md` exists but neither is a165 symlink to the other nor imports it, add a line `@AGENTS.md` to `CLAUDE.md`.166 Do the same for `GEMINI.md`.167168If an `## Agent skills` section exists, update it in place. Never touch the169surrounding sections.170171```markdown172## Agent skills173174### Issue tracker175176[one line: where issues are tracked]. See `docs/agents/issue-tracker.md`.177178### Triage labels179180[one line: the label vocabulary]. See `docs/agents/triage-labels.md`.181182### Domain docs183184[one line: single- or multi-context, glossary file, decision folder]. See `docs/agents/domain.md`.185186### Workspace187188[one line: scratch folder, conventions folder, code review]. See `docs/agents/workspace.md`.189```190191Include `### Triage labels` only when Section B ran.192193**The docs files.** Write them from the seed templates, adjusting names and paths194to the answers:195196- `templates/issue-tracker-github.md`, `templates/issue-tracker-gitlab.md`,197 `templates/issue-tracker-local.md`: the chosen tracker. For "other", write198 `docs/agents/issue-tracker.md` from the user's description.199- `templates/triage-labels.md`: only when Section B ran.200- `templates/domain.md`: replace `GLOSSARY.md`, `GLOSSARY-MAP.md` and201 `docs/adr/` with the chosen glossary file, map file and decision folder.202- `templates/workspace.md`: drop the lines for skills that are not installed.203204When Section B ran on GitHub or GitLab, create each configured label the tracker205lacks (`gh label create` / `glab label create`).206207Add the scratch folder to `.gitignore` when it is not covered.208209## 5. Done210211Tell the user which skills now read which file, the final tooling status, and212anything left for them to run themselves. They can edit `docs/agents/*.md`213directly later; re-running this skill is only needed to switch trackers, install214tools, or start over.