@chankov/agent-skills 0.2.0 → 0.3.0

package/.versions/0.3.0/skills/using-agent-skills/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: using-agent-skills
+description: Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.
+---
+
+# Using Agent Skills
+
+## Overview
+
+Agent Skills is a collection of engineering workflow skills organized by development phase. Each skill encodes a specific process that senior engineers follow. This meta-skill helps you discover and apply the right skill for your current task.
+
+## Skill Discovery
+
+When a task arrives, identify the development phase and apply the corresponding skill:
+
+```
+Task arrives
+    │
+    ├── Vague idea/need refinement? ──→ idea-refine
+    ├── New project/feature/change? ──→ spec-driven-development
+    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
+    ├── Implementing code? ────────────→ incremental-implementation
+    │   ├── UI work? ─────────────────→ frontend-ui-engineering
+    │   ├── API work? ────────────────→ api-and-interface-design
+    │   ├── Need better context? ─────→ context-engineering
+    │   └── Need doc-verified code? ───→ source-driven-development
+    ├── Writing/running tests? ────────→ test-driven-development
+    │   └── Browser-based? ───────────→ browser-testing-with-devtools
+    ├── Something broke? ──────────────→ debugging-and-error-recovery
+    ├── Reviewing code? ───────────────→ code-review-and-quality
+    │   ├── Security concerns? ───────→ security-and-hardening
+    │   └── Performance concerns? ────→ performance-optimization
+    ├── Committing/branching? ─────────→ git-workflow-and-versioning
+    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
+    ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
+    ├── Authoring a new skill/persona? ─→ designing-agents
+    └── Deploying/launching? ─────────→ shipping-and-launch
+```
+
+## Core Operating Behaviors
+
+These behaviors apply at all times, across all skills. They are non-negotiable.
+
+### 1. Surface Assumptions
+
+Before implementing anything non-trivial, explicitly state your assumptions:
+
+```
+ASSUMPTIONS I'M MAKING:
+1. [assumption about requirements]
+2. [assumption about architecture]
+3. [assumption about scope]
+→ Correct me now or I'll proceed with these.
+```
+
+Don't silently fill in ambiguous requirements. The most common failure mode is making wrong assumptions and running with them unchecked. Surface uncertainty early — it's cheaper than rework.
+
+### 2. Manage Confusion Actively
+
+When you encounter inconsistencies, conflicting requirements, or unclear specifications:
+
+1. **STOP.** Do not proceed with a guess.
+2. Name the specific confusion.
+3. Present the tradeoff or ask the clarifying question.
+4. Wait for resolution before continuing.
+
+**Bad:** Silently picking one interpretation and hoping it's right.
+**Good:** "I see X in the spec but Y in the existing code. Which takes precedence?"
+
+### 3. Push Back When Warranted
+
+You are not a yes-machine. When an approach has clear problems:
+
+- Point out the issue directly
+- Explain the concrete downside (quantify when possible — "this adds ~200ms latency" not "this might be slower")
+- Propose an alternative
+- Accept the human's decision if they override with full information
+
+Sycophancy is a failure mode. "Of course!" followed by implementing a bad idea helps no one. Honest technical disagreement is more valuable than false agreement.
+
+### 4. Enforce Simplicity
+
+Your natural tendency is to overcomplicate. Actively resist it.
+
+Before finishing any implementation, ask:
+- Can this be done in fewer lines?
+- Are these abstractions earning their complexity?
+- Would a staff engineer look at this and say "why didn't you just..."?
+
+If you build 1000 lines and 100 would suffice, you have failed. Prefer the boring, obvious solution. Cleverness is expensive.
+
+### 5. Maintain Scope Discipline
+
+Touch only what you're asked to touch.
+
+Do NOT:
+- Remove comments you don't understand
+- "Clean up" code orthogonal to the task
+- Refactor adjacent systems as a side effect
+- Delete code that seems unused without explicit approval
+- Add features not in the spec because they "seem useful"
+
+Your job is surgical precision, not unsolicited renovation.
+
+### 6. Verify, Don't Assume
+
+Every skill includes a verification step. A task is not complete until verification passes. "Seems right" is never sufficient — there must be evidence (passing tests, build output, runtime data).
+
+## Failure Modes to Avoid
+
+These are the subtle errors that look like productivity but create problems:
+
+1. Making wrong assumptions without checking
+2. Not managing your own confusion — plowing ahead when lost
+3. Not surfacing inconsistencies you notice
+4. Not presenting tradeoffs on non-obvious decisions
+5. Being sycophantic ("Of course!") to approaches with clear problems
+6. Overcomplicating code and APIs
+7. Modifying code or comments orthogonal to the task
+8. Removing things you don't fully understand
+9. Building without a spec because "it's obvious"
+10. Skipping verification because "it looks right"
+
+## Skill Rules
+
+1. **Check for an applicable skill before starting work.** Skills encode processes that prevent common mistakes.
+
+2. **Skills are workflows, not suggestions.** Follow the steps in order. Don't skip verification steps.
+
+3. **Multiple skills can apply.** A feature implementation might involve `idea-refine` → `spec-driven-development` → `planning-and-task-breakdown` → `incremental-implementation` → `test-driven-development` → `code-review-and-quality` → `shipping-and-launch` in sequence.
+
+4. **When in doubt, start with a spec.** If the task is non-trivial and there's no spec, begin with `spec-driven-development`.
+
+## Lifecycle Sequence
+
+For a complete feature, the typical skill sequence is:
+
+```
+1. idea-refine                 → Refine vague ideas
+2. spec-driven-development     → Define what we're building
+3. planning-and-task-breakdown → Break into verifiable chunks
+4. context-engineering         → Load the right context
+5. source-driven-development   → Verify against official docs
+6. incremental-implementation  → Build slice by slice
+7. test-driven-development     → Prove each slice works
+8. code-review-and-quality     → Review before merge
+9. git-workflow-and-versioning → Clean commit history
+10. documentation-and-adrs     → Document decisions
+11. shipping-and-launch        → Deploy safely
+```
+
+Not every task needs every skill. A bug fix might only need: `debugging-and-error-recovery` → `test-driven-development` → `code-review-and-quality`.
+
+## Quick Reference
+
+| Phase | Skill | One-Line Summary |
+|-------|-------|-----------------|
+| Define | idea-refine | Refine ideas through structured divergent and convergent thinking |
+| Define | spec-driven-development | Requirements and acceptance criteria before code |
+| Plan | planning-and-task-breakdown | Decompose into small, verifiable tasks |
+| Build | incremental-implementation | Thin vertical slices, test each before expanding |
+| Build | source-driven-development | Verify against official docs before implementing |
+| Build | context-engineering | Right context at the right time |
+| Build | frontend-ui-engineering | Production-quality UI with accessibility |
+| Build | api-and-interface-design | Stable interfaces with clear contracts |
+| Verify | test-driven-development | Failing test first, then make it pass |
+| Verify | browser-testing-with-devtools | Chrome DevTools MCP for runtime verification |
+| Verify | debugging-and-error-recovery | Reproduce → localize → fix → guard |
+| Review | code-review-and-quality | Five-axis review with quality gates |
+| Review | security-and-hardening | OWASP prevention, input validation, least privilege |
+| Review | performance-optimization | Measure first, optimize only what matters |
+| Ship | git-workflow-and-versioning | Atomic commits, clean history |
+| Ship | ci-cd-and-automation | Automated quality gates on every change |
+| Ship | documentation-and-adrs | Document the why, not just the what |
+| Ship | shipping-and-launch | Pre-launch checklist, monitoring, rollback plan |
+| Author | designing-agents | Author a persona, workflow skill, or pi harness |

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # agent-skills changelog
 
