dzhng/skills instruction manual

1. Purpose, scope, and Claude Code classification

`dzhng/skills` is an MIT-licensed collection of small, composable Agent Skills for building and reviewing software. The repository describes a “software factory” approach: map uncertainty, turn decisions into a specification, implement independently verifiable slices, and repeatedly review the result. The same skill folders are intended for Claude Code, Codex, opencode, Cursor, duet, and other compatible harnesses.

**Claude Code classification:** this repository is a **Claude extension based primarily on context injection**, with additional **orchestration**, **skill-authoring**, and optional **tool-surface** behavior. Each `SKILL.md` injects task-specific operating guidance. Skills such as `review`, `implement-spec`, and the documented full loop coordinate other skills. `write-skills` and `eval-skills` teach creation and testing of skills. `codex`, `claude`, `preview-shots`, and renderer workflows can invoke local CLIs or platform tools when their stated conditions are met.

The `.claude-plugin/plugin.json` file identifies a Claude Code plugin named `skills`, but its explicit manifest contains only 12 skill paths: `write-skills`, `eval-skills`, `refactor-clean`, `write-spec`, `implement-spec`, `close-spec`, `codex`, `write-docs`, `renderer`, `compare-screenshots`, `screenshot-critique`, and `preview-shots`. The README catalogs 22 skills. Therefore, do not assume the plugin manifest exposes every cataloged skill; use the repository-wide installer’s selection mode or copy a specific folder when you need a skill not listed in that manifest.

2. Installation, selection, and invocation

Install the repository’s skills through the documented skills installer:

npx skills add dzhng/skills

To choose individual skills rather than adding the collection without selection, append the documented `--list` option:

npx skills add dzhng/skills --list

The other documented installation method is manual: copy any complete `skills/<category>/<name>/` folder into the skill directory used by your harness. For project-local Claude Code use, the README gives `.claude/skills/` as the example destination. Keep the folder intact so its `SKILL.md` and any supporting material remain together.

Invoke an installed skill by name in the harness. The README presents slash-style invocations such as `/explore-unknowns`, `/write-spec`, and `/review`. Most skills may also be selected by the model when their frontmatter description matches the task. `eli5` is explicitly different: `disable-model-invocation: true` makes it user-invoked only.

No minimum Claude Code version, update procedure, uninstall command, dependency bootstrap, or compatibility test matrix is documented in the supplied files. Some skills require more than Markdown: `codex` expects an authenticated Codex CLI on `PATH`; `claude` expects an authenticated Claude Code CLI; `preview-shots` requires macOS; and renderer work requires the project’s own WebGPU/browser verification environment. Install or use those external facilities only under the conditions documented by their respective skills.

3. The end-to-end feature loop

For a large feature, begin with **`explore-unknowns`**. It maps the task’s “fog of war” quadrant by quadrant: established facts, questions, reactable artifacts such as mocks or decision tables, and blind spots. Its purpose is to turn vague ideas into decisions the user can inspect.

Next run **`write-spec`**. It converts the map into independently buildable and verifiable slices, with API seams and checkpoints that a person can review. The README says genuinely new decisions should return to the user rather than being silently invented.

Then use **`implement-spec`** to build the existing specification one reviewable pass at a time and delegate independent slices in parallel. The documented loop invocation is:

/goal /implement-spec specs/<feature>

`/goal` is described as placing the harness in loop mode. Optional natural-language framing may identify a branch or request Codex as implementer. **`implement-spec-with-codex`** is the dedicated variant in which Codex writes code while the parent agent orchestrates, integrates, and reviews each pass.

During implementation, the plan is treated as living: discoveries can trigger re-slicing instead of forcing a stale plan. Visual work calls the visual-review skills, each slice receives a review, and choices made where the spec was silent are collected in `specs/<feature>/choices.md`, least-confident first.

After shipping, run **`close-spec`**. It verifies the feature, moves the spec under `specs/done/` with `git mv`, replaces build-order prose with rationale and invariants, preserves visual provenance, points to real code and tests, removes obsolete slices, repairs links, and requires unbiased claim-by-claim auditing.

4. Engineering quality, explanation, and page governance

The engineering catalog provides focused checks that can stand alone:

• **`refactor-clean`** moves ownership to one clean concept instead of adding compatibility sediment beside an old design.
• **`write-tests`** adds tests as tracer bullets, pinning real behavior rather than implementation details, configuration literals, or lucky samples.
• **`audit-performance`** finds hot paths that repeat or amplify without progress, ranks actual failure risk, and prefers the smallest bounded fix that preserves recovery behavior.
• **`write-docs`** treats documentation as a glossary of principles, reasons, and pointers. It removes copied inventories, current constants, changelog narrative, and other facts better obtained from code. Each fact gets one home, and the root documentation links downward to specialized documents.
• **`code-review`** audits a diff for stale names, dead references, needless complexity, and comments that merely narrate. It ends with a clean/not-clean verdict.
• **`audit-choices`** reviews the implementer’s decision ledger rather than rereading the whole diff. It is described as a pure, non-blocking audit of architecture and decisions made for the user.
• **`eli5`** explains a spec or change for a technical reader with no prior context. It walks one concrete scenario, separates current behavior from proposals, uses decision-level pseudocode when ordering matters, inventories every durable schema change, and outputs `Problem`, `Solution`, then `Schema changes`.
• **`review`** is the closeout orchestrator: run `refactor-clean`, then `code-review`, then `write-docs`. Structural findings loop back to the first pass. Completion requires one resolved verdict across all three.
• **`marketing-pages`** governs writing, updating, and auditing pages by class. Campaign landing pages remain noindexed and unlinked with one call to action; other pages must earn sitemap inclusion, a crawl-rail link, and canonical copy ownership.

For an unplanned change that grew unexpectedly, the README’s documented sequence is `/review` followed by `/audit-choices`.

5. Independent-agent workflows: Codex and Claude

**`codex`** uses the local Codex CLI as a second agent, never as authority. Proactive review is appropriate for a substantive diff; implementation delegation is allowed only when the user explicitly names Codex. Supported review scopes are:

codex review --uncommitted
codex review --base <branch>
codex review --commit <sha>

Confirm every finding against the code and report accepted, fixed, and dismissed findings. For explicitly delegated pure code work, the skill documents:

codex exec --sandbox workspace-write "<task>"

Browser, server, or full-suite work may use `codex exec --dangerously-bypass-approvals-and-sandbox "<task>"` only in a dedicated worktree, with a fully self-authored prompt and mandatory diff review. Launch from the repository root, do not edit the same tree concurrently, and inspect the complete result. If Codex is absent, ask before installation and use OpenAI’s current first-party instructions; authentication remains interactive.

**`claude`** invokes Claude Code non-interactively as a separate worker. Its documented default is:

claude -p --model opus --effort high "<prompt>"

Use compact prompts with one task, an explicit result shape, grounding, verification, and scope constraints. Read-oriented consultation can use:

claude -p --model opus --effort high --tools "Read,Grep,Glob,Bash" --permission-mode dontAsk "<prompt>"

Claude may edit only after explicit delegation. Broad permission bypass is restricted to a dedicated worktree and requires later diff review. For either agent, preserve a clean baseline, avoid simultaneous edits, verify claims and tests yourself, and never treat the worker’s “done” message as completion.

6. Visual review and screenshot handling

The visual skills replace acceptance “on vibes” with explicit inspection.

**`compare-screenshots`** determines which image is less wrong relative to a target established for the task. Its reusable diff script supplies telemetry for locating divergence rather than proving an exact baseline match. It can also inspect one capture for flat, empty, or badly framed content.

**`screenshot-critique`** sends visual work to an unprimed subagent for an independent second look. The README makes this mandatory before declaring a reported visual defect fixed. “Unprimed” means the reviewer should not be told the expected answer.

**`preview-shots`** is a macOS-only presentation helper. Curate the smallest useful set, put the most important image first, and open all images in one Preview window:

open -a Preview <path> <path> ...

Before replacing a set, close existing Preview windows:

osascript -e 'tell application "Preview" to close every window'

If an unattended workflow proceeds without waiting for the user, close Preview afterward:

osascript -e 'quit app "Preview"'

Use saved PNG or GIF artifacts rather than live Chrome unless the user explicitly requests a browser or the defect occurs only headfully. Caption each opened shot so the user knows what each file represents.

7. Creating and evaluating skills

