diff --git a/.tasks/STATUS.md b/.tasks/STATUS.md index fc5945d..cc62075 100644 --- a/.tasks/STATUS.md +++ b/.tasks/STATUS.md @@ -74,4 +74,5 @@ _Updated: 2026-04-28_ - Decide whether to write a smoke-test that round-trips `skills//` → `dist/.skill` → unpack → diff (would catch archive-shape regressions). - Tune `active-platform` triggers based on real-world usage; add WSL handling if it comes up. - Consider running formal `skill-creator` eval loop on `active-platform` once we have ~5 real interactions to learn from. -- **Migrate this repo's `.wiki/` to the canonical Karpathy layout** (it was bootstrapped with the old buggy template). Directory rename + file moves; needs a conscious commit, not a silent piggyback. +- **Migrate this repo's `.wiki/` to the canonical Karpathy layout** (it was bootstrapped with the old buggy template). Directory rename + file moves; needs a conscious commit, not a silent piggyback. _(done — `4382fd3`)_ +- **Fix `project-bootstrap` Step 4 to match `task-status-wiki` canon.** Same class of bug as the wiki fix: bootstrap creates a single flat `STATUS.md`, but `task-status-wiki` SKILL.md expects per-task files (`.tasks/.md`) plus `STATUS.md` as a board pointing at them with emoji-status convention (🔴 active / 🟡 paused / ⚪ ready / 🟢 done / 🔵 blocked). Two pieces of work: (a) update bootstrap Step 4 + asset, (b) migrate this repo's existing `.tasks/STATUS.md` to per-task files. diff --git a/.wiki/concepts/skill-vs-plugin.md b/.wiki/concepts/skill-vs-plugin.md new file mode 100644 index 0000000..15499ed --- /dev/null +++ b/.wiki/concepts/skill-vs-plugin.md @@ -0,0 +1,77 @@ +--- +title: Skill vs Plugin +type: concept +updated: 2026-04-28 +--- + +# Skill vs Plugin + +When to ship a capability as a bare `SKILL.md` vs as a full Claude Code plugin. + +## What a plugin can ship + +A plugin is a bundle. It can include any of: + +| Component | Purpose | Loadable any other way? | +|---|---|---| +| **Skills** (`skills//SKILL.md`) | Behavioral guidance for Claude | Yes — copy to `~/.claude/skills/` | +| **Slash commands** (`commands/.md`) | `/foo` invocations | **No** — only via plugin manifest | +| **Hooks** (`hooks/`) | `session-start`, `pre-tool-use`, etc., executed by the harness | **No** — must be in plugin | +| **Sub-agents** (`agents/.md`) | `Agent { subagent_type: "" }` | **No** — only via plugin | +| **MCP servers** (`.mcp.json`) | Adds tools like `mcp__context7__*` | Manual `~/.claude/settings.json`, but loses versioning/marketplace ops | +| **Output styles, statusline, etc.** | Cosmetic / harness config | **No** | +| **Versioning + release notes** | `/plugin update X` flow | **No** | + +A bare `SKILL.md` is just one row in that table — the first one. + +## When the bare skill is enough + +If the artifact is *only* `SKILL.md` files (with optional `assets/`, `references/`): + +- A folder under `~/.claude/skills//` works. +- Distribute via `.skill` archive (zip) or copy the folder. +- All 13 skills in this repo are bare skills. No plugin needed. + +## When you actually need a plugin + +Any of: + +- **A slash command.** `/brainstorm`, `/commit`, `/loop`. Only path is `commands/.md` in a plugin. +- **A hook.** Auto-load behavior on session start / prompt submit / post-tool-use. Hooks fire from the harness, not from Claude. Plugin manifest is how the harness finds them. +- **A sub-agent type.** Plugin manifest is how `Agent` discovers it. +- **MCP server registration.** Yes, you can shove it into `~/.claude/settings.json` manually (we did this for context7 originally). But the official plugin gets you marketplace ops — `/plugin install`, `/plugin update`, `/plugin uninstall` — which manual JSON doesn't. +- **Versioning + marketplace path.** Consumers can pull updates without chasing. + +## Real example: `superpowers` + +The official `superpowers` plugin ships: + +| Component | Count | Notes | +|---|---|---| +| Skills | 14 | Could live as bare skills | +| Slash commands | 3 | `/brainstorm`, `/execute-plan`, `/write-plan` — only via plugin | +| Hooks | 4 | Includes `session-start` | +| Sub-agents | 1 | `code-reviewer` | + +The killer feature: the `session-start` hook auto-injects `using-superpowers` content at the top of every session. That's why we see `superpowers:brainstorming`, `superpowers:writing-plans`, etc. listed in `available_skills` from the very first message — without anyone saying "use superpowers". Bare-skill copies can't do that. + +## Decision flow + +``` +Want to ship a capability → + Only SKILL.md content? → bare skill (skills//, install via copy/zip) + Need /? → plugin + Need a session-start (or other) hook? → plugin + Need a subagent_type? → plugin + MCP server with /plugin update? → plugin (see context7-setup.md) +``` + +## What this means for *this* repo + +All 13 of our skills are currently bare. None ships slash commands, hooks, or sub-agents — so no plugin format is needed today. + +The moment to reconsider: if we want a `/caveman` slash command, or a `session-start` hook that auto-loads `active-platform` based on `uname`, or a sub-agent like a "skill-tester". At that point — wrap the relevant skills into a plugin and publish through a marketplace (own or `claude-plugins-official` if that channel becomes available). + +## See also + +- [context7-setup.md](context7-setup.md) — concrete example of switching a manual MCP registration to a plugin (and the cost: re-injecting `--api-key` after `/plugin update`). diff --git a/.wiki/index.md b/.wiki/index.md index 4faf16c..797679e 100644 --- a/.wiki/index.md +++ b/.wiki/index.md @@ -16,6 +16,7 @@ Catalog of all wiki pages. One line per page, organized by type. Updated on ever - [build-notes.md](concepts/build-notes.md) — why `build.ps1` exists alongside `build.sh`; PS 5.1 backslash-in-zip gotcha; how to extract a `.skill` - [context7-setup.md](concepts/context7-setup.md) — switched context7 from manual MCP entries to the official plugin; API key in `.mcp.json` as `--api-key`; now also captured as `setup-context7` skill (one-time install/migrate flow with key discovery) - [repo-layout.md](concepts/repo-layout.md) — flat `skills/`, committed `dist/`, bash + PowerShell scripts; install model +- [skill-vs-plugin.md](concepts/skill-vs-plugin.md) — when a bare SKILL.md is enough vs when you actually need a plugin (slash commands, hooks, sub-agents, MCP servers); concrete breakdown of `superpowers` - [wiki-realignment.md](concepts/wiki-realignment.md) — fixing `project-bootstrap` to create the Karpathy-canonical wiki layout ## Packages diff --git a/.wiki/log.md b/.wiki/log.md index 6a7b085..a0406ab 100644 --- a/.wiki/log.md +++ b/.wiki/log.md @@ -21,3 +21,4 @@ Parseable: `grep "^## \[" .wiki/log.md | tail -20`. ## [2026-04-28] decision | context7-setup — switched to official plugin; --api-key injected into plugin's .mcp.json; three manual MCP entries removed ## [2026-04-28] decision | setup-context7 skill — formalized the install/migrate algorithm; using-context7 gets a Prerequisites pointer; build.sh PS multi-arg bug fixed (loop instead of comma-joined -Names) ## [2026-04-28] verify | setup-context7 — Vitya ran using-context7 in a session that needed setup; Prerequisites pointer triggered setup-context7; full flow worked end-to-end. Pattern (policy + setup split) validated. +## [2026-04-28] decision | skill-vs-plugin — documented when a bare skill suffices vs when a plugin is required (slash commands, hooks, sub-agents, MCP via marketplace)