+## 0.3.0
+
+### Minor Changes
+
+- **Rename installer slash commands** + **auto-remove them after setup**.
+
+  The bootstrap commands are now namespaced so they don't collide with anything
+  in your workspace, and they get cleaned up automatically once `/setup-agent-skills`
+  finishes — leaving your agent's slash-command list as clean as before you ran
+  `init`.
+
+  ### What changed
+
+  - `/setup` → `/setup-agent-skills`
+  - `/doctor` → `/doctor-agent-skills`
+  - `/as-setup` → `/as-setup-agent-skills` (OpenCode)
+  - `/as-doctor` → `/as-doctor-agent-skills` (OpenCode)
+  - `guided-workspace-setup` SKILL.md still installs to `.{claude,pi,opencode}/skills/`
+    during bootstrap and is removed alongside the slash commands
+
+  ### Cleanup behaviour (default)
+
+  After `/setup-agent-skills` completes its install pass, the skill deletes the
+  bootstrap files (slash commands + skill body) from the workspace. The Step 9
+  confirmation states this explicitly and accepts `keep` as the opt-out. When
+  opted out, `keep-installer: true` is recorded in
+  `.ai/agent-skills-setup.md#workspace-summary`.
+
+  Re-run `npx @chankov/agent-skills init` whenever you need
+  `/setup-agent-skills` back — it's a one-line re-bootstrap.
+
+  ### Migration for users on 0.2.x
+
+  `npx @chankov/agent-skills@latest init` automatically detects and removes the
+  pre-rename `setup.md`/`doctor.md`/`as-*.md` files from the workspace before
+  writing the new names. No manual cleanup required.
+
+  ### New CLI subcommand
+
+  - `npx @chankov/agent-skills cleanup-installer --agent <agent>` — removes the
+    bootstrap files standalone. The skill calls this at end of apply; you can
+    also invoke it by hand. Honors `--dry-run`.
+
+### Patch Changes
+
+- Fix: `npx @chankov/agent-skills init` now bootstraps the installer artifacts
+  (`/setup`, `/doctor`, and the `guided-workspace-setup` skill) into the
+  workspace before printing the hand-off.
+
+  In 0.1.0 / 0.2.0, `init` printed _"Open your coding agent and run /setup"_ —
+  but `/setup` is itself a slash-command file that needed to exist in
+  `.claude/commands/`, `.pi/prompts/`, or `.opencode/commands/`. Fresh
+  workspaces didn't have it, so the agent had no idea what `/setup` was and
+  the hand-off silently no-op'd.
+
+  What `init` now writes (per chosen agent, to the workspace):
+
+  | Agent         | Files                                                                                                                                                                                                                                      |
+  | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+  | `claude-code` | `.claude/commands/setup.md`, `.claude/commands/doctor.md`, `.claude/skills/guided-workspace-setup/SKILL.md`                                                                                                                                |
+  | `pi`          | `.pi/prompts/setup.md`, `.pi/prompts/doctor.md`, `.pi/skills/guided-workspace-setup/SKILL.md`                                                                                                                                              |
+  | `opencode`    | `.opencode/commands/as-setup.md`, `.opencode/commands/as-doctor.md`, `.opencode/skills/guided-workspace-setup/SKILL.md` (+ printed note about adding the global AGENTS.md reference; project-local skill discovery in OpenCode is limited) |
+
+  The rest of the catalogue (the user-facing skills, personas, references,
+  hooks, pi extensions) is unchanged — those are still chosen interactively
+  inside `/setup`, as designed. The CLI only drops the installer plumbing.
+
+  Bootstrap files are always refreshed on re-run (they are scaffolding, not
+  user data). `--method symlink` against an unstable source path
+  (`~/.npm/_npx/...`) prints a warning recommending `--method copy` or a
+  global install.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -39,11 +39,11 @@ Skills also activate automatically based on what you're doing — designing an A
 # In the workspace you want to configure:
 npx @chankov/agent-skills init
 # Then open your coding agent in this directory and run:
