skills-init 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ezra Apple
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+![skills-init banner](./assets/banner.png)
+
+# skills-init
+
+Drop a small, opinionated agent skill system into any new project.
+
+`skills-init` creates a single source of truth at `.agents/skills`, installs a
+portable baseline of high-leverage skills, and symlinks those skills into the
+tool-specific folders agents already know how to read:
+
+```text
+.claude/skills/<skill>   -> ../../.agents/skills/<skill>
+.cursor/skills/<skill>   -> ../../.agents/skills/<skill>
+.codex/skills/<skill>    -> ../../.agents/skills/<skill>
+.opencode/skills/<skill> -> ../../.agents/skills/<skill>
+```
+
+The idea is simple: your project carries the actual context once, and every
+agent surface sees the same guidance.
+
+## Quick Start
+
+NPM package is coming next. Until then, run it directly from GitHub:
+
+```bash
+npx github:EzraApple/skills-init
+```
+
+After npm publish, the intended command is:
+
+```bash
+npx skills-init
+```
+
+Useful options:
+
+```bash
+skills-init --target .
+skills-init --target . --dry-run
+skills-init --target . --overwrite
+skills-init --target . --no-links
+skills-init --target . --copy-links
+skills-init --list
+```
+
+## What It Installs
+
+Default profile: `core`
+
+```text
+.agents/
+  README.md
+  skills/
+    adversarial-review/
+      SKILL.md
+    simplify/
+      SKILL.md
+    writing-skills/
+      SKILL.md
+  mcps/
+    README.md
+
+.claude/skills/*   -> .agents/skills/*
+.cursor/skills/*   -> .agents/skills/*
+.codex/skills/*    -> .agents/skills/*
+.opencode/skills/* -> .agents/skills/*
+```
+
+`.agents/mcps` is intentionally just a placeholder today. The package is built
+around profiles so MCP setup, tool config, and additional skill packs can be
+added later without changing the core installer model.
+
+## Included Skills
+
+### `adversarial-review`
+
+High-scrutiny independent review for code, PRs, changed files, plans, or
+specific paths.
+
+Includes:
+
+- scope selection for PRs, diffs, files, and local changes;
+- reviewer lane selection based on risk and user intent;
+- correctness, security, architecture, interface, test/ops, and UX lane
+  templates;
+- clustering findings by root cause;
+- validator passes whose job is to kill weak findings;
+- an iterative hardening loop for fix, check, and rerun cycles;
+- final report shape with verdict, action items, findings, and coverage.
+
+Use this when you want a skeptical second opinion, not a polite rubber stamp.
+
+### `writing-skills`
+
+The meta-skill for creating and maintaining useful skills.
+
+Includes:
+
+- how to define a skill's job, trigger phrases, audience, and output;
+- where skills should live: `.agents/skills`, tool links, always-on guidance,
+  scripts, or runtime workspace directories;
+- frontmatter rules for discoverable `name` and `description`;
+- guidance for progressive disclosure with `references/`, `scripts/`,
+  `templates/`, and `assets/`;
+- validation levels from lightweight checks to rigorous pressure scenarios;
+- anti-patterns like narrative skills, workflow-hidden descriptions, and
+  untested routing changes.
+
+Use this when you are turning repeated agent behavior into durable project
+context.
+
+### `simplify`
+
+Deletion-first code simplification for agents that tend to add wrappers,
+helpers, and speculative abstractions.
+
+Includes:
+
+- direct-version-first thinking;
+- single-use helper inlining;
+- guard-clause and flattening guidance;
+- deriving values instead of synchronizing state;
+- collapsing parallel code paths;
+- one-name-per-concept naming discipline;
+- rules for passing objects whole and deleting translation theater;
+- near-miss guidance for cases where added lines are still the simpler choice.
+
+Use this after implementation or during review to ask: what can we delete
+without losing clarity or safety?
+
+## Why This Exists
+
+Agent tools are getting better, but new projects still start cold. The same
+instructions get pasted into prompts, copied between repos, or forgotten until a
+review goes sideways.
+
+`skills-init` makes project context explicit and portable:
+
+- skills live in the repo;
+- tool-specific folders are generated;
+- repeated judgment becomes reusable guidance;
+- future MCP and tool setup has a place to grow.
+
+## Repo Structure
+
+```text
+assets/                 README images and package-visible assets
+bin/                    CLI entrypoint
+profiles/               data-driven install profiles
+scripts/                package validation scripts
+skills/                 source skills copied into target projects
+src/                    installer implementation
+templates/              files written into target projects
+test/                   Node test runner coverage
+```
+
+## Local Development
+
+Run from this checkout:
+
+```bash
+node bin/skills-init.js --target /path/to/project
+```
+
+Run checks:
+
+```bash
+npm run check
+```
+
+This validates skill frontmatter, runs installer tests, and verifies package
+contents with `npm pack --dry-run`.
+
+## Extending
+
+Add a skill:
+
+1. Create `skills/<skill-name>/SKILL.md`.
+2. Add the skill name to `profiles/core.json` or a new profile.
+3. Run `npm run check`.
+
+Add future MCP support:
+
+1. Put MCP templates or descriptors under `templates/` or a future `mcps/`
+   source directory.
+2. Add profile entries describing when they install.
+3. Keep writes idempotent.
+4. Never overwrite user config unless `--overwrite` explicitly allows it.
+
+The installer should stay boring: copy durable source context into `.agents`,
+then generate tool-specific views over that context.
+
+## License
+
+MIT

