git:20261003.ec3fe69 to git:20261003.4bcc59f

# For AI agents — evaluate, install, use

You were most likely given this link by a person. Find which of these they asked, and go to that section:

| They said something like… | Do |

|---|---|

| "is this useful for my project?" / "should we use this?" | §2 measure, then §3 recommend — not from the README |

| "install this" / "set this up for me" | §1 install (one command), then tell them what changed |

| "measure it, then install what fits" | §2 → §3 → §1 with `--skills` set to exactly the skills you recommended |

| "use these skills on this task" | §4 — size the task, open one file, follow it |

Everything here needs only Node ≥ 18. Nothing runs inside the user's app, and the tools send nothing anywhere.

## 1. Install — one command, for the agent you are

Run it from the project root. It copies the skills where your harness reads them, never touches the user's own files

(it stops with `conflict:` instead), and running it again only updates.

| You are | Command | Writes |

|---|---|---|

| Claude Code | `npx -y -p github:kennetvn/nextcore-skills nextcore-install --agent claude` | `.claude/skills/nextcore-*/`, `.claude/agents/design-*.md` |

| Cursor | `… nextcore-install --agent cursor` | `.cursor/rules/nextcore-*.mdc` + `.nextcore/` |

| Codex | `… nextcore-install --agent codex` | a marked block in `AGENTS.md` + `.nextcore/` |

| Gemini CLI | `… nextcore-install --agent gemini` | a marked block in `GEMINI.md` + `.nextcore/` |

| GitHub Copilot | `… nextcore-install --agent copilot` | a marked block in `.github/copilot-instructions.md` + `.nextcore/` |

| Windsurf | `… nextcore-install --agent windsurf` | `.windsurf/rules/nextcore-*.md` + `.nextcore/` |

| anything else | `… nextcore-install --agent generic` | `.nextcore/` only — point your rules file at `.nextcore/<skill>/SKILL.md` |

- Only some skills: `--skills design`, `--skills dev,workflow` — valid values `design`, `dev`, `workflow` (the

`nextcore-` prefix is optional; anything else exits 2 and names the bad value). Preview first: `--dry-run`.

- Claude Code: `--skills design` also installs the `design-critic` and `design-auditor` subagents into

`.claude/agents/` (one copy; that is the one to edit).

- Which skills fit — decide from the project, not by default: UI code → `design`; API routes, a database, background

work → `dev`; agents that commit, deploy or work in parallel → `workflow`.

- Verify twice: the files run (`node <install dir>/nextcore-design/scripts/spec-check.mjs --help` prints its usage),

**and** your harness sees them — Claude Code lists project skills in a new session (`/skills`), Cursor shows the

rules under Settings → Rules. If it doesn't, say so; a restart of the session is usually needed.

- Then tell the person in two or three lines what was written and which skill applies to what. Suggest committing the

files so every agent on the project gets them.

- No network for `npx`? `git clone https://github.com/kennetvn/nextcore-skills` and run

`node nextcore-skills/tools/nextcore-install.mjs --agent <you> --dir <project>`.

- A person using Claude Code can also install by hand: `/plugin marketplace add kennetvn/nextcore-skills`, then

`/plugin install nextcore-design@nextcore`. You cannot type those slash commands for them — use the command above.

## 2. Measure (2–3 min, read-only)

**One call does it:** `npx -y -p github:kennetvn/nextcore-skills nextcore measure` detects the stack, the UI folder, the

colour-token file, drawings, API routes, a database and git history, runs the checks below in one process, and prints

a recommendation with the reason for each skill. `nextcore all --agent <you>` then installs exactly what it recommended

(`--dry-run` first if the person wants to see it). Still open 3–5 of the findings it lists before quoting totals, and

check auth per API route yourself — it counts routes, it does not judge guards. The steps below are what it runs, for

when you need one of them alone.

