@givolt/i3-composer-agent 2.0.0 → 2.1.1

package/docs/codebuddy-setup.md

@@ -16,9 +16,11 @@ for project or global scope before installing. Project scope writes these paths:
 - `.codebuddy/commands/` — all 9 existing lifecycle workflows.
 - `.codebuddy/agents/` — all 4 persona definitions.
 
-Global scope uses the same layout under `~/.codebuddy/`. Existing assets require
-confirmed replacement and are preserved in backup directories. Settings are
-not replaced. Reload the CodeBuddy window or start a new chat, then inspect
+Global scope uses the same layout under `~/.codebuddy/`. Unchanged manifest-owned
+assets from the same version are reused. Modified files, unowned collisions and
+upgrades require confirmed replacement. Previous files are removed after
+successful installation; a failure restores them. Settings are preserved.
+Reload the CodeBuddy window or start a new chat, then inspect
 the Skills list and type `/` to inspect the command menu.
 
 ```text
@@ -38,9 +40,20 @@ For multiple tools or a noninteractive installation:
 
 ```bash
 npx @givolt/i3-composer-agent --agents codebuddy,codex --scope project --yes
+npx @givolt/i3-composer-agent --agents codebuddy,workbuddy --scope global --yes
 npx @givolt/i3-composer-agent --codebuddy --scope global --yes
 ```
 
+CodeBuddy and WorkBuddy share `.codebuddy/` project files. Installing either
+client first and adding the other at the same package version reuses unmodified
+owned files and merges the client IDs. Global WorkBuddy files use
+`~/.workbuddy/`, independently of `~/.codebuddy/`. See [WorkBuddy setup](workbuddy-setup.md).
+
+For WorkBuddy desktop, global installation is recommended because WorkBuddy
+5.7.7 does not list the shared `.codebuddy/skills/` project Skills. You can keep
+CodeBuddy at project scope and install WorkBuddy separately with
+`--workbuddy --scope global`.
+
 CodeBuddy documents [IDE skills](https://www.codebuddy.cn/docs/ide/Features/Skills)
 and [IDE custom commands](https://www.codebuddy.cn/docs/ide/User-guide/Slash-Commands).
 The directory layout follows its [configuration directory reference](https://www.codebuddy.cn/docs/cli/codebuddy-dir).

package/docs/cursor-setup.md

@@ -49,7 +49,7 @@ your-project/
 ```
 
 **Source of truth for the agent:** `.cursor/skills/`.  
-Treat `i3-composer-agent/skills/` (or a cloned [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)) as **upstream** — sync into `.cursor/skills/`, do not edit only upstream and expect Cursor to see it.
+Treat `i3-composer-agent/skills/` as **upstream** — sync into `.cursor/skills/`, do not edit only upstream and expect Cursor to see it.
 
 ---
 
@@ -222,4 +222,4 @@ Files under `i3-composer-agent/agents/` (e.g. code reviewer persona) are **not**
 
 - [getting-started.md](getting-started.md)
 - [../README.md](../README.md) — Cursor quick blurb