**`write-skills`** defines a skill as compressed operational memory, not general documentation. Create lowercase hyphen-case names and matching folders. Put invocation conditions in the frontmatter `description`, because that is what is visible before loading. Use short imperative procedures, explicit decision points, checkable completion criteria, and durable failure symptoms. Remove generic advice, stale history, implementation indexes, duplicated rules, and examples that prescribe an old fix.

Keep the main `SKILL.md` compact through progressive disclosure: long or variant-specific information belongs in linked `references/`; fragile repeatable operations belong in `scripts/`; reusable output material belongs in `assets/`. Choose default model invocation only when the agent or another skill must trigger it automatically. Set `disable-model-invocation: true` for user-only skills. Split a skill only when separate invocation or staged sequencing justifies the added context cost. The documented starter shape is frontmatter, a title and job statement, `Workflow`, and `Rules`.

**`eval-skills`** tests a skill like a function. It requires a real target `SKILL.md`, at least one concrete golden input, and a defensible success bar with failure smells. Each case runs in a fresh isolated agent that sees only the input and target skill—not the bar or expected result. A separate fresh judge receives the artifact, the bar, and the skill’s first principles. Important or borderline cases run two or three times and report pass rate.

Failures are classified as skill defects or bad cases. Valid defects drive narrowly scoped edits through `write-skills`; then every case is rerun to catch regressions. Always check the live checkout after isolated runs and clean leaked files. The final report gives per-case pass rates, cited gaps, mapped defects, edits, and before/after results.

8. WebGPU renderer development and verification

**`renderer`** guides three.js/TSL and raw WGSL WebGPU changes involving resources, passes, shaders, depth, composition, capabilities, performance, or browser-visible output. First inspect the project’s current device shell, pass graph, layouts, shader contracts, and verification routes. Define buffer, texture, bind-group, ownership, access, update, and lifetime contracts before adding pipelines. Use compute for parallel preparation or simulation and render passes for rasterized output; separate background, depth-tested world, translucent/effect, and UI phases when visibility rules differ.

Keep one canonical owner for projection, depth convention, environment, shared layouts, phase names, and semantic roles. Treat depth as an access contract such as read, read-write, or write. Do not mix translucent blending into depth-writing opaque geometry, draw terrain cues as world geometry rather than HUD, or rely on painter order for occlusion. WGSL layouts must respect alignment; mutable staged values use `var`, not immutable `let`.

For three.js WebGPU, verify reversed-depth sorting empirically, explicitly reapply instancing when a custom `positionNode` is used, transform `normalNode` deliberately because it is view-space, avoid TSL’s `time` node in favor of injectable time and seeded randomness, use a finite far plane, and snapshot renderer statistics at render time.

Browser success alone is insufficient. Open the actual PNG, capture validation warnings, reject blank or misframed canvases, and pair submitted-instance statistics with pixel/content probes. Performance numbers require proof of the actual GPU; SwiftShader is valid for correctness but not timing. GPU suites run with one worker. Use hardware measurements, bounded readbacks, useful pass statistics, and project-specific tests. Apply `compare-screenshots` for telemetry and `screenshot-critique` when a visual result is subtle or disputed.

9. Operational boundaries and source-supported expectations

The README’s unattended-run image and duration claims are repository-reported examples, not guarantees. Actual duration, autonomy, correctness, and cost depend on the harness, project, tests, external CLIs, browser/GPU environment, and human decisions. Every piece is expected to prove itself through architecture, code, and visual review, but those checks still require trustworthy project evidence.

The supplied files do not document telemetry, a security audit, host-version compatibility, automatic updates, or every cataloged skill’s full body. Several catalog entries—such as `explore-unknowns`, `write-spec`, `implement-spec`, `refactor-clean`, `write-tests`, `audit-performance`, `code-review`, `audit-choices`, `compare-screenshots`, `screenshot-critique`, and `marketing-pages`—are supported here only by their first-party README descriptions, so this manual does not add undocumented flags or procedures for them.

Review external-agent output, generated diffs, test results, visual artifacts, and destructive moves before acceptance. Respect explicit invocation boundaries: user-only skills require the user, and Codex or Claude implementation requires a direct request. The repository is public, unarchived, and MIT-licensed according to the supplied GitHub metadata.