eai-org/agent-toolkit

# Agentify project

Converge a project — greenfield or half-way-there — toward the canonical agent-neutral structure
specified in [references/target-structure.md](references/target-structure.md) (read it before the
audit), so a team of developers using different agents shares one lean, progressively disclosed
setup. Re-running converges further and reports drift.

Invocation: `/agentify-project [audit] [path]`

- `audit` — run step 1 only, print the findings and what a full run would change, modify nothing;
  the periodic drift check.
- `path` — target a subdirectory instead of the repo root (see Monorepos).

## Principles

# Attach to ticket

Save assets — pasted images, local files, URLs — into a ticket's planning directory and reference
them from its ticket file, so a fresh session picks them up. **Local only** — never query or modify
the tracker (no API calls, no re-fetch, no comments or edits); downloading an asset URL the user
supplies or a not-downloaded entry names is fine, tracker-hosted or not. Edit nothing in the
documents beyond the entries below and the REQUIREMENTS line of step 6.

## Your task

1. **Collect the assets.** The images pasted with the invocation, plus paths and URLs in its text;
   images pasted earlier only when the user points at them. Nothing pasted or pointed at → ask
   which, listing the images seen in the session. Done when every supplied asset is collected or
   dropped by the user.

# Check ticket implementation

Judge how much of a ticket is already implemented and report it so the user sees at a glance what
is done, what isn't, and what still needs attention.

## Gather

Input is a ticket URL / bare id — run [fetch-ticket](../fetch-ticket/SKILL.md) on it (it resolves
the tracker and planning dir and persists the `.TICKET.md`) — or a path to an already-fetched
ticket file or its task dir. Ambiguous input: ask, don't guess.

Run the fetch in a **subagent** when the runtime supports one, per fetch-ticket's
[delegate.md](../fetch-ticket/delegate.md), so its tool traffic stays out of this session's
context. Without subagent support, invoke fetch-ticket inline.

# Compact docs writer

Rewrite a doc — or draft a new one — for **token economy**: carry **all** its rules and intent in
the **least text possible**, because the doc loads into agent context and is paid for on every
read. Then prove nothing was lost: present the change with a word delta measured from the files,
and apply only on approval.

## Core principle

Write each piece of information with the least text that still preserves every rule, constraint,
edge case, and intent. Two directions, equally binding:

- Cut duplication, filler, and anything restatable more briefly.
- **Never** drop text whose removal loses information or instruction, just to be shorter.

# Compact skill creator

Author a new skill, or improve an existing one, so it carries **all** its rules and intent in the
**least text possible**. Cost has two tiers: the `description` sits in context *every* session — the
skill's most expensive text — while the body loads only when the skill triggers. Both stay lean. Be
interactive: gather what you need, draft, then apply only on approval.

## Compaction — always via compact-docs-writer

The compaction rules — the least-text principle, the removal-audit verification, and the
present-and-confirm with a measured word delta — live in
[compact-docs-writer](../compact-docs-writer/SKILL.md), the single source of truth; this skill never
restates or re-derives them. From the moment you draft (step 4) through self-review (step 5) and
present (step 6), **always** invoke compact-docs-writer and follow its workflow on the skill text —

# Context checkup

Find what loads **automatically** into the session's context at startup, quantify it, and propose
**reversible** trims ranked by payoff — shrink the startup context window by cutting what isn't
worth its tokens. Read-only — measure and recommend; change settings only on explicit approval.

## Mental model (spend attention top-down)

Cost hierarchy, biggest first:
1. **MCP tool schemas** — large, but **deferred** by tool search. Only a problem if tool search is
   OFF.