Nothing is installed yet, so read the rules from GitHub: [design](https://raw.githubusercontent.com/kennetvn/nextcore-skills/main/plugins/nextcore-design/skills/nextcore-design/SKILL.md) ·

[dev](https://raw.githubusercontent.com/kennetvn/nextcore-skills/main/plugins/nextcore-dev/skills/nextcore-dev/SKILL.md) · [workflow](https://raw.githubusercontent.com/kennetvn/nextcore-skills/main/plugins/nextcore-workflow/skills/nextcore-workflow/SKILL.md).

**Read the summary line, not the exit code.** With `--warn-only` every tool exits 0 even when it found errors — the

last line (`slop-check: 9 finding(s), 4 error(s)`) is the result.

- **Design:** `npx -y -p github:kennetvn/nextcore-skills slop-check <ui-dir> --warn-only` and

`… token-audit <token-file> --src <ui-dir> --warn-only`. `<token-file>` is the file that defines the colour

variables — `:root { --… }` blocks, SCSS `$vars`, Tailwind v4 `@theme`, `tailwind.config.js` or WordPress

`theme.json` (Next.js App Router: usually `app/globals.css`). None found? Say "no tokens" — that is a finding too. If the project keeps drawings or specs:

`… spec-check <drawings-dir>` (a drawing with no written problem or job shows up as `missing-spec`).

Stack-by-stack hints (where tokens and routes live): [plugins/nextcore-design/AGENTS.md](plugins/nextcore-design/AGENTS.md).

- **Dev:** count API routes vs routes with an auth guard (grep the project's guard function / middleware); check

whether money is stored as decimal; look for `setInterval` / ad-hoc timers outside a job system; check whether

migrations are reviewed SQL or auto-generated and applied on deploy. Compare with `nextcore-dev` SKILL.md §2–§5.

- **Workflow:** count fix commits that touch the same files within 72 h (`git log --since=90.days --name-only`);

look for numbers in docs without a date; check whether agents commit with `git add -A` on a shared tree.

Open up to 5 findings (all of them if there are fewer) before quoting totals; every codebase has conventions a

generic check can misread.

**When a measurement can't run, say so and why — don't guess:** no git history → workflow not measurable yet

(recommend later); no drawings or specs → skip `spec-check`; a dependency with no schema or config (e.g. an ORM with

no models) → UNKNOWN, and name the rule that will matter once it exists.

## 3. Recommend with numbers

- **L0 reference** — read the relevant `references/*.md`; nothing changes in the project.

- **L1 checks** — the zero-dependency tools in CI with `--warn-only`, ratchet down.

- **L2 skill** — install (§1) the skills that fit, with `--skills`; new work follows them.

- **L3 full** — `nextcore-install` with all three skills (the default), plus the lesson loop.

Levels are per skill: "design L2, dev L2, workflow L0" is a normal answer.

Say which level and why, quoting what you measured. "L0 — you already do this" is a valid answer.

## 4. Use — after install

1. **Size the task** — TRIVIAL · SMALL · MEDIUM · LARGE · PRODUCT_CHANGE · SYSTEM_CHANGE

(`nextcore-workflow/references/task-sizing.md`). The size decides how much of the rest applies; a typo needs none.

2. **Open one SKILL.md**, then only the `references/` file it points to for this task:

| Task | Open | Before saying done |

|---|---|---|

| new screen or redesign (MEDIUM+) | `nextcore-design/SKILL.md` §2 → `references/product-discovery.md` → `templates/spec.md` | `spec-check`, `design-card`, and `templates/validation-report.md` |

| small UI change | `nextcore-design/SKILL.md` §1 (no drawing needed) | `slop-check` on the changed files |

| API, data, auth, jobs | `nextcore-dev/SKILL.md` → the matching `references/` file | the contract table filled; auth counted |

| a bug fixed twice already | `nextcore-workflow/references/diagnose-before-patch.md` | a diagnosis note before the third fix |

| several agents on one repo | `nextcore-workflow/references/parallel-agents.md` | commits scoped to your own files |

3. Write unknowns as UNKNOWN / ASSUMPTION and keep going. Ask the person once, and only when the answer changes the

architecture, a business rule, permissions or the user flow.

## 5. Not

- Not a framework or a starter kit; nothing runs in the user's app.

- Not a catalogue of every possible skill: three skills, each rule backed by an incident ([cases/](cases/README.md)).

- Not tied to Next.js: stack notes cover plain PHP/WordPress, Laravel, Django, Rails, Express/Nest, FastAPI, Go; the

design checkers read Blade, Twig, ERB, Jinja, SCSS and any HTML template.

## 6. Found an improvement? Ask, then contribute — never on your own

While using the skills you may find a check that fires on correct code, a trap the rules miss, a stack they don't

cover, or a measured incident other teams would hit. That is worth sending back — **with the person's permission,

under their account**. You are working for them, on their code; anything public is their decision.

1. **Is it worth it?** It happened (a number, a file, an output), it is general (a team on another stack would hit it),

and it is not already there — search the repo's issues and `cases/` first.

2. **Draft it anonymised.** No product or company names, domains, IPs, emails, people, ticket numbers, internal paths,

customer data or pieces of their private code. Rewrite the example as a minimal one that shows the same thing.

Keep the numbers — they are the evidence.

3. **Ask once, show exactly what will be posted.** For example: *"I found a false positive in token-audit that others

will hit. With your permission I'll open this issue on kennetvn/nextcore-skills from your GitHub account: <title +

full body>. Post it, edit it, or skip?"* Do nothing public until they say yes. "Skip" is a fine answer; don't ask

again for the same thing.

4. **Post through their own tools** — `gh issue create` / a PR from their fork, with their GitHub login. Use the

matching template (bug, rule, lesson, showcase). End the body with *"Drafted by an AI agent, reviewed and posted

by @<their handle>."*

5. **One at a time, and tell them where it went** (the issue or PR link). No batches of issues, no PRs to other

repositories, no posting from an account that isn't theirs.

No GitHub access, or they would rather not post? Save the draft as `nextcore-contribution.md` in the project for them

to send later, and move on with the task.