-#   /setup
+#   /setup-agent-skills
 ```
 
 That's it. `npx` fetches the package, the CLI detects your coding agent
-(Claude Code, OpenCode, or pi), and `/setup` runs the full guided install —
+(Claude Code, OpenCode, or pi), and `/setup-agent-skills` runs the full guided install —
 analysing the workspace, showing grouped menus, and confirming everything
 before writing a single file.
 
@@ -51,9 +51,9 @@ Three CLI commands:
 
 | Command | What it does |
 |---|---|
-| `npx @chankov/agent-skills init` | Materialize the package + hand off to `/setup` |
+| `npx @chankov/agent-skills init` | Materialize the package + hand off to `/setup-agent-skills` |
 | `npx @chankov/agent-skills doctor` | Scan for broken symlinks and stale persona refs |
-| `npx @chankov/agent-skills update` | Surface the version delta + hand off to `/setup` for the per-artifact diff |
+| `npx @chankov/agent-skills update` | Surface the version delta + hand off to `/setup-agent-skills` for the per-artifact diff |
 
 Versioned with [semver](https://semver.org); changelog in
 [CHANGELOG.md](CHANGELOG.md); full docs in [docs/npm-install.md](docs/npm-install.md).
@@ -83,7 +83,7 @@ git clone https://github.com/chankov/agent-skills.git
 cd agent-skills
 # In Claude Code:
 claude --plugin-dir .
-# Then run /setup in your target workspace and pick "symlink" in Step 8.
+# Then run /setup-agent-skills in your target workspace and pick "symlink" in Step 8.
 ```
 
 Updates flow through `git pull`. Symlinks need Developer Mode on Windows.