package/bin/skills-init.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.js";
+
+run(process.argv.slice(2)).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "skills-init",
+  "version": "0.1.0",
+  "description": "Scaffold portable agent skills into a project.",
+  "type": "module",
+  "bin": {
+    "skills-init": "./bin/skills-init.js"
+  },
+  "files": [
+    "assets/",
+    "bin/",
+    "src/",
+    "scripts/",
+    "skills/",
+    "profiles/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EzraApple/skills-init.git"
+  },
+  "bugs": {
+    "url": "https://github.com/EzraApple/skills-init/issues"
+  },
+  "homepage": "https://github.com/EzraApple/skills-init#readme",
+  "scripts": {
+    "check": "npm run lint:skills && npm test && npm run pack:dry-run",
+    "lint:skills": "node scripts/lint-skills.js",
+    "pack:dry-run": "npm pack --dry-run",
+    "test": "node --test"
+  },
+  "keywords": [
+    "agents",
+    "skills",
+    "codex",
+    "claude",
+    "opencode",
+    "developer-tools"
+  ],
+  "author": "Ezra Apple",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/profiles/core.json

@@ -0,0 +1,31 @@
+{
+  "name": "core",
+  "description": "Portable baseline for code review, skill authoring, and simplification.",
+  "skills": [
+    "adversarial-review",
+    "writing-skills",
+    "simplify"
+  ],
+  "toolLinks": [
+    {
+      "tool": "claude",
+      "dir": ".claude/skills",
+      "mode": "always"
+    },
+    {
+      "tool": "cursor",
+      "dir": ".cursor/skills",
+      "mode": "always"
+    },
+    {
+      "tool": "codex",
+      "dir": ".codex/skills",
+      "mode": "always"
+    },
+    {
+      "tool": "opencode",
+      "dir": ".opencode/skills",
+      "mode": "always"
+    }
+  ]
+}

