Menu
Configure this repo for the engineering skills โ set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
Implement a piece of work based on a spec or set of tickets.
Reconcile the OKF knowledge bundle (knowledge/) with what a completed code change built, over that change's diff. Use once a change has finished landing โ the build closeout, just before committing โ or when the user asks to reconcile knowledge against code.
Turn the current conversation into a spec and save it to the OKF knowledge bundle โ no interview, just synthesis of what you've already discussed.
Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker โ edges as text in a local file, or native blocking links on a real tracker.
Plan a huge chunk of work โ more than one agent session can hold โ as a shared map of investigation tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
| name | setup-okf-matt-skills |
| description | Configure this repo for the engineering skills โ set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills. |
| disable-model-invocation | true |
Scaffold the per-repo configuration that the engineering skills assume:
knowledge/) lives, and the consumer rules for reading itAll three land in the agent layer at knowledge/_agents/ โ a reserved, _-prefixed
service directory inside the OKF bundle that holds agent-operational config and notes, and
is never a domain context (see "The agent layer" below).
This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
Look at the current repo to understand its starting state. Read whatever exists; don't assume:
git remote -v and .git/config โ is this a GitHub repo? Which one?AGENTS.md and CLAUDE.md at the repo root โ does either exist? Is there already an ## Agent skills section in either?knowledge/ โ the OKF knowledge bundle at the repo root (knowledge/glossary/, knowledge/adr/, knowledge/index.md), including any per-context subdirectoriesknowledge/_agents/ โ does this skill's prior output already exist? (Legacy repos may have it under knowledge/_agents/ โ an earlier layout; if you find that, migrate it to knowledge/_agents/ as part of this run.).scratch/ โ sign that a local-markdown issue tracker convention is already in useSummarise what's present and what's missing. Then walk the user through the three decisions one at a time โ present a section, get the user's answer, then move to the next. Don't dump all three at once.
Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why these skills need it, what changes if they pick differently). Then show the choices and the default.
Section A โ Issue tracker.
Explainer: The "issue tracker" is where issues live for this repo. Skills like
to-tickets,triage,to-spec, andqaread from and write to it โ they need to know whether to callgh issue create, write a markdown file under.scratch/, or follow some other workflow you describe. Pick the place you actually track work for this repo.
Default posture: these skills were designed for GitHub. If a git remote points at GitHub, propose that. If a git remote points at GitLab (gitlab.com or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:
gh CLI)glab CLI).scratch/<feature>/ in this repo (good for solo projects or repos without a remote)If โ and only if โ the user picked GitHub or GitLab, ask one follow-up:
Explainer: Open-source repos often receive feature requests as pull requests, not just issues โ a PR is an issue with attached code. If you turn this on,
/triagepulls external PRs into the same queue and runs them through the same labels and states as issues (collaborators' in-flight PRs are left alone). Leave it off if PRs aren't a request surface for you.
knowledge/_agents/issue-tracker.md. For local-markdown and other trackers, skip this question โ there are no PRs.Section B โ Triage label vocabulary.
Explainer: When the
triageskill processes an incoming issue, it moves it through a state machine โ needs evaluation, waiting on reporter, ready for an AFK agent to pick up, ready for a human, or won't fix. To do that, it needs to apply labels (or the equivalent in your issue tracker) that match strings you've actually configured. If your repo already uses different label names (e.g.bug:triageinstead ofneeds-triage), map them here so the skill applies the right ones instead of creating duplicates.
The five canonical roles:
needs-triage โ maintainer needs to evaluateneeds-info โ waiting on reporterready-for-agent โ fully specified, AFK-ready (an agent can pick it up with no human context)ready-for-human โ needs human implementationwontfix โ will not be actionedDefault: each role's string equals its name. Ask the user if they want to override any. If their issue tracker has no existing labels, the defaults are fine.
Section C โ Domain docs.
Explainer: Some skills (
improve-arch,debug,tdd) read the project's OKF knowledge bundle (knowledge/) to learn the domain language (knowledge/glossary/) and past architectural decisions (knowledge/adr/). They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.
Confirm the layout:
knowledge/ bundle with glossary/ and adr/ at its root. Most repos are this.knowledge/ bundle whose index.md is a context map, with each context as a subdirectory (knowledge/<context>/glossary/, knowledge/<context>/adr/) and system-wide decisions in knowledge/adr/ (typically a monorepo).knowledge/_agents/)The three config files above are not domain knowledge โ they describe how an agent operates in this repo (tooling, labels, how to read the domain). They live in a dedicated service directory inside the OKF bundle:
knowledge/
โโโ index.md # domain context map โ does NOT list _agents
โโโ _agents/ # the agent layer (reserved, not a domain context)
โ โโโ index.md # gatekeeper: what belongs here, what doesn't
โ โโโ issue-tracker.md # A โ operational config
โ โโโ triage-labels.md # A
โ โโโ domain.md # A โ consumer rules for reading the domain bundle
โ โโโ notes/ # B โ accumulated operational knowledge, grows lazily
โ โโโ index.md
โโโ <domain contextsโฆ>
Isolation contract. Any subdirectory of knowledge/ whose name starts with _ is a
reserved service directory, never a domain context. Domain consumers (domain-modeling,
improve-arch, tdd, debug) navigate via the context map in knowledge/index.md and skip
_-prefixed dirs โ so _agents never pollutes the domain model. Keep _agents out of
knowledge/index.md's context list.
A vs B โ what goes in the agent layer:
A (config, fixed set): issue-tracker.md, triage-labels.md, domain.md. Stable
contracts, live at the _agents/ root.
B (notes/, grows lazily): operational knowledge about this repo/tooling that is
neither domain nor global harness config โ tooling gotchas, local conventions, "why we do
it this way here". One file per note. Its index.md is the gatekeeper.
What does not belong in notes/ (redirect it):
knowledge/<context>/glossary/, adr/adr/CLAUDE.md / AGENTS.mdUse the light OKF regime for _agents/: hand-maintained index.md files, plain markdown,
no required frontmatter. It's a small service folder โ full OKF entry frontmatter is
overkill here.
Show the user a draft of:
## Agent skills block to add to whichever of CLAUDE.md / AGENTS.md is being edited (see step 4 for selection rules)knowledge/_agents/issue-tracker.md, knowledge/_agents/triage-labels.md, knowledge/_agents/domain.mdLet them edit before writing.
Pick the file to edit:
CLAUDE.md exists, edit it.AGENTS.md exists, edit it.Never create AGENTS.md when CLAUDE.md already exists (or vice versa) โ always edit the one that's already there.
If an ## Agent skills block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
The block:
## Agent skills
### Issue tracker
[one-line summary of where issues are tracked, plus whether external PRs are a triage surface]. See `knowledge/_agents/issue-tracker.md`.
### Triage labels
[one-line summary of the label vocabulary]. See `knowledge/_agents/triage-labels.md`.
### Domain docs
[one-line summary of layout โ "single-context" or "multi-context"]. See `knowledge/_agents/domain.md`.
### Repo notes
Operational gotchas and local conventions for this repo โ consult `knowledge/_agents/notes/index.md` before assuming. When you learn a durable repo/tooling insight worth sharing with future agents, follow the notes protocol in `knowledge/_agents/index.md`.
Also add the OKF primer block to the same file. It grounds every agent in what the knowledge/ bundle is โ the base model does not know OKF a priori. Write it as a marked block so re-runs update it in place without touching anything else. If the <!-- okf-primer --> markers already exist, replace what's between them; otherwise add the block:
<!-- okf-primer:start -->
## Knowledge bundle (OKF)
This repo keeps durable knowledge in an [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) bundle at `knowledge/`. Each concept is a markdown file carrying a `type` frontmatter field; reserved files (`index.md`, `log.md`) carry no frontmatter. The canonical categories are `glossary/` (domain terms), `adr/` (decisions), and `prd/` (product requirements) โ but OKF is **open**: when a durable entity fits none of them, a new concept category is legitimate (propose it, get sign-off, register it in `knowledge/index.md`). The `_agents/` subdirectory is reserved agent-operational config, never a domain context.
<!-- okf-primer:end -->
Create the knowledge/_agents/ directory and write the config files using the seed
templates in this skill folder as a starting point:
_agents/index.md gatekeeper (what belongs, what doesn't)Also write:
knowledge/_agents/index.md โ from agents-index.md.knowledge/_agents/notes/index.md โ a stub index for the (initially empty) B notes:
a one-line heading plus "No notes yet." Notes are added lazily later.If a legacy docs/agents/ exists from an earlier layout, move its files into
knowledge/_agents/ and delete docs/agents/ (and docs/ if it's now empty).
For "other" issue trackers, write knowledge/_agents/issue-tracker.md from scratch using the user's description.
Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit knowledge/_agents/*.md directly later โ re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.