package/bin/cli.js

@@ -2,9 +2,9 @@
 // agent-skills — thin dispatcher into the LLM-driven guided setup.
 //
 // Three commands:
-//   init     materialize the package, detect the coding agent, hand off to /setup
+//   init     materialize the package, detect the coding agent, hand off to /setup-agent-skills
 //   doctor   deterministic preflight scan (broken symlinks, stale persona refs)
-//   update   refresh the package, then hand off to /setup for the version-diff
+//   update   refresh the package, then hand off to /setup-agent-skills for the version-diff
 //
 // The CLI itself never decides which skills to install or what to overwrite —
 // that is the job of the guided-workspace-setup skill, run by the user's
@@ -22,6 +22,7 @@ import { stdin, stdout, exit } from "node:process";
 import { runDoctor } from "./lib/doctor.js";
 import { detectAgent, agentLabel, AGENTS } from "./lib/detect-agent.js";
 import { checkAndNotify } from "./lib/update-notifier.js";
+import { bootstrap, cleanupInstaller } from "./lib/bootstrap.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = resolve(__dirname, "..");
@@ -80,11 +81,12 @@ if (sub !== "update" && sub !== "check-update") {
 }
 
 switch (sub) {
-  case "init":          await cmdInit();        break;
-  case "doctor":        await cmdDoctor();      break;
-  case "update":        await cmdUpdate();      break;
-  case "check-update":  await cmdCheckUpdate(); break;
-  default:              fail(`unknown command: ${sub}\n\nRun "agent-skills --help" for usage.`);
+  case "init":              await cmdInit();             break;
+  case "doctor":            await cmdDoctor();           break;
+  case "update":            await cmdUpdate();           break;
+  case "check-update":      await cmdCheckUpdate();      break;
+  case "cleanup-installer": await cmdCleanupInstaller(); break;
+  default:                  fail(`unknown command: ${sub}\n\nRun "agent-skills --help" for usage.`);
 }
 
 // ── commands ──────────────────────────────────────────────────────────────