package/scripts/lint-skills.js

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = fileURLToPath(new URL("..", import.meta.url));
+const skillsRoot = join(packageRoot, "skills");
+const descriptionLimit = 1024;
+const namePattern = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const xmlTagPattern = /<[A-Za-z][^>]*>/;
+
+function parseFrontmatter(content, path) {
+  const match = /^---\n([\s\S]*?)\n---\n/.exec(content);
+  if (!match) {
+    throw new Error(`${path} is missing YAML frontmatter`);
+  }
+
+  const frontmatter = {};
+  for (const line of match[1].split("\n")) {
+    const field = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+    if (field) {
+      frontmatter[field[1]] = field[2].replace(/^["']|["']$/g, "");
+    }
+  }
+  return frontmatter;
+}
+
+const errors = [];
+
+for (const entry of readdirSync(skillsRoot, { withFileTypes: true })) {
+  if (!entry.isDirectory()) {
+    continue;
+  }
+
+  const skillName = entry.name;
+  const skillPath = join(skillsRoot, skillName, "SKILL.md");
+  if (!existsSync(skillPath)) {
+    errors.push(`${skillName} is missing SKILL.md`);
+    continue;
+  }
+
+  const content = readFileSync(skillPath, "utf8");
+  const frontmatter = parseFrontmatter(content, skillPath);
+
+  if (!frontmatter.name) {
+    errors.push(`${skillPath} is missing name`);
+  } else if (!namePattern.test(frontmatter.name)) {
+    errors.push(`${skillPath} has invalid name "${frontmatter.name}"`);
+  } else if (frontmatter.name !== skillName) {
+    errors.push(`${skillPath} name does not match directory "${skillName}"`);
+  }
+
+  if (!frontmatter.description) {
+    errors.push(`${skillPath} is missing description`);
+  } else {
+    if (!frontmatter.description.startsWith("Use when")) {
+      errors.push(`${skillPath} description must start with "Use when"`);
+    }
+    if (frontmatter.description.length > descriptionLimit) {
+      errors.push(`${skillPath} description exceeds ${descriptionLimit} characters`);
+    }
+    if (xmlTagPattern.test(frontmatter.description)) {
+      errors.push(`${skillPath} description contains XML-style angle brackets`);
+    }
+  }
+}
+
+if (errors.length > 0) {
+  console.error("Skill lint failed:");
+  for (const error of errors) {
+    console.error(`- ${error}`);
+  }
+  process.exit(1);
+}
+
+console.log("All skills passed lint.");

package/skills/adversarial-review/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: adversarial-review
+description: Use when the user asks for adversarial, independent, skeptical, panel, multi-agent, second-opinion, high-scrutiny, security-minded, or critical review of a PR, branch diff, uncommitted changes, changed files, plan, or specific paths.
+user-invocable: true
+argument-hint: "[PR_OR_DIFF_OR_PATH]"
+---
+
+# Adversarial Review
+
+Use this when ordinary review is not enough. The workflow is independent
+criticism, root-cause clustering, attempted takedown of findings, synthesized
+action items, and reruns after fixes when edits are in scope.
+
+The goal is not to generate more comments. The goal is to find the issues that
+survive skeptical validation.
+
+## Core Rules
+
+- Reviewer and validator passes are readonly. Edit only after synthesis, and
+  only to address validated action items.
+- Do not reuse the implementation chat as evidence. Reviewers get the review
+  packet, not the builder's defense of the code.
+- No issue quota. A clean review is valid if the probes were meaningful.
+- Every finding needs a concrete failure path, target file or symbol, evidence,
+  and suggested fix.
+- Vague concerns are not findings.
+- The user gets a synthesized action list, not raw reviewer transcripts.
+- Default to the hardening loop unless the user asks for report-only review.
+
+If your runtime supports subagents, use fresh readonly subagents for reviewer and
+validator passes. If it does not, run the same lanes sequentially in fresh notes:
+reset assumptions between lanes, do not edit during lane work, and do not let one
+lane's findings bias another until clustering.
+
+## Scope Selection
+
+Pick the narrowest concrete scope before launching reviewer lanes:
+
+1. If the user gives a PR URL or number, review that PR with the local GitHub
+   tooling available in the environment.
+2. If the user names files or directories, review those paths plus directly
+   relevant callers.
+3. If the user gives a base or revision range, review that diff.
+4. If the current branch has a resolvable PR, review that PR.
+5. Otherwise review the branch diff from the default branch using the merge
+   base.
+6. Otherwise review staged, unstaged, and untracked changes.
+
+If the resolved diff is empty, stop and say there is nothing to review.
+
+## Dimension Selection
+
+Choose lanes from the user's requested dimensions, changed surfaces, and risk
+profile. Do not run the same fixed panel every time.
+
+1. Extract explicit dimensions and exclusions from the prompt.
+2. Infer additional dimensions only when materially relevant.
+3. Skip unrelated default lanes.
+4. Use one lane for a narrow requested dimension, two or three for moderate
+   risk, and four or more only for broad PRs or explicit high-scrutiny requests.
+5. Ask for clarification only when two plausible lane sets would produce
+   materially different reviews.
+
+Record selected lanes and skipped obvious lanes in the final coverage section.
+
+## Review Packet
+
+Create one lean packet and pass the same packet to every reviewer lane.
+
+Include:
+
+- user request, requested dimensions, exclusions, and selected scope;
+- PR title/body or local change summary when available;
+- issue/ticket links when available;
+- diff command used and changed file list;
+- full diff or focused patch for the selected scope;
+- on reruns, the disposition ledger from prior rounds.
+
+Reference project guidance by path instead of inlining it. Reviewers may read
+`AGENTS.md`, local skill docs, package docs, and full files needed to prove or
+kill a finding.
+
+Do not include implementation plans, parent-agent notes, or private reasoning
+unless the user explicitly asks to review against them.
+
+## Lane Templates
+
+Use these as starting points. Add or remove lanes based on the task.
+
+| Lane | Focus question | Use for |
+| --- | --- | --- |
+| Correctness Critic | How does this break in production? | Runtime behavior, data flow, state, cache, idempotency, regression risk. |
+| Security Critic | What can a hostile user, integration, or prompt do with this? | Auth, authorization, injection, secret exposure, unsafe logs, trust boundaries. |
+| Architecture Minimalist | Is this the smallest maintainable shape? | Abstractions, duplicated pathways, wrong-layer fixes, interface bloat. |
+| Interface Critic | Does the public boundary make the caller's job clear? | APIs, schemas, hooks, component props, CLI flags, cross-package contracts. |
+| Test And Ops Critic | What will make this hard to verify, deploy, roll back, or debug? | Missing failure-path tests, migrations, observability, version skew, flaky assumptions. |
+| Product Or UX Critic | Does behavior match the expected user outcome? | Visible behavior, copy, loading/error states, accessibility, workflow fit. |
+
+Add domain lanes when warranted: migration safety, performance, prompt injection,
+data correctness, accessibility, payments, privacy, or package publishing.
+
+## Reviewer Output Contract
+
+Each reviewer returns Markdown with this shape:
+
+```markdown
+## <Reviewer Lane>
+
+Verdict: BLOCK | CONCERNS | CLEAN
+
+### Findings
+
+1. ID: <stable lane-local id>
+   Severity: CRITICAL | WARNING | NOTE
+   Confidence: HIGH | MEDIUM | LOW
+   Target: `<path>` / `<symbol or line if known>`
+   Problem: <one sentence>
+   Evidence: <specific code path and why existing guards do not cover it>
+   Failure path: <input/event/state that triggers the issue>
+   Suggested fix: <concrete remediation>
+
+### Probes That Survived
+
+- <meaningful checks that did not produce findings>
+```
+
+Severity rubric:
+
+- `CRITICAL`: merge-blocking correctness, data loss, security, or broken
+  existing contract.
+- `WARNING`: should be fixed, but not merge-blocking.
+- `NOTE`: informational; never becomes an action item on its own.
+
+If there are no findings, the reviewer still lists probes that survived.
+
+## Clustering And Validation
+
+Cluster first, then validate clusters. Never run one validator per raw finding.
+
+1. Cluster candidate findings by root cause, not by file or reviewer.
+2. Drop clusters made only of NOTE-severity or evidence-free findings.
+3. Run one fresh readonly validator pass per remaining cluster.
+4. The validator's job is to kill the finding, not defend it.
+
+Validator output:
+
+```markdown
+## Validation
+
+1. Cluster: <finding ids>
+   Disposition: action-item | omit | needs-human
+   Evidence: <code evidence for or against the finding>
+```
+
+Use `omit` for disputed, unproven, or confirmed-but-trivial findings. Keep a
+disputed finding only when the disagreement itself changes what the user should
+decide.
+
+## Synthesis
+
+The parent agent synthesizes. Do not paste raw reviewer reports.
+
+1. Convert `action-item` clusters into action items.
+2. Route `needs-human` clusters to a human-decision bucket.
+3. Rank by merge-blocking impact, then user risk, then maintenance cost.
+
+Verdict mapping describes the final diff after any fixes:
+
+- `BLOCK`: at least one validated CRITICAL finding remains unfixed.
+- `CONCERNS`: validated non-blocking action items or human decisions remain.
+- `CLEAN`: no validated findings remain.
+
+## Iterative Hardening Loop
+
+Use this loop by default when edits are in scope.
+
+1. Run reviewer lanes, clustering, validation, and synthesis.
+2. If validated action items remain and the local worktree is editable, fix them.
+3. Run targeted checks for touched surfaces.
+4. Refresh the packet and append a disposition ledger:
+   - fixed, with fix location;
+   - omitted, with killing evidence;
+   - needs-human, with the decision needed.
+5. Rerun only lanes that produced a validated finding or whose surfaces the fix
+   touched.
+6. Stop at a terminal state.
+
+Terminal states:
+
+- `clean`: fresh review leaves no validated actionable findings.
+- `human-decision`: remaining findings require product, architecture, rollout, or
+  risk-tolerance decisions.
+- `broad-refactor-required`: credible fix exceeds the requested scope; name the
+  subsystem boundary and why a local fix would be misleading.
+- `report-only-requested`: user explicitly requested readonly review.
+- `cycle-cap-reached`: three full cycles ran and validated findings remain.
+
+## Final Report
+
+Use this shape:
+
+```markdown
+## Independent Critical Review
+
+Verdict: BLOCK | CONCERNS | CLEAN
+
+### Action Items
+
+**Before merge**
+- <owner action> in `<path>` / `<symbol>` because <validated risk>.
+
+**Verification**
+- <test, check, or manual verification needed>.
+
+**Needs human decision**
+- <decision and why code alone cannot answer it>.
+
+### Findings
+
+1. **CRITICAL | WARNING | NOTE** - `<path>` / `<symbol>`
+   <problem and failure path>
+   Evidence: <why this survived validation>
+   Suggested fix: <concrete remediation>
+
+### Coverage
+
+- Scope reviewed: <diff/path/PR>
+- Lanes run: <lanes>
+- Lanes intentionally skipped: <lanes and why>
+- Validation: <commands or checks>
+```
+
+If no findings survive, say so directly and include the probes that mattered.