# Setup Vskills > Sets up this skills repo on a new machine — installs the skills with the vskills CLI, configures pstack model routing for any harness, ensures a verification skill, then regenerates the local-only context docs (CONTEXT.md, docs/) that are deliberately not published in the public repo. - Skill: `vraj-ai/setup-vskills` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add vraj-ai/setup-vskills` - Raw SKILL.md: https://api.skillmd.com/api/skills/vraj-ai/setup-vskills/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: vraj-ai (https://skillmd.com/u/vraj-ai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/vraj-ai/setup-vskills --- # Setup vskills This public repo ships the skills and the `vskills` CLI, but **not** the model-context docs. `CONTEXT.md`, `docs/`, `CONTEXT/`, and `CLAUDE.md` are gitignored on purpose: they are local working notes for coding agents, and they go stale against a fork faster than against the source tree. Your job is to install the skills and then rebuild those docs *from this clone*. ## Step 1 — Install the skills ```bash node bin/vskills.js init ``` - Init classifies every skill as install / up-to-date / adopt / update / conflict. Adopts are silent (byte-identical copies become managed). - On conflicts, the CLI prompts. Anything overwritten is backed up to `/.vskills-backup/-` — never deleted. - Re-running init is a no-op; use it freely to verify. Confirm with `node bin/vskills.js list` and run the test suite once: `node --test 'test/*.test.js'` — everything should pass before you write docs. ## Step 1.1 — Research the current harness and install integration templates Ask the user which coding agent harness is in use (e.g. omp, OpenCode, Claude Code, Codex, Cursor, etc.). Always research that harness's agent configuration and integration model first — there is no hardcoded allowlist that skips research. Install the tightest integration for `grill`, `issues`, `ship`/`goals`, and `snapshot`: ```bash # research only — prints the plan, writes nothing node standalone/setup-vskills/scripts/install-harness.mjs # only after the user has said yes to installing it node standalone/setup-vskills/scripts/install-harness.mjs --install ``` Ask before installing, every time. The installers write into the user's own harness config, so a bare run is research: it prints the integration plan and exits without touching anything. `--install` is the user's explicit yes, and the direct installers (`install-omp.mjs`, `install-opencode.mjs`) refuse to run without it. Supported harnesses are data, not prose. This table is the whole allowlist; every destination is overridable by its environment variable, and a harness not listed here is handled by the fallback row rather than by an error. | harness | template source | install destination (override) | routing file for Step 1.3 (override) | direct installer | | --- | --- | --- | --- | --- | | `omp` | `harness/omp/agent/` | user agents dir, `~/.omp/agent/agents/` (`$OMP_AGENTS_DIR`) | harness always-applied rules location | `scripts/install-omp.mjs --install` | | `opencode` | `harness/opencode/` | user config dir, `~/.config/opencode/` (`$OPENCODE_CONFIG_DIR`) | harness always-applied rules location | `scripts/install-opencode.mjs --install` | | `cursor` | — (research) | harness rules dir | `~/.cursor/rules/pstack-models.mdc`, `alwaysApply: true` | — | | *anything else* | — (research) | harness-defined | `docs/agents/model-routing.md` in the project | — | Row detail: - **omp**: copies the 10 canonical Role templates — invocation templates (`grill`, `issues`, `ship`, `goals`, `snapshot`) and worker templates (`researcher`, `builder`, `reviewer`, `adversary`, `small-task`). - **opencode**: copies canonical agent and command files — selectable `goals` and read-only `council` primaries, the contributor, cost-aware Gemini/DeepSeek, council, and adversary subagents, and `/goal`. Goals remains the sole delivery/backlog authority inside a goal run. - **Fallback row**: the installer does not research and does not claim it did. It reports that no bundled installer exists and exits successfully — a missing harness is never an error. You then research how that harness defines agent roles, custom commands, prompt templates, and subagents, and write an integration plan mapping `grill`, `issues`, `ship`/`goals`, and `snapshot` onto it. Never fail with an 'unknown harness' error from an allowlist. When a listed harness is simply not installed on the machine, skip its row and say so; do not create its config tree speculatively. All template installations are atomic and idempotent. Differing existing files are moved to `.vskills-backup/` before replace. It does not modify credentials or core configuration files. ## Step 1.1.1 — Optional: install the PR review bot (Greptile parity) When setting up a consumer project (not this repo), offer the polished PR review bot: ```bash node standalone/pr-review/scripts/copy.mjs [project-root] # or via the setup helper: node standalone/setup-vskills/scripts/copy-pr-review.mjs [project-root] ``` Interactive prompt (ask, don't assume): - "Install PR review bot? [y/N]" — default no. - If yes, ask model wiring: provider `none` (deterministic only) | `openai` | `anthropic` | `compat`, auth `apikey` | `oauth` | `none`, `baseUrl`, `model`, `secretName` (default `OPENROUTER_API_KEY`). Write choice into `.vskills/review.yml` (never store the secret value). Show next step: "Add OPENROUTER_API_KEY as a repo secret, set vars.REVIEW_MODEL / vars.REVIEW_API_BASE, and push a PR to test". - Copy is atomic, backs up existing workflows to `.vskills-backup/`, also installs `.vskills/pr-review/` prompts and parsers, is idempotent, and does not overwrite an existing `.vskills/review.yml`. Templates live in `standalone/pr-review/templates/` and carry `` for idempotent upserts. Verify with `node --test 'test/pr-review-*.test.js' 'test/setup-pr-review.test.js'`. ## Step 1.2 — Bootstrap the project agent architecture Run this from the root of the project being set up: ```bash node "/setup-vskills/scripts/init-context.mjs" ``` `` is wherever `vskills init` placed the skills on this machine (`node bin/vskills.js list` prints it); from a clone of this repo, `standalone/setup-vskills/scripts/init-context.mjs` works directly. Every path the initializer writes is resolved from the invoking repository root, never from the home directory. The initializer creates missing files only: - `AGENTS.md` — the always-loaded project router. - `CONTEXT/architecture.md` — human-owned purpose, locked decisions, invariants, non-goals, accepted boundaries, and ownership. - `CONTEXT/progress.md` — the bounded derived milestone pointer. It also adds only goal runtime paths to `.gitignore`. It never overwrites an existing `AGENTS.md`, architecture, progress, or project decision. It does not create a goal backlog; `/goals` creates `CONTEXT/goals//` when a plan runs. ## Step 1.3 — Configure model routing (pstack) pstack skills (`poteto-mode`, `how`, `why`, `arena`, `swarm`, `architect`, `interrogate`, `reflect`) split work by role across models. Without routing they fall back to inline defaults, which rot as entitlements change. Write the override once per machine; re-running updates it. Confirm the pstack skills resolve first (`poteto-mode`, `how`, `why`, `arena`, `swarm`, `architect`, `interrogate` in the install root). If any is missing, install pstack skills before continuing — routing without runners silently does nothing. 1. Detect available models. Enumerate the model slugs you can pass to a subagent in this session; that is the dependable source. If the harness exposes a models API or CLI, prefer it for completeness. If you cannot detect any, ask the user to paste the slugs they have access to. Never write a real slug you have not confirmed is available. The aliases `inherit-parent` and `auto` are always valid (the role runs on the parent chat model, which is how Auto users stay on Auto). 2. Load current state. If a routing file already exists (step 4), treat its values as the current choices. Otherwise start from the defaults in step 4. 3. Map and confirm. Show every role with its current model, marking any real slug not in the detected set as needing a choice. Offer the detected models plus `inherit-parent`/`auto`. Panel roles (`how critics`, `arena runners`, `architect runners`, `interrogate reviewers`) take lists — one subagent runs per entry, alias entries included, so list length sets fan-out. `arena cross-judge pool` is also a list; Arena picks one value from it whose model family differs from the parent's when possible. `swarm workers` is the default model for every worker unless a race assigns per-arm models. 4. Write the routing file, overwriting it whole so re-runs stay idempotent. Location comes from the Step 1.1 table's routing column, plus the harness research for anything not listed: use its always-applied rules/custom-instructions location, and if it has none, write `docs/agents/model-routing.md` in the project and point the `## Agent skills` block at it, and say so. Never fail with an 'unknown harness' error. Shape (defaults — replace slugs with detected ones): ``` --- description: pstack per-role model choices (overrides skill defaults) alwaysApply: true --- # pstack model configuration. One line per role. Delete a line to fall back to the skill default. # `inherit-parent` or `auto` as a value: the role runs on the parent chat model (omit Task `model`). Alias entries in a panel list still count toward its fan-out. feature, refactoring: grok-4.6-fast-xhigh bug-fix: gpt-5.6-sol-max perf-issue: gpt-5.6-sol-max hillclimb: gpt-5.6-sol-max judgment and prose: claude-fable-5-thinking-max hardest tasks: claude-fable-5-thinking-max how explorer: grok-4.6-fast-xhigh how explainer: claude-fable-5-thinking-max how critics: claude-fable-5-thinking-max, gpt-5.6-sol-max, grok-4.6-fast-xhigh, claude-opus-5-thinking-xhigh why investigators: grok-4.6-fast-xhigh why synthesizer: claude-fable-5-thinking-max reflect tooling: gpt-5.6-sol-max reflect judgment, divergent, synthesizer: claude-fable-5-thinking-max arena runners: claude-fable-5-thinking-max, gpt-5.6-sol-max, grok-4.6-fast-xhigh, claude-opus-5-thinking-xhigh arena cross-judge pool: claude-fable-5-thinking-max, gpt-5.6-sol-max, grok-4.6-fast-xhigh, claude-opus-5-thinking-xhigh swarm workers: grok-4.6-fast-xhigh architect runners: claude-fable-5-thinking-max, gpt-5.6-sol-max, grok-4.6-fast-xhigh, claude-opus-5-thinking-xhigh interrogate reviewers: claude-fable-5-thinking-max, gpt-5.6-sol-max, grok-4.6-fast-xhigh, claude-opus-5-thinking-xhigh ``` 5. Validate. Every real slug written must be in the detected set; `inherit-parent` and `auto` always pass. A routing file pointing at a model the user cannot use breaks every delegation that reads it. Slugs only — never secrets or keys. ## Step 1.4 — Ensure a verification skill A production project needs a way to drive the real app for proof. Check for a project-local `verify-*` skill or an existing harness that drives the app the way a user does. If one exists, record its command — `/issues` will lock it as the ticket acceptance command and `/snapshot` will use it as its code gate. If not, offer once to generate one with `/create-verification-skill` (resolves wherever pstack is installed — workspace, user, or plugin). On yes, invoke it. On no, move on without pushing, and record the gap as a follow-up in the tracker closeout review. ## Step 2 — Regenerate CONTEXT.md Write a fresh `CONTEXT.md` at the repo root by reading the actual code, not by guessing. It must cover, briefly: - What the repo is: a personal skills collection plus the `vskills` installer (`bin/vskills.js`, `src/`). - The skill layout: root skill folders and nested category folders, each skill a directory with a `SKILL.md` whose frontmatter has `name`, `version`, `description`, and optional `dependencies`. - The install model: skills are copied into an install root, agent targets get symlinks, and `.vskills-manifest.json` records `sourcePath`, `contentHash`, `installedAt` per skill. - Drift rules: a copy whose hash doesn't match the manifest is "drifted" and never overwritten without `--force`; forced overwrites of unmanaged content are backed up first. - How to run tests and where they live (`test/*.test.js`, node:test, no external dependencies). Keep it under ~100 lines. If a claim can't be verified in the source, leave it out. ## Step 3 — Regenerate docs/ Recreate `docs/` with: - `docs/invariants.md` — the safety rules the code enforces (atomic replace, backup-before-destroy, symlink-never-clobber, manifest-is-source-of-truth). Derive each one from `src/install.js` and the tests that pin it. - `docs/spec-vskills-cli.md` — command-by-command behavior of `init`, `add`, `list`, `update`, taken from `src/commands/`. - `docs/adr/` — one short ADR per structural decision you can actually observe (e.g. npm registry distribution as `vskills`, CLI architecture). Number them `0001-...`, `0002-...`. ## Step 4 — Verify nothing leaks ```bash git status --short git check-ignore CONTEXT.md docs/invariants.md ``` Both paths must be ignored. If `git status` shows any of the regenerated docs as untracked-and-addable, stop and fix `.gitignore` before committing anything. ## Tracker closeout review After setup verification, if `docs/agents/issue-tracker.md` exists, write one review through that tracker using its commands. Read issues, pull requests, and commits this session produced or touched. Post one comment on the parent spec or open PR (GitHub: `gh issue comment` / `gh pr comment`). Cover what was installed, remaining follow-ups, and any contradiction with `CONTEXT/`. Do not create tickets. Do not rotate `goals:*` labels. If the tracker file is missing, skip and say so. ## Session handoff `setup-vskills` owns installation, the initial project agent architecture, and this repository's local regenerated docs. When setup work must continue in another session, write a full sectioned handoff to `$TMPDIR` after verification, then deliver it with `/push-handoff` if it must reach the remote. ## Durable context contract This repository keeps its own machine-local working notes — `CONTEXT.md`, `docs/`, `CONTEXT/`, and `CLAUDE.md` — local-only under **this repo's own `.gitignore`**. They are a property of the public vskills repository, not a universal rule about consumer projects: the `vskills` CLI never writes them into a consumer repo, there is no `vskills docs-init` command, and the CLI never infers a consumer project's context. Each consumer project owns its own durable context. Consumer projects that adopt `goals`/`council` track only these artifacts as durable context: - Uppercase `AGENTS.md` — the always-loaded router (human-owned). - `CONTEXT/architecture.md` — durable intent, locked decisions, non-goals, and accepted boundaries (human-owned). - Bounded derived `CONTEXT/progress.md` — a small pointer to the current milestone and last verified edit; never a diary, narrative, or resume source of truth (`goals`-owned, event-driven). - `CONTEXT/goals//handoff.md` and `reviews/M.json`, `reviews/T3.json` — the goal resume and review verdicts (`goals`-owned, event-driven). Only the runtime paths beneath a consumer `CONTEXT/` are ignored there: `CONTEXT/goals//backlog.jsonl` (goal resume state owned solely by `goals`), `lock.d/`, `CONTEXT/worktrees//`, `*.log`, `results.json`, and `.digest.json`. The tracked artifacts above are not ignored. Do not apply this repo's own `.gitignore` (which hides the whole `CONTEXT/` of the vskills repository) to a consumer project — a consumer's tracked `CONTEXT/architecture.md`, `CONTEXT/progress.md`, and goal handoff would become invisible. Ownership rules carry across skills: - **One owner per artifact.** No shared writers. - **Event-driven updates only.** Rewrite an artifact when its trigger fires — a locked decision changes, a milestone completes, a T1/T3 verdict lands, or a clean stop checkpoints the handoff. No polling, no autonomous broad rewrites, no speculative refresh of the whole context tree. - **Evidence over prose.** Progress and handoff entries point at tests, builds, review verdicts, or commits — never narrative. - **Bounded context.** `CONTEXT/progress.md` stays a derived pointer; backlogs and handoffs remain the goal resume. - **`goals` is the sole writer of goal state** (backlog, handoff, progress pointer, review verdicts). `council` is read-only and reports documentation impact only; it never edits a context artifact or the backlog. ## Rules - Never commit `CONTEXT.md`, `docs/`, `CONTEXT/`, or `CLAUDE.md` to this repo. They are local-only by design. - Never edit installed copies under the install root — edit the repo source and re-run `node bin/vskills.js init`. - Never edit installed harness agent/role copies directly — edit `harness//` and rerun the installer with the user's approval (`install-harness.mjs --install`, `install-omp.mjs --install`, or `install-opencode.mjs --install`). - Bump the `version:` in a skill's frontmatter whenever you change its content; init uses versions to auto-resolve otherwise-ambiguous updates. - Quit and restart the harness after installing; config-time files are loaded once. - Re-run Step 1.3 whenever model entitlements change; stale slugs break every delegation that reads them. - Keep model routing (slugs, roles) and secrets (keys, tokens) in separate files; routing files never carry secret values.