@@ -100,15 +102,41 @@ async function cmdInit() {
   const agent = await chooseAgent(opts.agent);
   console.log(`Coding agent: ${agentLabel(agent)}`);
 
-  // The CLI doesn't write any skill / persona / command files itself —
-  // that is the job of `guided-workspace-setup` running inside the agent.
-  // What it CAN do is record the chosen agent + method as a hint the skill
-  // will pick up, and print the exact next-step command.
   const method = opts.method ?? "copy";
   if (!["copy", "symlink"].includes(method)) {
     fail(`--method must be "copy" or "symlink" (got "${method}")`);
   }
 
+  // Bootstrap the installer artifacts (setup + doctor + the skill they invoke).
+  // Without this, the agent has no /setup-agent-skills command to hand off to — the
+  // /setup-agent-skills command is itself one of the files this writes. The rest of the
+  // catalogue (skills, personas, etc.) is the job of /setup-agent-skills running inside
+  // the agent; we only drop the plumbing it needs to exist.
+  printSection("Bootstrap installer");
+  const { written, skipped, removed, warnings } = bootstrap({
+    agent,
+    sourceRoot: pkgRoot,
+    workspace,
+    method,
+    dryRun: opts["dry-run"],
+  });
+
+  for (const w of warnings) console.log(`  ⚠ ${w}`);
+  for (const p of removed) {
+    const tag = opts["dry-run"] ? "would remove (legacy)" : "removed legacy";
+    console.log(`  − ${tag}: ${relative(workspace, p)}`);
+  }
+  for (const f of written) {
+    const tag = opts["dry-run"] ? "would write" : (method === "symlink" ? "linked" : "wrote");
+    console.log(`  ✓ ${tag}: ${relative(workspace, f.dest)}`);
+  }
+  for (const f of skipped) {
+    console.log(`  ✗ skipped: ${relative(workspace, f.dest)} — ${f.error}`);
+  }
+  if (written.length === 0 && skipped.length === 0 && removed.length === 0) {
+    console.log("  (nothing to do — sources missing from package)");
+  }
+
   printSection("Next step");
   printHandoff({ agent, method, workspace, source: pkgRoot, version: pkg.version });
 
@@ -159,7 +187,7 @@ async function cmdDoctor() {
     `\n✓ Doctor finished — repaired ${repaired}, deleted ${deleted}, skipped ${skipped}.`,
   );
   console.log(
-    "Re-run /setup inside your coding agent if you also want to add or remove artifacts.",
+    "Re-run /setup-agent-skills inside your coding agent if you also want to add or remove artifacts.",
   );
 }
 