-- Upstream: [github.com/addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)
+- Package: [@givolt/i3-composer-agent](https://www.npmjs.com/package/@givolt/i3-composer-agent)

package/docs/getting-started.md

@@ -165,8 +165,6 @@ selected `skills/<name>/` directory is copied. The skill still works, but paths
 to supplementary checklists in the repo-level `references/` directory are
 unavailable. Use a whole-repo integration, clone the repository, or copy the
 needed checklist into a `references/` directory inside the installed skill.
-This portability gap is tracked in
-[upstream agent-skills #361](https://github.com/addyosmani/agent-skills/issues/361).
 
 ## Spec and task artifacts
 

package/docs/opencode-setup.md

@@ -42,7 +42,7 @@ mkdir -p .opencode/skills
 cp -r .claude/skills/<skill-name> .opencode/skills/
 ```
 
-> **Note:** Per-skill installs copy only the skill directory itself. If a skill references shared files under `references/`, copy those into the installed skill directory or install the whole pack. See [upstream agent-skills #361](https://github.com/addyosmani/agent-skills/issues/361) for background.
+> **Note:** Per-skill installs copy only the skill directory itself. If a skill references shared files under `references/`, copy those into the installed skill directory or install the whole pack.
 
 ### Option 2: Prepare the plugin bundle
 
@@ -93,7 +93,7 @@ Copy the directories under `skills/` (for example `skills/i3-spec-driven-develop
 
 ## Project `AGENTS.md`
 
-Create an `AGENTS.md` in **your own project** root. This is the system prompt that tells OpenCode when and how to invoke the installed skills. Unlike the repo-scoped `AGENTS.md` in `addyosmani/agent-skills`, this file belongs to your project and should be adapted to your stack.
+Create an `AGENTS.md` in **your own project** root. This is the system prompt that tells OpenCode when and how to invoke the installed skills. Unlike the repo-scoped `AGENTS.md` in `i3-composer-agent`, this file belongs to your project and should be adapted to your stack.
 
 Below is a template you can paste into your project's `AGENTS.md`:
 
@@ -133,7 +133,7 @@ For every request:
 
 Save this as `AGENTS.md` in your project root. OpenCode will load it automatically.
 
-> **Note:** The root `AGENTS.md` inside the `addyosmani/agent-skills` repository is intended for contributors working on this repository and should not be copied into other projects. See [CONTRIBUTING.md](../CONTRIBUTING.md#repo-scoped-files).
+> **Note:** The root `AGENTS.md` inside the `i3-composer-agent` repository is intended for contributors working on this repository and should not be copied into other projects. See [CONTRIBUTING.md](../CONTRIBUTING.md#repo-scoped-files).
 
 ## How It Works
 
@@ -256,4 +256,4 @@ These rules are enforced by your project's `AGENTS.md`, not by the copy of the s
 3. OpenCode discovers the skills and your `AGENTS.md` guides the agent to invoke them.
 4. Optionally add `.opencode/commands/*.md` for explicit slash commands.
 
-This keeps the reusable assets (skills) separate from the repository-specific configuration (the `addyosmani/agent-skills` root `AGENTS.md`).
+This keeps the reusable assets (skills) separate from the repository-specific configuration (the `i3-composer-agent` root `AGENTS.md`).

package/docs/workbuddy-setup.md

@@ -0,0 +1,106 @@
+# Using i3 Composer Agent with WorkBuddy
+
+## Recommended global installation
+
+Install WorkBuddy assets in its user configuration directory:
+
+```bash
+npx @givolt/i3-composer-agent --workbuddy --scope global
+```
+
+The terminal wizard preselects WorkBuddy and confirms the global installation.
+For installation without prompts:
+
+```bash
+npx @givolt/i3-composer-agent --workbuddy --scope global --yes
+npx @givolt/i3-composer-agent --agents codebuddy,workbuddy --scope global --yes
+```
+
+Global WorkBuddy installation includes:
+
+- `~/.workbuddy/skills/`: all 25 Skills with their existing `i3-` IDs.
+- `~/.workbuddy/commands/`: all 9 short `/i3-*` workflows.
+- `~/.workbuddy/agents/`: all 4 Agents (role definitions).
+- `~/.workbuddy/references/`: shared references and the standard MIT license.
+- `~/.workbuddy/docs/agents.md`: Agent role documentation.
+- `~/.workbuddy/.i3-composer-agent.json`: managed asset and client records.
+
+If you use a separate WorkBuddy profile, set `WORKBUDDY_CONFIG_DIR` to its
+configuration directory when installing. The installer does not borrow
+`CODEBUDDY_CONFIG_DIR` for WorkBuddy. Open the corresponding profile in the host.
+
+## Discovery and invocation
+
+Open your project in WorkBuddy and start a new chat after installation. Type `/`
+to inspect Commands, and open the Skills list. Global installation resolves the
+desktop Skills list issue observed in WorkBuddy 5.7.7 and confirmed by user testing.
+Examples:
+
+```text
+/i3-spec
+/i3-plan
+/i3-build
+/i3-build auto
+/i3-review
+/i3-ship
+```
+
+Commands invoke the installed Skill IDs without a plugin namespace. Native
+Buddy commands refer to `CODEBUDDY.md` and the installed persona directories.
+Shared project commands refer to the current host's user-level persona directory
+so they work for either client. `/i3-ship` uses native subagents when available
+and reads the installed persona prompts sequentially otherwise. Skill content,
+`$ARGUMENTS`, workflow approval gates, and relative reference links are retained.
+
+The [task-bar command documentation](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Task-Bar)
+describes command discovery, and the [CLI command documentation](https://www.codebuddy.cn/docs/cli/slash-commands)
+describes Markdown commands and `$ARGUMENTS`.
+
+## Project installation and mixed clients
+
+| Selected clients | Project files | Global files |
+| --- | --- | --- |
+| CodeBuddy | `.codebuddy/` | `~/.codebuddy/` |
+| WorkBuddy | `.codebuddy/` (desktop Skills list limitation) | `~/.workbuddy/` (recommended) |
+| CodeBuddy and WorkBuddy | One shared `.codebuddy/` installation | One installation in each client's directory |
+
+Project installation remains available for shared `.codebuddy/` assets. However,
+WorkBuddy 5.7.7 scans `.workbuddy/skills/` for its desktop Skills list, so Skills
+installed at `.codebuddy/skills/` do not appear there even though Commands are
+discoverable. The [WorkBuddy project documentation](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Project)
+describes `.codebuddy/` paths; that documentation does not establish desktop
+Skills list compatibility for this host version.
+
+For CodeBuddy at project scope and WorkBuddy at global scope, run:
+
+```bash
+npx @givolt/i3-composer-agent --codebuddy --scope project --yes
+npx @givolt/i3-composer-agent --workbuddy --scope global --yes
+```
+
+Existing `.workbuddy/` project settings are preserved. A shared project
+installation may add `.codebuddy/`, so both directories can exist in a workspace.
+
+## Adding a second client or upgrading
+
+When both clients use project scope, either can be installed first. Installing
+the other at the same package version and scope reuses unmodified manifest-owned
+files and merges the client IDs. It does not create a second project copy. Global
+installations remain independent. Missing files are restored;
+unrelated settings and custom command filenames are preserved.
+
+Review an upgrade or conflict before replacing files:
+
+```bash
+npx @givolt/i3-composer-agent --workbuddy --scope global --dry-run
+npx @givolt/i3-composer-agent --workbuddy --scope global --yes --force
+```
+
+Modified assets, unowned filename collisions and different versions require
+confirmation or `--force`. Successful replacements remove old files and managed
+historical backups. If installation fails, the previous files are restored.
+
+Native installation provides Commands, Skills and Agent role definitions. It does not register
+a WorkBuddy plugin or enable plugin hooks; `--prepare --workbuddy` is unsupported.
+File installation and command discovery are separate from model execution and
+workflow acceptance in the host.

package/package.json

@@ -30,14 +30,24 @@
     ".codex-plugin/",
     ".agents/plugins/",
     "hooks/",
-    "docs/",
-    "scripts/",
-    "evals/",
-    "rebrand/",
-    "tests/",
+    "docs/adoption-guide.md",
+    "docs/agents.md",
+    "docs/antigravity-setup.md",
+    "docs/codebuddy-setup.md",
+    "docs/codex-setup.md",
+    "docs/commandcode-setup.md",
+    "docs/copilot-cli-setup.md",
+    "docs/copilot-setup.md",
+    "docs/cursor-setup.md",
+    "docs/gemini-cli-setup.md",
+    "docs/getting-started.md",
+    "docs/opencode-setup.md",
+    "docs/other-hosts.md",
+    "docs/windsurf-setup.md",
+    "docs/workbuddy-setup.md",
     "plugin.json",
-    "NOTICE.md",
-    "CHANGELOG.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "rebrand": "node rebrand/apply.cjs --apply",
@@ -50,6 +60,7 @@
     "i3-composer",
     "agent-skills",
     "codebuddy",
+    "workbuddy",
     "codex",
     "claude-code"
   ],
@@ -66,23 +77,28 @@
       ".codex-plugin",
       ".agents/plugins",
       "hooks",
-      "docs",
-      "scripts",
-      "evals",
-      "rebrand",
-      "tests",
+      "docs/adoption-guide.md",
+      "docs/agents.md",
+      "docs/antigravity-setup.md",
+      "docs/codebuddy-setup.md",
+      "docs/codex-setup.md",
+      "docs/commandcode-setup.md",
+      "docs/copilot-cli-setup.md",
+      "docs/copilot-setup.md",
+      "docs/cursor-setup.md",
+      "docs/gemini-cli-setup.md",
+      "docs/getting-started.md",
+      "docs/opencode-setup.md",
+      "docs/other-hosts.md",
+      "docs/windsurf-setup.md",
+      "docs/workbuddy-setup.md",
       "plugin.json",
       "package.json",
       "README.md",
-      "LICENSE",
-      "NOTICE.md",
-      "CHANGELOG.md"
-    ],
-    "upstreamVersion": "0.6.12",
-    "upstreamCommit": "1401c8b8030e023baeebb31781a6653fe8e93026",
-    "upstreamRepository": "https://github.com/addyosmani/agent-skills"
+      "LICENSE"
+    ]
   },
-  "version": "2.0.0",
+  "version": "2.1.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/49780522/i3-composer-agent.git"

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "i3-composer-agent",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
   "homepage": "https://github.com/49780522/i3-composer-agent",
   "repository": "https://github.com/49780522/i3-composer-agent"

package/CHANGELOG.md

@@ -1,51 +0,0 @@
-# i3 Composer Agent changes
-
-## 2.0.0 — 2026-10-07
-
-Upstream baseline: agent-skills 0.6.12 at commit 1401c8b8030e023baeebb31781a6653fe8e93026.
-
-### Changed
-
-- Commands and Skill IDs use the `i3-` prefix, such as `/i3-spec` and `$i3-spec-driven-development`.
-- Native upgrades back up and retire this package's manifest-owned unprefixed paths. Unowned entries remain in place; failed migrations roll back.
-- Local command references, hooks, routing fixtures and setup documentation follow the renamed identifiers.
-
-### Migration
-
-- Replace `/spec`, `/plan`, `/build` and other lifecycle calls with `/i3-spec`, `/i3-plan`, `/i3-build` and their prefixed equivalents. Plugin calls use `/i3-composer-agent:i3-<command>`.
-- Replace Skill calls such as `$spec-driven-development` with `$i3-spec-driven-development`.
-- Upgrade with `npx @givolt/i3-composer-agent@2.0.0 --codebuddy`, confirm replacement, then reload the host. The installer backs up manifest-owned legacy entries before retiring them.
-- Keep using the pinned 1.0.1 package if a consuming workflow needs the old identifiers. Existing published versions remain available.
-
-## 1.0.1 — 2026-10-07
-
-Upstream baseline: agent-skills 0.6.12 at commit 1401c8b8030e023baeebb31781a6653fe8e93026.
-
-### Fixed
-
-- Restore the promised terminal installation wizard with multiple tool selection, project/global scope, a destination summary and confirmation.
-- Install complete native skill files and shared references; include short lifecycle commands and personas for CodeBuddy and Claude Code.
-- Protect existing assets with confirmed replacement, backups and rollback on installation failure.
-- Retain complete plugin preparation with --prepare and existing explicit --dir calls.
-
-## 1.0.0 — 2026-10-07
-
-Upstream baseline: agent-skills 0.6.12 at commit 1401c8b8030e023baeebb31781a6653fe8e93026.
-
-### Changed
-
-- Start independent i3 release numbering. The upstream baseline remains 0.6.12; this replaces the unpublished 0.6.13 candidate.
-- Display the i3 release and upstream baseline together in the README, CLI help, and bundle preparation output. Keep --version machine-readable.
-- Include the upstream version, commit, and repository in package metadata.
-- Maintain source changes on agent/source, generate and validate a branded candidate, then update main in this independent repository.
-
-### Fixed
-
-- Preserve complete reviewed runtime assets when replaying branding, including newly approved upstream skills and commands.
-- Keep replay checks repeatable in npm bundles without repository CI files.
-- Preserve branded ignore rules and exclude Finder metadata from runtime preservation checks.
-
-## 0.6.12
-
-- Publish the first i3 Composer Agent npm distribution based on agent-skills 0.6.12.
-- Retain upstream skill IDs, command workflows, specialist personas, shared references, and MIT attribution.

package/NOTICE.md

@@ -1,15 +0,0 @@
-# Attribution
-
-i3 Composer Agent is a branded distribution of
-[Agent Skills](https://github.com/addyosmani/agent-skills) by Addy Osmani.
-The initial distribution is based on upstream commit `1401c8b` (version 0.6.12).
-
-The original MIT license and copyright notice are preserved in LICENSE.
-Givolt maintains the branding, npm distribution, and installation CLI.
-Skill IDs and command filenames use an i3- prefix in this distribution.
-The original command workflows and persona definitions are retained.
-
-The tool installation directory presets in `bin/agent-targets.json` are adapted
-from Vercel's [Skills CLI registry](https://github.com/vercel-labs/skills/blob/48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e/src/agents.ts)
-at commit `48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e`. Copyright (c) 2026
-Vercel, Inc. Its MIT license is retained in `bin/skills-registry.LICENSE`.

package/docs/advanced-per-agent-configuration.md

@@ -1,70 +0,0 @@
-# Advanced per-agent configuration
-
-Skills in this repository are intentionally portable. Every `SKILL.md` keeps its frontmatter limited to the fields the [Agent Skills specification](https://agentskills.io) defines, so the same file works across Claude Code, Cursor, Gemini CLI, Antigravity, and any other spec-conformant client.
-
-Several agents also support extra runtime controls: model routing, tool restrictions, turn limits, execution isolation. These controls are valuable, but they are vendor-specific and do not belong in the shared, portable frontmatter. This document explains which controls each agent supports, where they belong, and how to apply them as an opt-in without breaking portability.
-
-This is the canonical reference for per-agent configuration, and it supersedes the earlier approach of adding vendor fields to top-level `SKILL.md` frontmatter. Fields such as `kind`, `model`, `temperature`, `max_turns`, `tools`, and `context` must not appear at the top level of a skill. They belong under `metadata` or in a separate per-agent adapter file, as described below.
-
-## Principles
-
-1. **Keep `SKILL.md` portable.** The Agent Skills specification reserves top-level frontmatter for `name`, `description`, `license`, `compatibility`, `metadata`, and the experimental `allowed-tools`. Vendor or client-specific properties belong under `metadata`, not at the top level.
-2. **Unknown top-level fields are not guaranteed to be ignored.** Many parsers only read `name` and `description` and silently drop the rest, but a strict spec-conformant validator or client may flag or reject unrecognized top-level keys. Putting vendor fields under `metadata` keeps the file conformant everywhere.
-3. **Opt-in, not global.** Runtime controls should be something a user adds for their own agent and workflow, not a default baked into every skill in the repository.
-4. **Prefer generation over hand-editing.** Where a configuration is repetitive and mechanical, generate it from a single source of truth instead of maintaining copies by hand. See [Automating with scripts](#automating-with-scripts).
-
-## Where vendor fields belong
-
-| Field type | Example | Correct home |
-|---|---|---|
-| Spec fields | `name`, `description`, `license`, `compatibility` | Top-level frontmatter in `SKILL.md` |
-| Vendor metadata | model hints, routing tags | Under the `metadata` key in `SKILL.md` |
-| Runtime orchestration | subagent definitions, turn limits, tool allowlists | A separate per-agent adapter file (see each agent below) |
-
-## Claude Code
-
-Claude Code reads `name` and `description` for discovery. Custom commands and skills share the same frontmatter, so the `context` and `allowed-tools` fields below work in both `.claude/commands/*.md` and `.claude/skills/*/SKILL.md`.
-
-- **`context: fork`** runs a command or skill in an isolated subagent context instead of the active conversation. This gives context isolation, repeatable execution from a clean state, execution tokens spent in the fork rather than the main session, and a cleaner handoff where only the result surfaces back. An optional **`agent`** field selects which subagent type runs the fork (for example `agent: Plan`); it defaults to `general-purpose`.
-- **`allowed-tools`** pre-approves tools; it does not restrict them. Listed tools run without a permission prompt for the turn that invokes the command or skill, and the grant clears on your next message. Nothing is removed from the tool pool.
-- **`disallowed-tools`** is the field that actually restricts: it removes the listed tools from the available pool while the skill is active, which is what least-privilege needs for passive stages such as review or audit. The restriction also clears on your next message. Note it is a Claude Code field and not one of the specification's six, so it belongs in a local copy or an adapter file; in a published `SKILL.md` it fails packaging with an unexpected-key error.
-
-These are Claude Code conventions. Keep the shared, published `SKILL.md` limited to spec fields; apply these runtime controls in your own local command or skill copies instead.
-
-## Gemini CLI and Antigravity
-
-Gemini CLI and Antigravity discover skills the same way: they match `name` and `description`, then load the full skill on demand. Runtime orchestration lives in a separate resource, not in the skill frontmatter.
-
-- **Subagent definitions** live in `.gemini/agents/*.md`, which are distinct from skills. Their schema is `kind` (`local` or `remote`), `model`, `temperature`, `max_turns`, and `tools`. Note that this is a subagent schema, not a skill schema: the two should not be merged into one `SKILL.md`.
-- **Model routing** can send lighter tasks (formatting, documentation, git operations) to a faster model and reserve a stronger model for cognitively demanding work (debugging, security auditing, interface design).
-- **Tool restrictions** enforce least-privilege per subagent, which also trims unused tool schemas from the prompt.
-- **Turn limits** (`max_turns`) cap execution to avoid runaway correction loops.
-
-### Model guidance
-
-Google recommends omitting `temperature` for Gemini 3.x models and using `thinking_level` instead. Do not hardcode `temperature` on skills or subagents routed to 3.x models; prefer `thinking_level` and revisit this guidance as the models evolve.
-
-```yaml
-# .gemini/agents/security-auditor.md
----
-kind: local
-model: gemini-3-pro
-thinking_level: high   # not: temperature: 0.1
-tools: [read_file, grep]
-max_turns: 10
----
-```
-
-## Automating with scripts
-
-Maintaining per-agent metadata by hand across every skill is repetitive, drifts out of sync, and is easy to get wrong. A better approach is to keep a single source of truth and generate the agent-specific output:
-
-- A generator reads a per-skill configuration map (which model, tool allowlist, turn limit, and isolation each skill should use for a given agent).
-- For metadata-style fields, it injects them under the `metadata` key of each `SKILL.md`, keeping the file spec-conformant.
-- For orchestration-style fields, it emits the separate adapter files an agent expects, for example `.gemini/agents/*.md` subagent definitions, leaving `SKILL.md` untouched.
-
-Generation also lets the tooling validate **semantics, not just shape**: confirm that a model name is a known model, that a tool name is a real tool, that `max_turns` is a positive integer, and that `temperature` (where still applicable) is a valid number in range. Shape-only checks let invalid values such as `parseInt("1.5")` or `parseFloat("0.2oops")` slip through.
-
-## Status
-
-This document consolidates the discussion from [#272](https://github.com/addyosmani/agent-skills/pull/272), [#36](https://github.com/addyosmani/agent-skills/pull/36), and [upstream agent-skills #35](https://github.com/addyosmani/agent-skills/issues/35), all closed in favor of this approach. It is the single reference for per-agent configuration: it keeps the shared skills portable while documenting the advanced controls each agent offers as an opt-in. The script-based automation described above is a proposal pending agreement before any implementation.

package/docs/comparison.md

@@ -1,131 +0,0 @@
-<!--
-  This document is for developers evaluating the project. It is NOT a skill and
-  is not meant to be loaded into an agent's context. It lives in docs/ so it
-  stays out of the agent's working set.
--->
-
-# How agent-skills compares
-
-> **Upstream research:** This comparison is retained from Addy Osmani's `agent-skills` at commit `1401c8b8030e023baeebb31781a6653fe8e93026`. Its experiments describe the upstream project; they are not independent evaluations of i3 Composer Agent.
-
-People often ask how **agent-skills** relates to the two other "skills for coding agents" collections they hear about most: **Superpowers** (Jesse Vincent / obra) and **Matt Pocock's skills**. All three are good, share a lot of DNA, and are worth learning from. This page is an honest map of how they are *shaped* differently, so you can pick the one that fits how you work, or borrow across all three.
-
-> **TL;DR** — They optimize for different moments. **agent-skills** organizes the *whole product lifecycle* (Define, Plan, Build, Verify, Review, Ship) with review personas, anti-rationalization guards, and an in-repo eval framework that checks the skills actually route and behave. **Superpowers** leans into *autonomous, reasoning-heavy* runs with subagents, a strict pipeline, and worktree isolation. **Matt Pocock's skills** are a *sharp, opinionated Claude Code toolkit* distilled from one expert's daily workflow, with a signature "grill me" interrogation loop. None is "best" in the abstract; it depends on the work in front of you.
-
----
-
-## At a glance
-
-| | **agent-skills** | **Superpowers** | **Matt Pocock's skills** |
-|---|---|---|---|
-| **Core idea** | Encode the full senior-engineering lifecycle as skills | A complete development *methodology* built on composable skills | One expert's Claude Code workflow, open-sourced and evolving |
-| **Organizing principle** | SDLC **phases** (Define to Ship) behind a meta-skill router | A single disciplined loop: brainstorm, plan, execute, review | A curated toolbox of focused, composable commands |
-| **Catalog size** | 25 skills spanning the whole lifecycle | ~14 skills, deep on the inner build loop | ~30 skills, grouped into engineering / productivity / in-progress / deprecated |
-| **Lifecycle coverage** | Broad: idea refinement, API and UI design, security, performance, CI/CD, observability, deprecation, ADRs, launch | Deep but narrow: TDD, debugging, planning, review, skill authoring | Define and Build heavy: grilling, PRDs, issues, TDD, architecture, bug triage, knowledge management |
-| **Entry points** | Slash commands mapped 1:1 to phases (`/spec` `/plan` `/build` `/test` `/review` `/code-simplify` `/ship`, plus `/webperf`), with a `/build auto` full-plan mode | Skill-chained pipeline (`brainstorming`, `writing-plans`, `subagent-driven-development`) | Slash commands (`/grill-me`, `/tdd`, `/to-prd`, `/diagnosing-bugs`, `/grill-with-docs`) |
-| **Distinctive mechanisms** | Anti-rationalization tables and Red Flags in every skill; parallel review **personas** in `/ship`; reference checklists; a **three-tier eval framework** in CI | Subagent-driven development with a task reviewer (spec + quality) and a fix loop; git-worktree isolation; skills-that-write-skills, pressure-tested | The **grilling** primitive (one question at a time, design-tree walking); seam-based TDD; explicit user-invoked vs model-invoked split; issue-tracker integration |
-| **Quality measurement** | Trigger, routing, and behavioral evals run against the catalog (in-repo, some in CI) | Pressure-testing methodology is core to its philosophy; the eval suite itself now lives in a separate repo | None shipped in-repo |
-| **Tooling reach** | Claude Code, Cursor, Gemini CLI, Antigravity, OpenCode, Windsurf, Copilot, Kiro, Codex, Command Code, plus the `npx skills` CLI | One of the widest and most actively churned surfaces: Claude Code, Codex, Cursor, Copilot CLI, OpenCode, Kimi, Factory Droid, Antigravity, Pi | Claude Code first, distributed via `npx skills add`; other agents work with varying fidelity |
-| **Governance** | Actively reviews and merges community contributions; every skill ships an eval | Largely solo-authored; a substantial backlog of unmerged community PRs | Solo-authored, self-merged, developed openly in public |
-| **Best for** | Driving a feature through every phase with a human checkpoint at each | Long, autonomous, reasoning-heavy or exploratory work | A pragmatic, battle-tested daily loop, strongest at requirements and TDD |
-
-*(We deliberately leave out star counts and adoption figures: they are cited wildly differently across blogs and change weekly. All three are actively used and maintained.)*
-
----
-
-## The three projects, in their own terms
-
-### Superpowers (obra)
-
-A full software-development *methodology* built on composable skills. It bets on **autonomy and upfront reasoning**. A session runs a deliberately linear pipeline: Socratic brainstorming that writes a dated spec and permits exactly one handoff, detailed plans written to be executable by "an enthusiastic junior engineer with poor taste and no context," then subagent-driven execution where a fresh subagent implements each task and a task reviewer signs off on both spec compliance and code quality before it closes, with a fix loop for anything it flags and a whole-branch review on the most capable model at the end. Git worktrees keep parallel work isolated, and its `writing-skills` skill applies TDD to documentation itself: no skill ships without a failing test first.
-
-Its strengths are real: hand off a sizable chunk and come back to a reviewed result, with strong guardrails against an agent rationalizing its way past the process. The trade-offs are the flip side of that discipline. Coverage is narrow (it is an inner-loop build methodology, not a security-to-launch lifecycle), the single pipeline can feel heavy on small changes, and the recent direction has been about paying down that cost, for example consolidating to a single task reviewer for roughly twice the speed and half the tokens. The loudest thing its community keeps asking for, multi-agent team execution, is not yet in the box.
-
-**Repo:** <https://github.com/obra/superpowers>
-
-### Matt Pocock's skills
-
-Matt open-sourced the Claude Code skills he actually uses, and the collection has grown into a broad, opinionated toolbox organized in public, complete with visible `in-progress/` and `deprecated/` directories that model the discipline the skills preach. The center of gravity is not TDD, it is **grilling**: a reusable interrogation loop that asks one question at a time, walks each branch of the design tree resolving dependencies in order, offers a recommended answer per question, prefers reading the codebase over asking, and refuses to proceed until you confirm a shared understanding. `grill-me` and `grill-with-docs` are thin wrappers over it. The TDD skill is distinctive too and cheerfully heterodox ("refactoring is not part of the loop," it belongs to code review), and there is a deliberate split between user-invoked and model-invoked skills to treat agent context as a scarce budget.
-
-Its strengths are authenticity and sharpness: this is how one very good engineer ships, not a committee's idea of a framework, and the requirements-grilling loop is genuinely excellent. The trade-offs: it is Claude Code first in practice (other agents surface reliability rough edges), there are no in-repo evals to catch regressions, lifecycle coverage past Build is thin, and some skills couple to a personal setup wizard and tracker conventions. Recent work is pushing from single-session skills toward multi-session orchestration through issue trackers (the in-progress `wayfinder`).
-
-**Repo:** <https://github.com/mattpocock/skills> · related: <https://github.com/mattpocock/agent-rules-books>
-
-### agent-skills (this project)
-
-agent-skills organizes the **entire product lifecycle** as skills, with a meta-skill (`using-agent-skills`) that routes a task to the right one. Every skill carries a **Common Rationalizations** table (the excuses an agent makes to skip a step, each rebutted) and **Red Flags**. Slash commands map one-to-one to lifecycle phases; `/build auto` runs a whole approved plan in one pass; and `/ship` fans out review **personas** (`code-reviewer`, `security-auditor`, `test-engineer`, `web-performance-auditor`) in parallel, then merges them into a go/no-go. It keeps a human checkpoint at each phase, ships seven reference checklists including a Definition of Done, and runs across most major agent tools with a single-command install on several of them.
-
-What is newer, and the current point of difference: a **three-tier eval framework** lives in the repo. Tier 1 checks structure, Tier 2 checks that each skill's description carries the vocabulary users actually say and that no two skills collide on routing (deterministic, runs in CI), and Tier 3 grades an agent's real execution trace against per-skill expectations. Neither of the other two ships that kind of in-repo, catalog-wide measurement today. The honest trade-off in the other direction: agent-skills has less of a single opinionated "run" than Superpowers, and none of the three has yet solved durable cross-session memory well.
-
----
-
-## A real head-to-head: Superpowers vs. agent-skills
-
-Om Mishra ran a controlled experiment, same model, same repo, same prompt in Claude Code, changing only the skill framework, and wrote it up:
-
-**["Superpowers vs Agent-Skills: Faster Shipping, Safer Reasoning"](https://www.linkedin.com/pulse/superpowers-vs-agent-skills-faster-shipping-safer-reasoning-om-mishra-dzakf/)** by Om Mishra
-
-Summarized fairly:
-
-- **agent-skills** moved to code faster (~8 min vs ~12) and ran **more validation passes** (7 vs 5, including the full test suite). That broader validation caught a compatibility issue *outside* the immediate feature that the feature-specific tests missed. He gave it the edge on **validation depth** for that task.
-- **Superpowers** invested more **upfront architectural reasoning**, which he still prefers as his daily driver for evolving production systems and exploratory work with no established pattern to follow.
-- Token efficiency was effectively identical; both replanned once.
-
-It is one developer's single-task experiment, not a benchmark, but it is a concrete illustration of the core trade-off: **broad disciplined validation versus heavy upfront reasoning**. His own conclusion is the honest one: pick the tool to the task.
-
----
-
-## How to decide what to use
-
-The at-a-glance table tells you how they are shaped. This is how to choose in practice.
-
-### Start with the shape of your work
-
-- **A whole feature, front to back?** agent-skills. It is the only one of the three that carries you from spec through security, performance, and launch with a checkpoint at each phase, so nothing quietly skips the review or the pre-flight.
-- **A big, ambiguous chunk you want to hand off and walk away from?** Superpowers. Its pipeline and subagent review are built to run for a long time and hand back a result that has already been reviewed against the spec.
-- **A fast, focused daily loop, especially getting requirements right before code?** Matt Pocock's skills. The grilling loop is the sharpest requirements tool of the three, and the toolkit stays out of your way.
-
-### Then weight what you actually care about
-
-- **Breadth of coverage** (security, performance, CI/CD, observability, launch): agent-skills is the clear pick; the others are inner-loop focused.
-- **Autonomy over a long run**: Superpowers, by design.
-- **Low ceremony on small changes**: Pocock's toolkit is lightest; agent-skills offers a middle gear (a small change can skip straight to `/test` and `/review`); Superpowers is the most process-heavy.
-- **Confidence that the skills themselves work**: agent-skills is the only one with catalog-wide evals in the repo, so a description or routing regression fails CI rather than surfacing as a mysterious "why didn't the skill fire" later.
-- **Requirements interrogation**: Pocock's grilling is the reference implementation; agent-skills' `interview-me` is close in spirit and gaining an opt-in collaborative mode.
-- **Platform spread**: agent-skills and Superpowers both run almost everywhere; Pocock is happiest on Claude Code.
-- **A human gate at each step vs. a hands-off run**: agent-skills checkpoints by default; Superpowers minimizes mid-run check-ins on purpose.
-
-### Concrete scenarios
-
-- *"Ship a new endpoint with auth, tests, and a security pass before merge."* agent-skills: `/spec` to `/ship`, with the security-auditor and test-engineer personas fanning out at the end.
-- *"Refactor a gnarly subsystem overnight and review it in the morning."* Superpowers: hand it the plan, let subagent-driven development and the task reviewer run.
-- *"I have a vague idea and keep letting the agent guess the requirements."* Pocock's `grill-me` (or agent-skills' `interview-me`) to pin down intent before any code.
-- *"Fix one clear bug, test-first."* Any of them; reach for the lightest one you already have installed.
-- *"Standardize how a team of engineers uses agents across a repo."* agent-skills: the phase commands, personas, and shared checklists give a team a common vocabulary, and the evals keep custom skills honest.
-- *"Roll my own skills and know they trigger correctly."* agent-skills, and borrow Superpowers' pressure-testing discipline for the ones that must not be rationalized away.
-
-### Solo vs. team
-
-For a solo developer, taste and momentum win: pick the one whose defaults match how you already work, and the lowest-ceremony option is often the most-used one. For a team, the calculus shifts toward shared structure and guardrails you can enforce: named phases, review personas, checklists, and evals that fail CI are what keep five people (and their agents) converging on the same standard rather than five private workflows. That is the situation agent-skills is built for, though a team can absolutely adopt Superpowers' review discipline or Pocock's grilling loop within it.
-
-### The shared frontier (true of all three)
-
-None of these has solved **durable cross-session memory** well yet: what an agent learned in one session rarely carries cleanly into the next. All three are circling it (learnings files, handoff artifacts, tracker-backed planning maps). If that is your bottleneck, know that you are at the edge of what any of them ships today, and expect to stitch some of it yourself for now.
-
----
-
-## Combining them
-
-You do not have to choose exclusively, but combine with care. These are Markdown skills, not runtimes, so cherry-picking *individual* skills works well: pull in Pocock's `grill-me`, a Superpowers isolation pattern, or a specific checklist alongside your main setup.
-
-What does not work is running two of them as your **active router at the same time**. Stacked meta-skills fight over command names (`/tdd` defined in two places), compete on routing logic, and pull in different TDD philosophies, so you get unpredictable behavior rather than the best of both. Pick one framework as your primary router, and borrow from the others a la carte.
-
----
-
-## Sources
-
-- Superpowers: <https://github.com/obra/superpowers>
-- Matt Pocock's skills: <https://github.com/mattpocock/skills>
-- Om Mishra, *Superpowers vs Agent-Skills*: <https://www.linkedin.com/pulse/superpowers-vs-agent-skills-faster-shipping-safer-reasoning-om-mishra-dzakf/>
-
-*Spotted something inaccurate about another project here? Open an issue or PR. We would rather be fair than flattering.*