2. **Always-on text** — every always-on instruction file (entry-file chain, `@imports`, unscoped
   rules files) and **skill/agent/command descriptions**: every available one's description
   loads every session, except skills flagged non-model-invocable (their description never

# Create Implementation Plan

**Planning only** — no code changes, no execution. You produce one document: an implementation plan
that is the contract for a later execution session.

This is the **"how", not the "what"**. The "what" was settled in an earlier refinement step and
lives in the requirements document you're given; do not redefine scope. But you **must flag** any
gap, ambiguity, or inconsistency you find in the requirements — surface it, never paper over it.

## Golden rule

**Never guess — ask.** With one limit: anything resolvable by reading the codebase, resolve by
reading the codebase; only questions the code cannot settle go to the user.

# Create manual test instructions

## Resolve the input

- **Ticket or requirements document** (file or pasted text) — the only source: the checks follow
  it, and no code change is looked up.
- **Code change** — a branch, PR URL, commit range, pasted diff or patch file, or nothing (the
  current branch). A commit range is diffed between its own ends. A branch or PR: `git fetch` the
  remotes, then diff from the merge base `<base>` with the target — a PR's base from its
  metadata, else the default branch of the `upstream` remote when one exists, else of `origin`,
  via `git ls-remote --symref <remote> HEAD`; that failing, the sole existing candidate among
  `main`, `master`, `develop`/`development`, preferring `upstream`'s remote-tracking ref, then
  `origin`'s, then the local branch. `git diff <base> <source>` for a tip; a checked-out source
  is reviewed as its working tree: `git diff <base>` plus the untracked files

# Execute plan tasks

One task per run — implement it, verify it, tick it, stop. The review between tasks is the point;
never carry on into the next.

Invocation: `/execute-plan-tasks <plan-path> [task-id]`

## Pick the task

Read the plan whole — summary, conventions and overrides, the steps the task cites, acceptance
criteria — then its `## Tasks` section, and the decisions log beside it when it exists
(`<id>-<slug>.DECISIONS.md`, `<id>-<slug>` being the plan filename without `.PLAN.md`): a logged
deviation outranks the plan text it deviates from. Ambiguous or missing plan path → ask. Several
task sections → ask which one this run works from. No task section → stop and point at

# Explain in simple language

Comprehension is the only goal of the wording: the reader understands on the first read. Defines
only the wording of what you say to the user or write in a document a human reads: what to say (the
evidence, the parts the caller requires) stays with whatever asked for the text; this skill decides
how sentences and paragraphs are built and what you add on your own initiative. Most agent text is
already clear: change a sentence only when another wording would raise the chance the reader
understands it, and leave the rest alone.

## The reader

A competent developer, fluent in English but often not native, who did not see what you just saw:
the files, the tool output, your own reasoning. When whatever asked for the text names other
readers (a tester, a product owner), write for the least technical of them: a code name comes with

# Extract PR review rules

Mine the conventions a repository's reviewers enforce in their inline PR review comments into the
project's own governing docs — each rule in the topic doc it belongs to, so it loads only with its
subject, never as one always-read rules file. Re-runnable: each run resumes from the last
checkpoint, fetching only newer comments.

Invocation: `/extract-pr-review-rules <repo-url>`

## 1. Resolve the target

Identify the forge from the repo URL and work through whatever MCP or CLI is connected for it
(GitHub → `gh`). Unrecognized URL, or nothing connected → ask.

# PR review fetcher

**Fetch only** — capture the review feedback left on a pull request; never fix code, reply, or
judge the comments. Output is a self-contained `.PR-REVIEW.md` a fresh session can pick up and act
on (e.g. via `/refine-pr-review`). Someone else's PR to review is not this skill's job: use
`review-code-assistant` or `maintainer-review` when available.

## Source & access

Identify the platform from the PR URL (host shape) and fetch through the matching MCP server or
CLI — e.g. **GitHub MCP / `gh`** for GitHub PRs, **Azure DevOps MCP** for ADO pull requests. Use
whichever equivalent tools are connected; tool name prefixes vary by config. Fetch each stream
through its last page, thread replies included: metadata, review verdicts, inline threads with
their resolution and outdated flags (usually a thread-level API, not the flat comment list),

# Ticket Fetcher

**Fetch only** — no analysis, requirements, or planning. Output is a self-contained `.TICKET.md`.

## Source & access

Identify the tracker from the input (URL host, or id shape) and fetch through the matching MCP
server — e.g. **Azure DevOps MCP** for ADO work items, **Atlassian MCP** for Jira issues, **GitHub
MCP / `gh`** for GitHub issues. Use whichever equivalent tools are connected; tool name prefixes
vary by config. Resolve once any handle the MCP needs (e.g. Atlassian `cloudId`, ADO project) and
reuse it. A bare id that fits several trackers: the one the project's governing docs name, else
the `Source` host all ticket files in the planning directory share, else the only connected
tracker MCP; still open → ask, naming your pick. If no matching MCP is connected: a public ticket
may be scraped from its URL as a fallback (you may still suggest installing the matching MCP when

# Fresh-eyes review

A context that produced a change reads its intent, not its text, so same-context review misses what
a fresh reader would catch. The fix is procedural: a reviewer whose context holds only the
artifacts.

## Workflow

1. **Resolve the inputs.** The changeset: whatever the invocation names — a branch, a commit, a
   diff range, a draft vs its original. Given none, infer it from the session — usually the work
   just finished, committed or not; no VCS required. With no session context to draw on, fall back
   to git: the working tree against HEAD (`git diff HEAD` plus untracked files) and the branch
   against its merge base with the fetched default branch of its tracking remote (`git ls-remote
   --symref <remote> HEAD`). One non-empty → take it; both → offer both in step 2's proposal;

Interview the user relentlessly about every aspect of their plan, design, or idea until you reach
a shared understanding. Walk down each branch of the design tree, resolving dependencies between
decisions one by one.

- One question at a time, each with your recommended answer, worded so that "yes" accepts it, via
  `explain-in-simple-language` when available.
- Facts are yours to find (codebase, docs, tool output): look them up, never ask. Decisions are
  the user's: put each one to them and wait.

Done when no branch is open and nothing is silently assumed. Then print the settled decisions as a
short list (decision, chosen answer, one-line why) the user can paste into the plan, ticket or
doc, and stop: act on it only after the user confirms.

# Handover

Package a finished change so its reviewers never reconstruct intent from the diff. Write for a
reviewer holding the diff and nothing else — no planning docs, no session, no knowledge that
either exists.

## Resolve the task

The input is any partial reference — ticket id, slug, a planning artifact's path — or nothing,
meaning the session's task; in a fresh session, infer it from branch name and recent commits.
Resolve it to the task's **planning home**: its `<id>-<slug>/` directory (no ticket → no id) in
the project's planning directory, or its flat `<id>-<slug>.*` files in a shared family directory.
One clear match → proceed, stating the home and artifacts found. Inferred, or several candidates
(`-vN`, …) → confirm first. An explicit reference matching nothing local → stop and ask; never

# Harden artifact

Make a `.REQUIREMENTS.md` or `.PLAN.md` — the **artifact** — safe to hand to the next phase:
every deviation from its ticket deliberate, explained and correct; every claim true; nothing
blocking the session that picks it up. A fresh-context reviewer hunts, the session challenges
each finding, and only what survives changes the artifact — which **must never end worse than it
started**.

A session that wrote the artifact cannot judge findings on it: say so and propose a fresh session
before continuing.

## Resolve the sources

- **Artifact** — the file the invocation names; ambiguous or neither kind → ask. A plan — the

# Maintainer review

You are the merge gate, not the author's assistant: the question is whether this ships, and the
contributor will argue back. Your own PR belongs to `self-review`. Review in **this** session, not a
subagent. A session opened for the PR is fresh already, and staying in it keeps the diff, the
comments and your findings in hand for the argument that follows. Session already loaded with
unrelated work, say so and offer a fresh one first.

Before the first text addressed to the user, the report included, actually invoke
[explain-in-simple-language](../explain-in-simple-language/SKILL.md) and follow it — reciting its
rules from memory does not count. Not installed: plain words, one idea per sentence, and nothing
named only by a stand-in the reader hasn't seen.

## 1. Start clean and current

# Memory doctor

Agent-memory is an unseen side-channel into every session's context window: facts accumulate there,
often by accident, that the user never reviews and cannot govern. This skill drains it. Technically
**nothing** should live in project memory — durable guidance belongs in homes the user controls
(project docs, project skills/rules, user-level skills/rules), and the rest is garbage. Block by
block, move each entry to its proper home or archive it, until memory trends toward empty and the
user — not the memory store — decides what reaches the context window.

## Golden rule

**The skill guesses and recommends; the user decides.** Every verdict, scope, form, and target is a
*proposal* the user confirms or flips. When unsure, ask. Nothing is moved, deleted, or written
without explicit per-item approval. For every block the user gets the whole fixed menu —

# Prepare prompt

Write for a session holding only this text — no chat history, no memory of what was meant — and
make it as short as that reader allows: nothing it needs is cut for brevity, nothing else stays.
The reader is a fresh interactive session the user pastes it into; a subagent brief only when the
invocation asks for one, under the same rules.

## Input

The user's goal, in a line, plus this session. Draft at once; ask only what neither settles, one
question at a time, with a recommended answer.

## Content

# Refine PR review

The **Refine** phase for review feedback: turn a `.PR-REVIEW.md` (from /fetch-pr-review; ask if
the path is ambiguous) into user-settled per-comment verdicts, drafted replies, and a REQUIREMENTS
file covering the accepted code changes. Triage and replies are settled here; the plan and execute
phases see only code changes.

A PR URL instead: when the harness has subagents and fetch-pr-review is available
(`../fetch-pr-review/SKILL.md` beside this skill), a subagent fetches it first per its
[delegate.md](../fetch-pr-review/delegate.md) and the file it returns is the input. Not available
→ say so and ask for the fetched file; available but no subagents → hand off
`/fetch-pr-review <url>` to a fresh session and stop.

A trailing `head=<sha>` token (fetch-pr-review's refresh hand-off) is the head a refresh just

# Refine ticket

The **Refine** phase of Refine → Plan → Act: turn a raw ticket — or an idea to brainstorm — into a
validated requirements document a fresh session can plan from. Analysis only — it defines **what**
must be true when the work is done, never **how** to build it, and never touches code.

An idea is a ticket that doesn't exist yet: treat the user's words as the ticket text, and grill
to shape the idea itself — goal, in vs out of scope — before closing the branches that block
implementation.

## Input

A `.TICKET.md` path, a ticket URL or bare id, or an idea in words. When the harness has subagents
and fetch-ticket is available (`../fetch-ticket/SKILL.md` beside this skill), a URL or id is

# Review code assistant

Assist a human's local code-review pass: read the diff, understand the intent, surface the real
issues. You suggest candidate comments; the human decides what to post.
Single-pass and lightweight. The edge over a human: the agent has the project's convention docs open
and reads big files fast.

## Resolve what to review

Accept input flexibly; a PR link is optional:

1. **PR URL** — fetch its metadata (source/target branch, title, description), then diff.
2. **One branch** ("review branch xxxx") — diff it against the auto-detected target.
3. **Two branches** ("review xxxx against yyyy") — explicit source and target.

# Review ticket

A pre-pickup triage glance: read a ticket — or a set of tickets forming one feature — usually
before anyone has started it, and decide whether it can be picked up or something must be
clarified first. The output briefs the developer on the feature and lists the questions worth
asking whoever owns the requirements.

## Input

- **Local ticket document(s)**: a single `.TICKET.md`, several, a ticket-set directory, or a
  `.TICKET.md` whose `## Ticket set` section lists siblings.
- **One or more ticket URLs or bare ids/keys**: delegate — even for a single one — to a subagent
  running [fetch-ticket](../fetch-ticket/SKILL.md) per its
  [delegate.md](../fetch-ticket/delegate.md), so the tickets land on disk without the fetch

# Run Nx Checks

Run format, lint, typecheck, test, build. Fix unambiguous failures. Report anything judgment-laden
and every file you changed.

## Arguments

`$ARGUMENTS` — optional, space-separated: `[cpuCount] [projectName] [--remote-cache]`. Number
token → `cpuCount`. Non-number, non-flag token → `projectName`. `--remote-cache` flag → opt back
into the remote cache by dropping the remote-cache-off prefix. Default `cpuCount` = cores - 4
(min 1); count cores with `node -p 'os.cpus().length'`.
Default project scope = affected. Default remote-cache state = off (see Steps).

`$base`, `$cpuCount`, `$projectName` and `$snap` in the commands below are placeholders:

# Self-improve

**Suggest** durable improvements to the skill, doc or check that should have steered the agent,
so the next session gets it right without being told again — and apply them only after the user
approves. The skill proposes; the user stays in control of every change. Three ways in:

- **Manual** — the user invokes `/self-improve` to deliberately improve a skill or doc.
- **Self-triggered** — the agent notices it was corrected on something a skill, doc or check
  governs (or should). Don't silently correct and move on, but don't derail the task either: note
  the lesson, finish what the user asked for, and offer to persist it at the next natural
  breakpoint.
- **Driven by another skill** — a caller (or its launch command, pasted by the user) hands over
  lessons already phrased as durable guidance, sometimes with all or part of a target it settled
  with the user (scope, form, path — possibly a new file or a merge into an existing one). Skip

# Self-review

Make a changeset merge-ready before submission — no regressions, sound code, the project's
conventions respected — and prove it was scrutinized: a fresh-context reviewer hunts for what
would block the merge, the author answers every finding, and a compact report — scannable by a
maintainer in seconds — records the outcome. The report is the review record only; the change's
what/why belongs to the PR description (e.g. via /handover), never here.

Only for a changeset you authored. The fresh-context reviewer exists to escape authoring
blindness, so someone else's PR has nothing to escape and belongs to `maintainer-review`.

## Resolve the changeset

1. Resolve source and target. No input → current branch against the auto-detected target: the

# Split plan into tasks

Append a task breakdown to a plan so the work lands in small increments — one task, then a review,
a correction pass, a commit — instead of one sweep. Authoring only: executing the tasks is a later,
separate session.

Invocation: `/split-plan-tasks <plan-path>`

## Read the plan

Ambiguous or missing path → ask. A plan with numbered steps and an acceptance-criteria checklist
splits best; any plan markdown works — reference tasks to headings when steps aren't numbered, and
drop the AC line when there is no such checklist.

# Use conversational language

Defines the **voice**, how to word text a human should read as if a person typed it, plus the shape
each genre below takes; where a caller's own rules on what to say (evidence bars, scope, structure)
conflict with a genre rule, the caller's win. Apply the baseline always, plus the section matching
the situation. Sections are collections of rules and examples, not silos: whatever fits the text
at hand applies, from any section. Bans ("no …", "never …") are hard rules; everything else is a
tip, and quoted snippets ("wdyt") are examples, never required wording.

## Baseline

Concise, plain language that reads like natural conversation, with no AI tells.

Hard rules:

# Verify understanding

One goal, nothing more, nothing less: verify the engineer is ready to move to the implementation
phase. Exercise their understanding of a feature before they work on it — the pipeline's other
artifacts serve fresh agent sessions; this step serves the human. Active recall: the user produces
the feature in their own words, you only steer and fix. Re-runnable: right after the ticket
review, or days later just before implementation — every run starts fresh from the review file, no
state kept between runs.

## Input

A `.TICKET-REVIEW.md`. Read it and the ticket files and parent it links. A reference that exists
only as a tracker URL (no local file) may be read from the tracker at conversation time. A ticket
with a newer `-vN` fetch beside the one the review read has likely overtaken it: say so, read the

# Brace list

A brace-list section sets a limit of sixty; this line has seventyxxxx.

# Clean

A prose line that stays under the limit, with a working link to [reference.md](reference.md#top).

Ends with a command that stays on one line even past the limit, as the conventions allow: `claude --name create-plan-<slug> "/create-implementation-plan <path>.REQUIREMENTS.md"`

Counted in characters — six em dashes — push this line — past one hundred bytes — while — shortxx.

````
a four-backtick fence holds an inner ``` line and a line far over the limit that the check must still skip
```
````

A source link is never wrapped either: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

# Colon

# Dangling

See [the missing doc](references/missing.md) and [an anchor](#dangling), which is fine.

# Desc dquote

# Desc folded

# Desc literal

# Desc multiline clean

# Desc next line

# Desc plain

# Double backtick

A double-backtick span is a template, not a link: ``[example](missing.md)``.

A command that holds a backtick stays on one line past the limit: ``git log --format='%h `%s`' --no-merges``

# Flag

# Long line

This prose line is padded until it is exactly one character over the fixtures' limit of ninety-nine.

# Md off

A prose line well past the 99 characters the parent .editorconfig sets, which the value off in this folder must lift entirely.

# Mismatch

# No frontmatter

This skill file starts with a heading.