@@ -172,7 +200,7 @@ async function cmdUpdate() {
 
   // npm itself does the package upgrade. The CLI's job here is to read the
   // workspace's install record, surface the version delta, and tell the user
-  // to run /setup so the skill can drive the diff-aware refresh.
+  // to run /setup-agent-skills so the skill can drive the diff-aware refresh.
   const recordPath = join(workspace, ".ai", "agent-skills-setup.md");
   if (!existsSync(recordPath)) {
     console.log("This workspace has no .ai/agent-skills-setup.md install record.");
@@ -194,12 +222,40 @@ async function cmdUpdate() {
   console.log(`Recorded in workspace: v${recorded ?? "(pre-versioning)"}`);
   console.log(`Installed package:     v${current}`);
   console.log();
-  console.log("Run /setup inside your coding agent — the guided-workspace-setup");
+  console.log("Run /setup-agent-skills inside your coding agent — the guided-workspace-setup");
   console.log("skill will detect the version delta, show the CHANGELOG between");
   console.log("the two versions, and offer a per-artifact three-way diff before");
   console.log("touching any file.");
 }
 
+async function cmdCleanupInstaller() {
+  // Removes the bootstrap artifacts (setup-agent-skills, doctor-agent-skills,
+  // guided-workspace-setup skill body) from the workspace. Invoked by the
+  // skill itself at the end of Step 10 — keeps the workspace's slash-command
+  // list clean. Re-running `init` brings them back.
+  await mustBeDirectory(workspace, "workspace");
+
+  const agent = opts.agent ?? detectAgent({ workspace, env: process.env });
+  if (!agent || !AGENTS.includes(agent)) {
+    fail(`cleanup-installer needs --agent (one of: ${AGENTS.join(", ")})`);
+  }
+
+  const { removed, kept, warnings } = cleanupInstaller({
+    agent,
+    workspace,
+    dryRun: opts["dry-run"],
+  });
+
+  for (const w of warnings) console.log(`  ⚠ ${w}`);
+  for (const p of removed) {
+    const tag = opts["dry-run"] ? "would remove" : "removed";
+    console.log(`  − ${tag}: ${relative(workspace, p)}`);
+  }
+  if (removed.length === 0 && warnings.length === 0) {
+    console.log("Nothing to clean up — installer files already absent.");
+  }
+}
+
 async function cmdCheckUpdate() {
   // Entry point for hook scripts and pi extensions. Blocks on a single
   // registry fetch (short timeout); emits a one-line banner to stdout if an
@@ -244,6 +300,8 @@ async function chooseAgent(supplied) {
 
 function printHandoff({ agent, method, workspace, source, version }) {
   const rel = relative(process.cwd(), workspace) || ".";
+  const setupCmd =
+    agent === "opencode" ? "/as-setup-agent-skills" : "/setup-agent-skills";
   const lines = [
     `agent-skills v${version} is ready.`,
     "",
@@ -252,21 +310,37 @@ function printHandoff({ agent, method, workspace, source, version }) {
     `Install method:  ${method}`,
     `Source root:     ${source}`,
     "",
-    "Open your coding agent in this directory and run:",
+    `Open ${agentLaunchHint(agent)} in this directory and run:`,
     "",
-    `  /setup`,
+    `  ${setupCmd}`,
     "",
     "The guided-workspace-setup skill will:",
     "  • analyse the workspace",
     "  • show grouped install menus with recommendations",
     "  • offer project overrides",
     "  • confirm everything before writing a single file",
+    "  • remove the installer commands from your workspace at the end so",
+    "    they don't pollute your agent's command list (reply 'keep' in",
+    "    Step 9 if you'd rather leave them in)",
     "",
-    "Re-run `npx agent-skills doctor` any time to scan for broken symlinks.",
   ];
+  if (agent === "opencode") {
+    lines.push(
+      "OpenCode note: project-local skill discovery is limited. If",
+      "/as-setup-agent-skills does not load the skill, follow",
+      "docs/opencode-setup.md to link it into ~/.config/opencode/skills/",
+      "and add a reference in AGENTS.md.",
+      "",
+    );
+  }
+  lines.push("Re-run `npx @chankov/agent-skills init` later to re-bootstrap (commands are removed by default once setup completes).");
   for (const line of lines) console.log(line);
 }
 
+function agentLaunchHint(agent) {
+  return { "claude-code": "Claude Code (`claude`)", "opencode": "OpenCode (`opencode`)", "pi": "pi (`pi`)" }[agent] || agent;
+}
+
 function tryLaunch(agent, cwd) {
   const cmd = { "claude-code": "claude", "opencode": "opencode", "pi": "pi" }[agent];
   if (!cmd) return;
@@ -274,7 +348,7 @@ function tryLaunch(agent, cwd) {
   const r = spawnSync(cmd, [], { cwd, stdio: "inherit" });
   if (r.error) {
     console.log(`(could not launch ${cmd}: ${r.error.message})`);
-    console.log(`Open ${cmd} manually and run /setup.`);
+    console.log(`Open ${cmd} manually and run /setup-agent-skills.`);
   }
 }
 
@@ -339,7 +413,7 @@ function printHelp(sub) {
   if (sub === "init") {
     console.log(`agent-skills init [options]
 
-  Materialize the package and hand off to the LLM-driven /setup skill.
+  Materialize the package and hand off to the LLM-driven /setup-agent-skills skill.
 
 Options:
   --agent <claude-code|opencode|pi>   Skip the agent auto-detection
@@ -367,7 +441,7 @@ Options:
     console.log(`agent-skills update [options]
 
   Read the workspace's install record and surface the version delta. The
-  actual diff-aware refresh runs inside your coding agent via /setup.
+  actual diff-aware refresh runs inside your coding agent via /setup-agent-skills.
 
 Options:
   --workspace <path>   Target workspace (default: cwd)
@@ -385,10 +459,12 @@ Usage:
   npx agent-skills <command> [options]
 
 Commands:
-  init           Materialize the package + hand off to /setup in your agent
-  doctor         Scan for broken symlinks and stale persona references
-  update         Surface the version delta + hand off to /setup for the refresh
-  check-update   One-line registry check (used by session hooks; safe to script)
+  init                Bootstrap installer files + hand off to /setup-agent-skills-agent-skills
+  doctor              Scan for broken symlinks and stale persona references
+  update              Surface the version delta + hand off to /setup-agent-skills-agent-skills
+  check-update        One-line registry check (used by session hooks; safe to script)
+  cleanup-installer   Remove the installer slash commands from a workspace (used
+                      by the skill at end of setup; safe to run by hand)
 
 Options:
   -v, --version    Print the package version