Add research documentation for marketing skills and superpowers plugins

README.md

@@ -1,6 +1,10 @@
-# Agent Skills
+# Agent Skills For Real Engineers
 
-A collection of agent skills that extend capabilities across planning, development, and tooling.
+My agent skills that I use every day to do real engineering - not vibe coding.
+
+If you want to keep up with changes to these skills, and any new ones I create, you can join ~60,000 other devs on my newsletter:
+
+[Sign Up To The Newsletter](https://www.aihero.dev/s/skills-newsletter)
 
 ## Planning & Design
 

domain-model/CONTEXT-FORMAT.md

@@ -10,7 +10,7 @@
 ## Language
 
 **Order**:
-A customer's request to purchase one or more items.
+{A concise description of the term}
 _Avoid_: Purchase, transaction
 
 **Invoice**:

research/README.md

@@ -0,0 +1,17 @@
+# Research
+
+Research notes informing the infrastructure plan for this repo.
+
+- [superpowers.md](./superpowers.md) — `obra/superpowers`: a single skill bundle that ships as Claude Code, Codex App, Cursor, OpenCode, and Gemini plugins simultaneously by colocating manifests at the repo root. Themed grouping happens in a _separate_ curation repo (`obra/superpowers-marketplace`), not as a monorepo.
+- [marketingskills.md](./marketingskills.md) — `coreyhaines31/marketingskills`: minimalist single-plugin marketplace, zero npm deps, all codegen via Node stdlib + bash. Notable patterns: `evals/evals.json` per skill, `VERSIONS.md` auto-update protocol, sync-skills.js GHA that auto-rewrites the marketplace and README on push.
+
+## Cross-cutting takeaways
+
+| Goal                 | superpowers                                                            | marketingskills                           | Implication                                                                                                                                                                   |
+| -------------------- | ---------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `npx skills add`     | not used                                                               | first-class                               | "Just be SKILL.md-spec compliant under `skills/`" — no work                                                                                                                   |
+| Claude Code plugins  | `.claude-plugin/` at root, themed groups via separate marketplace repo | single-plugin marketplace                 | Neither models a multi-plugin monorepo. Matt's plan (multiple plugins under `plugins/<name>/`, one marketplace.json listing them with `source: "./plugins/<name>"`) is novel. |
+| Codex plugins        | `.codex-plugin/plugin.json` (Codex App) + `.codex/INSTALL.md` (CLI)    | implicit via AGENTS.md only               | If Matt wants Codex App marketplace presence, copy superpowers' `.codex-plugin/`. If just CLI, AGENTS.md suffices.                                                            |
+| Docs site            | none                                                                   | none                                      | No prior art — Matt would be the first.                                                                                                                                       |
+| Build tooling        | bash + jq, no package.json scripts                                     | Node stdlib + bash, no deps               | Both prove you don't need a build pipeline. Multi-plugin assembly may change that.                                                                                            |
+| SKILL.md frontmatter | `name`, `description` only                                             | `name`, `description`, `metadata.version` | Keep it minimal.                                                                                                                                                              |

research/marketingskills.md

@@ -0,0 +1,152 @@
+# Research: `coreyhaines31/marketingskills`
+
+A marketing-themed Agent Skills repo by Corey Haines. The infrastructure is genuinely interesting and notably *minimal*: zero npm dependencies, all codegen done with Node stdlib + bash.
+
+## Repo structure
+
+```
+.claude-plugin/        marketplace.json, plugin.json
+.github/               workflows + sync script + issue/PR templates
+skills/                40 skill dirs (flat, one level deep)
+tools/                 clis/, integrations/, composio/, REGISTRY.md
+AGENTS.md  CLAUDE.md  CONTRIBUTING.md  README.md  VERSIONS.md
+validate-skills.sh  validate-skills-official.sh
+```
+
+`CLAUDE.md` is a one-line file: `AGENTS.md` (i.e. it points Claude at the cross-agent file, treating AGENTS.md as the source of truth).
+
+Each skill directory is uniform:
+
+```
+skills/<name>/
+├── SKILL.md
+├── evals/evals.json        # eval prompts + assertions
+└── references/*.md         # progressive-disclosure docs
+```
+
+No `scripts/` or `assets/`. Skills are flat (no nesting / sub-skills). **No `plugins/` or `dist/` directories** — the repo *is* the plugin, served from root.
+
+## Plugin packaging
+
+Ships as a Claude Code plugin marketplace via two manifests:
+
+`.claude-plugin/marketplace.json`:
+```json
+{
+  "name": "marketingskills",
+  "owner": { "name": "Corey Haines", "url": "https://corey.co" },
+  "metadata": { "version": "1.9.0" },
+  "plugins": [
+    { "name": "marketing-skills",
+      "description": "40 marketing skills...",
+      "source": "./" }
+  ]
+}
+```
+
+`.claude-plugin/plugin.json`:
+```json
+{ "name": "marketing-skills", "version": "1.9.0",
+  "skills": "./skills", "license": "MIT" }
+```
+
+**One marketplace, one plugin, all 40 skills bundled.** No themed sub-grouping into multiple plugins — the README's "categories" exist only as headings, not separate installable units. (Relevant for Matt's multi-plugin goal: this repo doesn't actually demonstrate a multi-plugin marketplace.)
+
+VERSIONS.md notes the `plugin.json` was added explicitly so Claude Code's loader recognizes the skills directory.
+
+## Build tooling
+
+**No package.json, no TypeScript, no bundler, no dist build.** The only Node code is `.github/scripts/sync-skills.js` — a zero-dependency script (`fs`, `path` only) that:
+
+1. Walks `skills/*/SKILL.md`
+2. Parses YAML frontmatter with a hand-rolled regex (`/^---\n([\s\S]*?)\n---/`) — naïve key:value splitter, no real YAML lib
+3. Rewrites the `plugins[0].skills` array in `marketplace.json` to a list of `./skills/<name>` paths
+4. Updates the skill count in the plugin description (`/\d+ marketing skills/`)
+5. Replaces the `<!-- SKILLS:START -->...<!-- SKILLS:END -->` block in README.md with a regenerated table (description truncated to 120 chars at a word boundary)
+
+That's the entire codegen story. `validate-skills.sh` and `validate-skills-official.sh` are bash-only frontmatter linters using `sed`/`grep`.
+
+## Installation story
+
+Six options listed in the README, in priority order:
+
+1. **vercel-labs/skills CLI** — `npx skills add coreyhaines31/marketingskills [--skill page-cro copywriting] [--list]`. README claims this installs to `.agents/skills/` and symlinks `.claude/skills/` for Claude Code.
+2. **Claude Code plugins** — `/plugin marketplace add coreyhaines31/marketingskills` then `/plugin install marketing-skills`.
+3. Clone-and-copy.
+4. Git submodule.
+5. Fork.
+6. **SkillKit** (`npx skillkit install ...`) for cross-agent install (Cursor/Copilot/etc).
+
+**Codex support** is implicit: the repo ships `AGENTS.md` (the cross-agent spec file Codex reads) and the README claims compatibility with "Claude Code, OpenAI Codex, Cursor, Windsurf, and any agent that supports the Agent Skills spec." There is **no Codex-specific plugin manifest** — Codex compatibility comes purely from being SKILL.md-spec-compliant + AGENTS.md at root.
+
+## Docs site
+
+**There is no embedded docs site.** No `docs/`, no `site/`, no `website/`, no Docusaurus/Nextra/Astro config, `has_pages: false`. The README claims `homepage: https://marketing-skills.com` but it is not built from this repo.
+
+The only generated docs artifact is the README skills table (built by `sync-skills.js`).
+
+## CI / release
+
+Two workflows:
+
+- **`.github/workflows/sync-skills.yml`** — on push to `main` touching `skills/**`, runs `sync-skills.js` and commits the result back via `stefanzweifel/git-auto-commit-action@v7` as a bot user. This is the "build step" — it auto-rewrites `marketplace.json` and `README.md` whenever skills change.
+- **`.github/workflows/validate-skill.yml`** — on push/PR touching `**/SKILL.md`. A `detect-changes` job computes the changed skill dirs via git diff and a jq-built JSON array, then a matrix `validate` job runs `Flash-Brew-Digital/validate-skill@v1` on each. Skips drafts and dependabot.
+
+No release/publish workflow — versioning is tracked manually in `VERSIONS.md` (per-skill semver + dates) and in `marketplace.json`/`plugin.json`'s top-level `version`.
+
+## SKILL.md format
+
+Frontmatter is minimal:
+
+```yaml
+---
+name: page-cro
+description: When the user wants to optimize... [trigger phrases and "For X, see other-skill" cross-refs]
+metadata:
+  version: 1.1.0
+---
+```
+
+Conventions documented in `AGENTS.md`:
+- `name`: 1-64 chars, lowercase a-z + digits + hyphens, must match dir
+- `description`: 1-1024 chars, *must* include trigger phrases AND scope-boundary cross-references to sibling skills
+- `metadata.version` only (no author/license per-skill)
+- SKILL.md kept under 500 lines; details pushed into `references/`
+
+Distinctive description style: every skill enumerates trigger-phrase-laden quotes ("CRO," "this page isn't converting," "my landing page sucks") plus explicit `For X, see other-skill` boundaries — clearly tuned for the Skill-tool dispatcher's keyword matching.
+
+## Distinctive / novel patterns
+
+1. **Per-skill `evals/evals.json`** — every skill has structured eval prompts with `expected_output` summary + a list of `assertions` strings. Not wired into CI but provides a dataset for offline eval runs.
+
+2. **Auto-update protocol baked into `AGENTS.md`** — instructs the agent to fetch `VERSIONS.md` from raw.githubusercontent once per session, compare local versions, and surface a non-blocking notification if 2+ skills are stale or any has a major bump. Includes a "say 'update skills'" trigger that runs `git pull`. This is a memory-less, network-fetched update channel.
+
+3. **`product-marketing-context` as a hub skill** — every other skill is documented to read `.agents/product-marketing-context.md` (with `.claude/` fallback) before doing anything. README diagram shows it as the root of a star topology.
+
+4. **Claude Code-only escape hatch in AGENTS.md** — explicitly calls out that `` !`command` `` shell-injection syntax is Claude Code-only and **must not** be in the cross-agent SKILL.md files. Suggests local override in `.claude/skills/` if you want it. Clean pattern: keep skills cross-agent, document Claude-Code-only enhancements separately.
+
+5. **`tools/` registry** — orthogonal to skills, not part of the plugin. 60+ zero-dep Node CLIs (`tools/clis/<vendor>.js`) plus 80+ markdown integration guides plus a Composio mapping. AGENTS.md tells the agent: skills *reference* tools by name, agent reads `tools/REGISTRY.md` and `tools/integrations/<tool>.md` on demand. Effectively a second progressive-disclosure layer beyond `references/`.
+
+6. **No package.json / no JS deps** — the entire codegen + validation pipeline is `node` (stdlib only) + `bash`. Maximally portable.
+
+7. **No agents, no hooks, no slash-commands** — README hints at `/page-cro` invocations, but no `commands/` directory exists. These are skill-name invocations the Claude Code plugin loader produces automatically.
+
+## Takeaways for Matt's infra goals
+
+- **Multi-plugin marketplace (goal 2)**: this repo is *not* a model for that — single-plugin marketplace. The marketplace.json schema does support multiple `plugins[]` entries pointing to different `source` paths, so for themed groups Matt would want each plugin to live in its own subdir (e.g. `plugins/architecture/`, `plugins/typescript/`) each with their own `skills/`. coreyhaines31 doesn't demonstrate this.
+- **Codex (goal 3)**: cheap — drop AGENTS.md at root, keep SKILL.md spec-compliant, claim compatibility. No separate manifest needed.
+- **vercel-labs CLI (goal 1)**: zero work — once `skills/<name>/SKILL.md` exists with valid frontmatter, the CLI picks it up. coreyhaines31 added nothing extra.
+- **Docs site (goal 4)**: not modeled here; this repo opts out and links to a separately-hosted marketing site.
+- **Worth copying**: the `sync-skills.js` + GitHub Action pattern (auto-rewrite README table and marketplace skill list on push), the `VERSIONS.md` + auto-update protocol, the `evals/evals.json` per skill, and the AGENTS.md note about keeping `` !`command` `` out of cross-agent SKILL.md.
+
+## Key file paths
+
+(all on `main` branch of `coreyhaines31/marketingskills`)
+
+- `/.claude-plugin/marketplace.json`, `/.claude-plugin/plugin.json`
+- `/.github/scripts/sync-skills.js`
+- `/.github/workflows/sync-skills.yml`, `/.github/workflows/validate-skill.yml`
+- `/AGENTS.md` (the canonical agent guide; `CLAUDE.md` just points to it)
+- `/VERSIONS.md`
+- `/skills/<name>/SKILL.md` + `/skills/<name>/evals/evals.json` + `/skills/<name>/references/*.md`
+- `/validate-skills.sh`, `/validate-skills-official.sh`

research/superpowers.md

@@ -0,0 +1,110 @@
+# Research: `obra/superpowers`
+
+A single plugin/skills bundle that ships itself as a Claude Code plugin, a Codex plugin, a Cursor plugin, an OpenCode plugin, and a Gemini extension *simultaneously* by colocating every harness's manifest at the repo root.
+
+## Repo structure
+
+```
+.claude-plugin/      marketplace.json + plugin.json (Claude Code)
+.codex-plugin/       plugin.json (Codex App)
+.codex/              INSTALL.md (Codex CLI bootstrap docs)
+.cursor-plugin/      plugin.json (Cursor)
+.opencode/           INSTALL.md + plugins/superpowers.js (OpenCode)
+gemini-extension.json (Gemini CLI)
+agents/              code-reviewer.md
+commands/            brainstorm.md, execute-plan.md, write-plan.md
+hooks/               hooks.json, hooks-cursor.json, run-hook.cmd, session-start
+skills/              14 top-level SKILL.md folders (FLAT, not nested)
+docs/                handwritten markdown — README.codex.md, README.opencode.md, plans/, specs/
+scripts/             bump-version.sh, sync-to-codex-plugin.sh
+tests/               brainstorm-server, claude-code, codex-plugin-sync, opencode, skill-triggering, subagent-driven-dev
+assets/              icons, logos
+package.json, AGENTS.md, CLAUDE.md, GEMINI.md, RELEASE-NOTES.md
+```
+
+No `dist/`, no `plugins/` subdir, no nested skills. All skills live at `skills/<kebab-name>/SKILL.md` (14 of them). Skills can have sibling reference files or a `references/` subdir.
+
+## Plugin packaging — multi-harness, not multi-plugin
+
+The repo ships **one logical plugin packaged six ways**:
+
+- **Claude Code**: `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` (the marketplace declares a single plugin named `superpowers` with `"source": "./"`, so the repo *is* its own dev marketplace).
+- **Codex App**: `.codex-plugin/plugin.json` — much richer than the Claude one, includes an `interface` block (`displayName`, `shortDescription`, `defaultPrompt`, `brandColor`, `composerIcon`, `logo`, `category: "Coding"`).
+- **Cursor**: `.cursor-plugin/plugin.json` — declares `skills`, `agents`, `commands`, `hooks: ./hooks/hooks-cursor.json`.
+- **OpenCode**: `.opencode/plugins/superpowers.js` — a real JS module that injects bootstrap context via system-prompt transform and parses SKILL.md frontmatter at runtime.
+- **Codex CLI**: install via `git clone` + `ln -s skills ~/.agents/skills/superpowers` (no plugin manifest, uses native skill discovery).
+- **Gemini CLI**: `gemini-extension.json` with `contextFileName: "GEMINI.md"`.
+
+The **separate marketplace repo** `obra/superpowers-marketplace` is where themed grouping happens. Its `.claude-plugin/marketplace.json` lists 7 plugins by remote git URL: `superpowers`, `superpowers-chrome`, `elements-of-style`, `episodic-memory`, `superpowers-lab`, `superpowers-developing-for-claude-code`, `superpowers-dev`. Each entry is `{name, source: {source: "url", url}, description, version, strict: true}`. So the marketplace is a thin curation layer pointing at independent plugin repos — **no monorepo, no themed sub-plugins inside one repo**.
+
+## Build tooling
+
+`package.json` is minimal — just `name`, `version`, `type: "module"`, `main` pointing at the OpenCode plugin file. **No scripts, no dependencies, no build step, no TypeScript.** Manifests are handwritten and kept in sync by a custom version-bump tool.
+
+Two interesting scripts:
+
+1. **`scripts/bump-version.sh`** — driven by `.version-bump.json`, which lists every file containing a version field (`package.json`, `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json`, `.codex-plugin/plugin.json`, `.claude-plugin/marketplace.json` at `plugins.0.version`, `gemini-extension.json`). Has `--check` (drift detection) and `--audit` (greps repo for stale version strings). Pure bash + jq.
+
+2. **`scripts/sync-to-codex-plugin.sh`** — ~300-line bash tool that rsyncs the upstream tree into a fork (`prime-radiant-inc/openai-codex-plugins/plugins/superpowers/`), opens a PR via `gh`. Has `--dry-run`, `--bootstrap`, `--local`. Deterministic: same upstream SHA → identical PR diff. This is how the Codex App marketplace gets updated.
+
+## Installation story
+
+**No `npx` installer of its own.** Installation is per-harness:
+
+- Claude Code: `/plugin marketplace add obra/superpowers-marketplace` then `/plugin install superpowers@superpowers-marketplace`, OR Anthropic's official marketplace `/plugin install superpowers@claude-plugins-official`.
+- Codex App: search & install via in-app plugin UI.
+- Codex CLI: clone + symlink (manual).
+- Cursor: `/add-plugin superpowers`.
+- OpenCode: tell agent to fetch `INSTALL.md`.
+- Gemini: `gemini extensions install https://github.com/obra/superpowers`.
+- Copilot CLI: `copilot plugin marketplace add obra/superpowers-marketplace`.
+
+Vercel-labs/skills is **not mentioned anywhere**.
+
+## Docs site
+
+**There is no docs site.** No Docusaurus/Nextra/Astro/Starlight, no GitHub Pages (`has_pages: false`). `docs/` is a flat folder of handwritten markdown plus design specs dated YYYY-MM-DD. All discovery happens via the README plus per-harness INSTALL.md files.
+
+## CI / release
+
+`.github/` contains only `FUNDING.yml`, `ISSUE_TEMPLATE/`, and `PULL_REQUEST_TEMPLATE.md` — **no GitHub Actions workflows**. Releases appear to be manual: bump versions with the script, push tag, the marketplace repo points at git URLs (and `superpowers-dev` entry pins `ref: "dev"`).
+
+## SKILL.md format
+
+Frontmatter is intentionally minimal — only `name` and `description`:
+
+```yaml
+---
+name: test-driven-development
+description: Use when implementing any feature or bugfix, before writing implementation code
+---
+```
+
+Body uses heavy XML-style emphasis tags (`<EXTREMELY-IMPORTANT>`, `<SUBAGENT-STOP>`, `<important-reminder>`) and prescriptive uppercase rules. No tags, no allowed-tools, no version field per skill.
+
+## Distinctive patterns
+
+- **Bootstrap via SessionStart hook**: `hooks/hooks.json` registers a `SessionStart` (matchers `startup|clear|compact`) that runs `hooks/run-hook.cmd session-start`, which reads `skills/using-superpowers/SKILL.md` and injects it as additional system context — this is how skills "trigger automatically" without the user opting in.
+- **`using-superpowers` as meta-skill**: forces the agent to invoke the Skill tool *before any reply, including clarifying questions*.
+- **OpenCode runtime SKILL.md parser**: `.opencode/plugins/superpowers.js` reimplements frontmatter extraction inline ("avoid dependency on skills-core for bootstrap").
+- **Tests for skill triggering**: `tests/skill-triggering/`, `tests/codex-plugin-sync/`, `tests/opencode/` — actual integration tests for whether agents invoke the right skill.
+- **Multi-harness CLAUDE.md/AGENTS.md/GEMINI.md** at root, one per agent's convention.
+- **Spec-driven development** visible in `docs/superpowers/specs/`.
+
+## Implications for Matt's repo
+
+- **Multi-plugin themed marketplace**: superpowers' pattern is **separate plugin repos + one curation repo with `.claude-plugin/marketplace.json`** listing them by URL — *not* a monorepo. If Matt wants a monorepo, he'd be inventing a different pattern.
+- **Codex support**: cheapest path is `.codex-plugin/plugin.json` at root (Codex App) plus `.codex/INSTALL.md` for CLI clone+symlink. No build step needed.
+- **Docs site**: superpowers offers no precedent — Matt would be ahead of it.
+- **Build tooling**: superpowers proves you can run a popular skills plugin with **zero npm scripts** and just two bash scripts (version bump + cross-repo sync). The `.version-bump.json` config-driven approach is worth copying.
+- **SKILL.md conventions**: keep frontmatter to `name` + `description`; lean on body prose for behavior.
+
+## Key URLs
+
+- https://github.com/obra/superpowers/blob/main/.claude-plugin/marketplace.json
+- https://github.com/obra/superpowers/blob/main/.codex-plugin/plugin.json
+- https://github.com/obra/superpowers/blob/main/.opencode/plugins/superpowers.js
+- https://github.com/obra/superpowers/blob/main/scripts/bump-version.sh
+- https://github.com/obra/superpowers/blob/main/scripts/sync-to-codex-plugin.sh
+- https://github.com/obra/superpowers/blob/main/hooks/hooks.json
+- https://github.com/obra/superpowers-marketplace/blob/main/.claude-plugin/marketplace.json