get-tbd 0.2.2 → 0.3.0

package/dist/docs/guidelines/cli-agent-skill-patterns.md

@@ -2,12 +2,23 @@
 title: Agent Skills and CLI Integration Patterns
 description: How to write skills and agent-integrated CLIs that work across Claude Code, Codex, and the broader coding-agent ecosystem—a simple baseline plus references for advanced, multi-subcommand tools
 author: Joshua Levy (github.com/jlevy) with LLM assistance
+category: general
 ---
 # Agent Skills and CLI Integration Patterns
 
-**Last Updated**: 2026-05-31 (research verified against primary sources May 2026; added
-the L0–L3 integration ladder and §6.6.2 project-vs-global scope mechanics, informed by
-`qmd`)
+**Last Updated**: 2026-06-13 (issue #173: named the L2b variant—an L2 self-installer
+that also writes a managed `AGENTS.md` block, `pprose` reference—reframed
+format-versioning as artifact-driven rather than L3-only, added the §6.7 generator-side
+dev-build pin rule, dropped the redundant `surface=` tag from the marker examples, added
+multi-block collapse in §2, and refreshed §6.6 for Cursor’s native `.agents/skills/`
+scanning and the spread of native per-agent skill dirs.
+Earlier 2026-06-04: §4.6 adds the “attention routing” framing—the slopdocs vs.
+hiding-details failure modes—as a contained section, and the §3.1 mechanism callback
+points at it. Earlier 2026-06-02: §6.8 now covers Anthropic’s official and community
+plugin marketplaces—the reviewed, gated submission channel—and the `/plugin` install
+preview; verified against code.claude.com docs.
+Earlier 2026-05-31: research verified against primary sources, added the L0–L3
+integration ladder and §6.6.2 project-vs-global scope mechanics, informed by `qmd`)
 
 This guideline covers how to package a capability so AI coding agents can discover and
 use it well—from a single-file skill up to a full CLI with many subcommands exposed as a
@@ -22,12 +33,11 @@ should use—a prompt-only skill, a CLI tool, an MCP server, or a multi-agent
 integration—and you want it to work across Claude Code, Codex, Cursor, Gemini CLI, and
 others without rewriting it per agent.
 
-> **The single most important shift since 2025**: skills and project instructions are
-> now **open standards**, not per-vendor formats.
-> `AGENTS.md` is governed under the Linux Foundation’s **Agentic AI Foundation (AAIF)**;
-> the **Agent Skills (`SKILL.md`)** format is an open standard published at
-> [agentskills.io](https://agentskills.io) and implemented by 20+ agents.
-> Write to the standard once; most agents pick it up for free.
+Skills and project instructions are now **open standards**, not per-vendor formats.
+`AGENTS.md` is governed under the Linux Foundation’s **Agentic AI Foundation (AAIF)**;
+the **Agent Skills (`SKILL.md`)** format is an open standard published at
+[agentskills.io](https://agentskills.io) and implemented by 20+ agents.
+Write to the standard once; most agents pick it up for free.
 
 * * *
 
@@ -74,7 +84,7 @@ more—proof the baseline scales without custom tooling.
 manager:
 
 ```bash
-npx skills add owner/repo       # Vercel's skills.sh ecosystem (symlinks, 27+ agents)
+npx skills add owner/repo       # Vercel's skills.sh ecosystem (symlinks, 50+ agents)
 # or commit it to a discovery directory:
 #   .agents/skills/my-skill/SKILL.md   (cross-agent: Codex, pi, others)
 #   .claude/skills/my-skill/SKILL.md   (Claude Code, project)
@@ -123,9 +133,10 @@ So:
 - **Maximum reach across many agents** → layer them: AGENTS.md, SKILL.md, CLI, and MCP.
   (§1)
 - **Self-installs into agents?** → climb the integration ladder (§6.0): L0 pure skill →
-  L1 skill + pinned `npx`/`uvx` → L2 self-install into skill dirs only (`qmd`) → L3 full
-  platform with managed `AGENTS.md`, hooks, and format versioning (`tbd`). Most tools
-  are L1; stop as low as you can.
+  L1 skill and pinned `npx`/`uvx` → L2 self-install into skill dirs (`qmd`; its **L2b**
+  variant also writes a managed `AGENTS.md` block, `pprose`) → L3 full platform with
+  hooks, `prime`/`setup`, and format-versioned migration (`tbd`). Most tools are L1;
+  stop as low as you can.
 
 Everything below is reference material.
 You do not need most of it for most tools.
@@ -199,7 +210,7 @@ Version the managed block by carrying the format on the **begin marker line itse
 generated content without touching user-authored text:
 
 ```markdown
-<!-- BEGIN MYCLI INTEGRATION format=f02 surface=agents-md -->
+<!-- BEGIN MYCLI INTEGRATION format=f02 -->
 ## mycli
 
 - Run `mycli prime` for current project context.
@@ -212,6 +223,17 @@ Keep the begin/end marker *names* stable (`<!-- BEGIN MYCLI INTEGRATION`)—matc
 prefix so detection finds both legacy blocks (no `format=`, treated as `f01`) and
 current ones. Only the `format=fNN` value changes when the block’s shape changes.
 
+The marker carries only `format=fNN`. An artifact’s type is clear from its **location**
+(a `SKILL.md` under a skill dir, or this BEGIN/END block in `AGENTS.md`), so no in-file
+`surface=` tag is needed, and the portable and Claude `SKILL.md` copies stay
+byte-identical.
+On install, if several managed blocks have accumulated (for example after
+a marker-prefix rename across versions), collapse them: replace every matching block
+with one current block at the position of the first, and preserve everything outside the
+markers.
+Collapse only finds blocks whose begin-prefix the installer recognizes, so match
+a small set of known legacy prefixes, not just the current one.
+
 * * *
 
 ## 3. The Agent Skills Standard (SKILL.md)
@@ -253,6 +275,9 @@ The body names the capability and the command; the agent runs that command’s `
 `--list` when it needs the mechanics.
 This is progressive disclosure applied to a CLI: the tool documents itself, and the
 skill stays a thin pointer to it.
+This is *attention routing* (§4.6) in mechanism form: each level keeps the agent aware
+that more detail exists and routes to it, without pulling the detail itself up into
+context before it is needed.
 
 ### 3.2 Bundled scripts and resources
 
@@ -381,6 +406,32 @@ it:
 - **Deprecation**: when removing or renaming a skill, leave a deprecation window with a
   pointer to the replacement; don’t silently delete an activation trigger users rely on.
 
+### 4.6 Attention routing—the idea behind this guide
+
+Everything above is in service of one idea.
+Route the agent’s attention through a pyramid of pointers: surface enough context around
+each pointer to show what is relevant, pull detail up only where it helps, and keep the
+upper levels lean.
+The judgment at every step is **how much to copy into the skill versus
+leave behind a link to the CLI**—which is why rules like **route, don’t restate** (§6.5)
+and **the skill points; the CLI documents** (§0.2) exist.
+There are two opposite failure modes:
+
+- **Slopdocs** (*copying too much, or unthinkingly*)—help text, flag tables, and recipes
+  copied into the skill with no judgment about what level or form belongs where.
+  Deliberate, consistent copying is fine—the multi-agent mirror in §6.6 is exactly
+  that—but thoughtless copying bloats context and dilutes attention, and breeds
+  maintenance burden and inconsistencies that drift into real errors.
+- **Hiding details** (*copying too little, or hiding details behind links too
+  dogmatically*)—pointing at the CLI or a reference without enough context to convey
+  what is there or why to look, so the agent never learns the capability is relevant.
+  Fix: pull up just enough—name each capability and the command that reaches it—so the
+  link is worth following.
+
+Push the *mechanics* (flags, recipes) down into help pages or docs, but keep enough
+*awareness* and *detail* up in the skill—each key capability described once, with the
+command that reaches it—so the agent knows whether a pointer is worth following.
+
 * * *
 
 ## 5. Per-Agent Integration Reference
@@ -471,7 +522,7 @@ Four rungs, lightest first:
   install command. The agent follows the body directly.
   Garry Tan’s **gstack** (23 plain skills) is L0. Install by committing to a discovery
   dir or `npx skills add`.
-- **L1—skill + delegated CLI (zero-install).** Ship a `SKILL.md` that points at a CLI
+- **L1—skill and delegated CLI (zero-install).** Ship a `SKILL.md` that points at a CLI
   invoked through a **version-pinned** zero-install runner—`npx --yes pkg@<ver>`,
   `uvx --from pkg@<ver>`, or `pipx run pkg==<ver>` (§6.7). No install command, no
   managed `AGENTS.md` block, no hooks, no format versioning.
@@ -490,26 +541,42 @@ Four rungs, lightest first:
   and **stops there**: no managed `AGENTS.md` block, no hooks, no `prime`/`setup`
   context machinery. Because it never touches a human-authored project-instruction file
   and always full-overwrites its own generated skill, it does **not** need the §6.6
-  format-version / migration apparatus—a re-install is just a clean overwrite.
-  **`qmd`** (Tobi Lütke’s Markdown search tool) is the reference: `qmd skill install` /
-  `--global`, an embedded skill with a build-time drift test, a
+  format-version and migration apparatus—a re-install is just a clean overwrite.
+  **`qmd`** (Tobi Lütke’s Markdown search tool) is the reference: `qmd skill install`
+  and `--global`, an embedded skill with a build-time drift test, a
   `.claude-plugin/marketplace.json`, and an MCP server—all without writing to
-  `AGENTS.md` at all.
+  `AGENTS.md` at all. One useful variant sits between L2 and L3—call it **L2b**: an L2
+  self-installer that *also* writes a compact managed `AGENTS.md` block (an always-on
+  bootstrap naming the tool, its trigger, and the pinned runner), but still no hooks,
+  `prime`/`setup`, or DocCache.
+  That block is the one L3 surface a small tool can adopt on its own; because it is
+  merged into a human-authored file rather than overwritten whole, an L2b tool **does**
+  need the §6.6 format-stamp and forward-compatibility guard.
+  **`pprose`** (Practical Prose) is the reference, writing `.agents/skills/`, the
+  `.claude/skills/` mirror, and a `format=fNN`-stamped `AGENTS.md` block with the same
+  refuse-to-clobber-newer guard `tbd` uses.
 - **L3—full self-installing CLI platform.** Everything in L2 **plus** a managed
   `AGENTS.md` block, lifecycle hooks (`SessionStart`/`PreCompact`), `prime` and `setup`
-  commands, format-versioned migration with a forward-compatibility guard (§6.6), and
-  usually a knowledge-injection meta-skill (§6.2) backed by a path-ordered DocCache
-  (§6.3). Take this on only for a tool with many capabilities, cross-session state, or a
-  curated knowledge library.
-  **`tbd`** is the reference implementation; **Beads/`bd`** follows the same shape.
-  Such platforms are typically **project-only and version-pinned per repo** (§6.6.2):
-  the tool is part of the project’s reproducible toolchain, so global scope is usually
-  not worth offering. `qmd` (L2) offers global/dual scope precisely because it is a
-  general-purpose utility that carries no per-project config.
-
-The self-upgrade and format-versioning rules in §6.6 apply **only to L3**—L0–L2 never
-need them. If in doubt, you are L1: `tbd` is an L3 reference implementation, `qmd` an L2
-one, and most CLIs are neither.
+  commands, format-versioned migration across every managed surface (§6.6), and usually
+  a knowledge-injection meta-skill (§6.2) backed by a path-ordered DocCache (§6.3). Take
+  this on only for a tool with many capabilities, cross-session state, or a curated
+  knowledge library. **`tbd`** is the reference implementation; **Beads/`bd`** follows
+  the same shape. Such platforms are typically **project-only and version-pinned per
+  repo** (§6.6.2): the tool is part of the project’s reproducible toolchain, so global
+  scope is usually not worth offering.
+  `qmd` (L2) offers global/dual scope precisely because it is a general-purpose utility
+  that carries no per-project config.
+
+Format-versioning is **artifact-driven, not rung-driven**: the §6.6 format-stamp and
+forward-compatibility guard apply to **any rung that writes a generated artifact it may
+later need to upgrade or refuse to clobber**—in practice a managed `AGENTS.md` block
+(the L2b variant, or L3) or a committed generated skill shared across tool versions.
+A tool that only overwrites its own discovery-dir skill whole (plain L0–L2) never needs
+them.
+What stays strictly L3 is the rest of the platform: hooks, `prime`/`setup`, and the
+meta-skill/DocCache machinery.
+If in doubt, you are L1: `tbd` is an L3 reference implementation, `pprose` the L2b
+variant, `qmd` a plain L2 one, and most CLIs are none of these.
 
 ### 6.1 Two kinds of commands
 
@@ -590,7 +657,7 @@ Rules: reference commands **explicitly** (`mycli command arg`, never “see the
 - **`--json` on every command**—one output path that renders human or machine output.
 - **`--brief`/`--quiet`** for constrained contexts and scripts.
 - **Idempotent `setup --auto`** (non-interactive) vs.
-  `setup --interactive` for humans; never let an agent get stuck on a prompt.
+  a guided setup for humans; never let an agent get stuck on a prompt.
 - **Actionable errors** that include the next command to run.
 - **Discoverable help**: an `IMPORTANT:` epilog pointing at a context-restore command
   (e.g., `mycli prime`), and a “Getting Started” one-liner.
@@ -637,17 +704,25 @@ only where a target agent requires it:
 - `.agents/skills/<tool>/SKILL.md`—the portable project skill.
   **Be precise about who reads this path natively vs.
   who reaches it via an installer**, rather than claiming a flat “all agents read it”:
-  - **Scans repo-root `.agents/skills/` natively** (verified): **Codex** (source above)
-    and **Gemini CLI** (documents `.agents/skills/` as a workspace/user alias).
-    **pi** / **OpenCode** scan project Agent Skills dirs.
+  - **Scans repo-root `.agents/skills/` natively** (verified): **Codex** (source above),
+    **Cursor** (its Agent Skills docs list `.agents/skills/`, `.cursor/skills/`, and the
+    `~/` global variants, plus `.claude/skills/` and `.codex/skills/` for
+    compatibility), and **Gemini CLI** (documents `.agents/skills/` as a workspace/user
+    alias). **pi** and **OpenCode** scan project Agent Skills dirs.
   - **Reached via the cross-agent installer**: `npx skills add` copies the same
     `SKILL.md` into `.agents/skills/` and **symlinks it into each agent’s own dir**
-    (Cursor, Copilot, Cline, Amp, Windsurf, …). For those agents the *installer*, not
-    the agent, is what binds `.agents/skills/` to their native location—so “works with
-    Cursor/Copilot/…” means “via skills.sh”, not “Cursor scans `.agents/skills/`
-    itself.”
+    (Copilot, Cline, Amp, Windsurf, …). For an agent that does not scan
+    `.agents/skills/` itself, the *installer*, not the agent, binds it to that agent’s
+    native location, so “works with Copilot/…” means “via skills.sh”, not “the agent
+    scans `.agents/skills/` itself.”
   - **Claude Code does NOT scan `.agents/`** at all—it reads only `.claude/skills/`
     (next bullet), which is why the mirror is required, not optional.
+  - **Native per-agent skill dirs are multiplying** (community catalogs, mid-2026;
+    verify per agent): beyond `.claude/skills/`, agents document their own dirs such as
+    `.cursor/skills/`, `.github/skills/` (Copilot), `.gemini/skills/`,
+    `.opencode/skills/`, `.windsurf/skills/`, and `.agent/skills/` (Google Antigravity).
+    Emitting only the portable `.agents/skills/` and the Claude mirror and letting
+    `npx skills add` fan out the rest scales better than writing each one.
   - When in doubt, verify against the agent’s source/docs before asserting native
     scanning.
 - `.claude/skills/<tool>/SKILL.md`—Claude Code compatibility mirror (required: Claude
@@ -661,7 +736,7 @@ tbd should write a CLI-managed `SKILL.md` to `.agents/skills/tbd/`, mirror it to
 also feeds Cursor, Codex, and Factory), preserving user content outside the markers:
 
 ```markdown
-<!-- BEGIN MYCLI INTEGRATION format=f02 surface=agents-md -->
+<!-- BEGIN MYCLI INTEGRATION format=f02 -->
 ## mycli
 
 - Run `mycli prime` for current project context.
@@ -738,10 +813,14 @@ Do not make Codex hooks call scripts stored under `.claude/`—that couples Code
 Claude setup. If a script must move out of `.claude/scripts/`, update the tbd-owned hook
 commands (or leave a wrapper) so existing Claude hooks keep working.
 
-**Upgrade existing installs deliberately (L3 only).** A self-installing tool whose skill
-content evolves *will* leave older generated files in users’ repos.
-(An L2 tool that only writes discovery-dir skills can skip all of this: a re-install is
-a clean full overwrite, with no managed `AGENTS.md` block or hooks to migrate.)
+**Upgrade managed generated artifacts deliberately.** A self-installing tool whose
+generated content evolves *will* leave older artifacts in users’ repos.
+(A tool that only writes fully-overwritten discovery-dir skills—plain L2 or below—can
+skip all of this: a re-install is a clean full overwrite, with no managed `AGENTS.md`
+block or hooks to migrate.
+The L2b variant, which merges a managed `AGENTS.md` block into a human-authored file,
+**does** need the format stamp and forward-compatibility guard even though it is not
+L3—this is the artifact-driven rule from §6.0, not an L3-only one.)
 Treat generated integration files like config migrations:
 
 Reserve an `fNN` **format bump** for changes big enough to need an explicit migration: a
@@ -783,7 +862,8 @@ it; it does not license the tool to mutate the repo on its own.
   `AGENTS.md` block, generated skills, tool-owned hooks, `.codex/` config), re-running
   cleanly with no change when already current.
 - Treat old marked `AGENTS.md` blocks with no metadata as legacy generated content and
-  replace only the managed region.
+  replace only the managed region, collapsing any duplicate stale blocks to one current
+  block at the first block’s position (§2).
 - Detect tool-owned hook entries by command/path/signature, replace only those entries,
   and preserve unrelated user hooks.
 - **Forward-compatibility guard.** When the tool finds a generated artifact whose
@@ -1030,6 +1110,20 @@ This is a supply-chain control, not just ergonomics: an unpinned runner re-resol
 the latest published version on every run and bypasses any cool-off window.
 See `tbd guidelines supply-chain-hardening` for the cross-ecosystem policy.
 
+**Bake a pin the generator can actually resolve.** The rules above are consumer-side:
+they assume the generating tool can pin to its own running version.
+A tool installing from an editable or dev checkout cannot.
+Its running version is an unpublished dev, pre-release, or local build
+(`0.1.1.dev49+abc1234`, npm `0.0.0-dev.<sha>` or `x.y.z-canary`) that `uvx pkg@<that>`
+or `npx pkg@<that>` will never resolve, so baking it ships a skill that fails the moment
+a teammate runs it—one works-on-my-machine install poisons the clone.
+Bake the running version only when it is a real, resolvable published release; otherwise
+fall back to a known-good published pin.
+`pprose` does this with a `DISCOVERY_VERSION` constant (its last real PyPI release)
+gated by a PEP 440 release check (`is_pypi_release`), and enforces at release time that
+the constant equals the release tag.
+This is the generator-side mirror of the consumer-side pin rule.
+
 **Current tooling (May 2026)**
 
 - **Node / TypeScript**: zero-install via `npx <pkg>@<ver>` (`-y` to skip the prompt),
@@ -1056,9 +1150,12 @@ environments where the project wants lockfile-managed versions and warm-start sp
 
 ### 6.8 Publishing and discovery—make the skill installable
 
-Most “skill registries” (May 2026) are **GitHub-repo discoverers, not gated app
-stores**. You don’t submit a form; you put a spec-compliant `SKILL.md` in a public repo
+Most “skill registries” (mid-2026) are **GitHub-repo discoverers, not gated app
+stores**: you don’t submit a form, you put a spec-compliant `SKILL.md` in a public repo
 and the ecosystem finds it.
+The exception is **Anthropic’s own plugin marketplaces**, which *are* a reviewed,
+curated channel with a real submission and security-screening flow (below)—so the
+landscape is now a spectrum from passive scrapers to a gated store, not one shape.
 The landscape worth targeting:
 
 - **`skills.sh` / `npx skills add <owner/repo>`** (Vercel)—the cross-agent “npm for
@@ -1068,16 +1165,59 @@ The landscape worth targeting:
 - **GitHub-scraping indexers** (SkillsMP ~800k skills, ClaudeSkills.info, LobeHub,
   claudemarketplaces.com)—auto-list public repos that contain a `SKILL.md` (often gated
   on ≥2 stars). You get listed for free just by being public and discoverable.
-- **Plugin marketplaces**—`.claude-plugin/marketplace.json` (Claude Code, the official
-  Anthropic channel) and `.agents/plugins/marketplace.json` (Codex; Codex reads both).
+- **Self-hosted plugin marketplaces**—`.claude-plugin/marketplace.json` (Claude Code)
+  and `.agents/plugins/marketplace.json` (Codex; Codex reads both).
   These are *plugin* channels: bundles of skills, MCP servers, hooks, and commands.
   They are **only for publishing a bundle**—a repo-local skill already loads from
   `.claude/skills/` (Claude Code) and `.agents/skills/` (Codex) **without any
   manifest**, so don’t add one just to be discovered.
+  Users add yours with `/plugin marketplace add <owner/repo>` and install with
+  `/plugin install <name>@<marketplace>`; it is not centrally indexed unless you also
+  list on the community marketplace (next bullet).
   If you *do* emit a `marketplace.json` / `.codex-plugin/plugin.json`, treat it like any
   generated artifact (§6.6): point it at the same generated `SKILL.md` payload (no body
   duplication), mark it `DO NOT EDIT`, make it deterministic so re-install is a no-op,
   and pick the same commit-vs-gitignore mode as the skill it references.
+- **Anthropic’s official and community marketplaces**—the one genuinely *gated* channel,
+  and the only place a third party gets a reviewed, security-scanned listing.
+  Two catalogs ship with Claude Code:
+  - **`claude-plugins-official`**—auto-available in every session (catalog at
+    `claude.com/plugins`); curated by Anthropic, inclusion **at its discretion, not
+    self-serve**. Install: `/plugin install <name>@claude-plugins-official`.
+  - **`anthropics/claude-plugins-community`** (install name `claude-community`)—a
+    **read-only nightly mirror of Anthropic’s internal review pipeline**. Third-party
+    plugins that pass **automated validation + security screening** get listed, each
+    **pinned to a commit SHA**. Users add it manually
+    (`/plugin marketplace add anthropics/claude-plugins-community`) then
+    `/plugin install <name>@claude-community`. **Submitting**: do *not* open a PR
+    against the repo—they are auto-closed.
+    Submit through the in-app form / `clau.de/plugin-directory-submission` and let the
+    scan and approval run (the in-app forms feed the *community* marketplace, never the
+    official one). This is the channel that buys **trust and discoverability inside
+    Claude Code**: current `/plugin` install views show a **Context cost** estimate
+    (per-turn token cost; v2.1.143+), a **Last updated** date (v2.1.144+), and a **Will
+    install** breakdown (commands, agents, skills, hooks, MCP/LSP; v2.1.145+) before the
+    user commits—best-in-class informed consent.
+    Worth it for a tool you want broadly adopted; still optional, since a repo-local
+    skill loads with none of it.
+
+**Channels at a glance** (generic; verify specifics against current docs—this space
+moves fast). The rows run from lowest effort/reach to highest trust, and they
+**compose**: a single public repo can satisfy every row at once.
+
+| Channel | User install | Discovery & reach | Trust & security | Versioning | Publish / submit |
+| --- | --- | --- | --- | --- | --- |
+| **Documented install** (README + optional installer) | A few manual steps, or one command if you ship `mytool install` | None beyond the repo’s own stars/SEO | Fully manual—user reads the source before running | Whatever your docs pin; manual re-pull | Push the repo and write the README |
+| **`npx skills add`** (skills.sh, Vercel) | `npx skills add <owner/repo>`—one command, 50+ agents, symlink or copy | High and **cross-agent**; `npx skills find`, ranked by install telemetry | Runs the `skills` CLI + your repo; review the `SKILL.md`, pin to a ref | Tracks the repo/ref; `npx skills update`; no semver | Put `skills/<name>/SKILL.md` in a public repo—auto-works. [skills.sh](https://skills.sh) · [vercel-labs/skills](https://github.com/vercel-labs/skills) |
+| **GitHub-scraping indexers** (SkillsMP, claudemarketplaces, LobeHub…) | They hand you one of the other commands | Highest *passive* top-of-funnel; free; often gated on ≥2 stars | Mostly unvetted link directories; you don’t control the listing | Inherits the underlying method | Automatic once public—no action. e.g. [claudemarketplaces.com](https://claudemarketplaces.com) |
+| **Self-hosted plugin marketplace** (Claude Code / Codex) | `/plugin marketplace add <owner/repo>`, then `/plugin install <name>@<mp>` (or the `/plugin` UI) | Inside Claude Code once added; **not** centrally indexed | Your repo’s trust only; install preview shows exactly what loads | **Best**—`version` field + SHA pin + auto-update toggle | Add `.claude-plugin/marketplace.json`. [Docs](https://code.claude.com/docs/en/plugin-marketplaces) |
+| **Anthropic official / community marketplace** | Official: auto-available (`<name>@claude-plugins-official`). Community: add `anthropics/claude-plugins-community`, then `<name>@claude-community` | Highest inside Claude Code (Discover tab, `claude.com/plugins`) | **Best**—reviewed, security-screened, SHA-pinned, install preview | SHA-pinned in the catalog; nightly-mirror updates | Official: not self-serve (Anthropic’s discretion). Community: submit at [clau.de/plugin-directory-submission](https://clau.de/plugin-directory-submission) (no PRs—auto-closed). [Docs](https://code.claude.com/docs/en/discover-plugins) |
+
+**Takeaway**: for broad cross-agent reach at near-zero effort, ship a valid `SKILL.md`
+and lean on `npx skills add` plus the scrapers; for the highest trust and
+discoverability *inside Claude Code*, additionally submit to the community marketplace.
+Reserve a self-hosted marketplace for a private/team channel or to bundle hooks, agents,
+and MCP servers alongside the skill.
 
 **The simplest publishable structure** (works for all of the above at once):
 
@@ -1263,7 +1403,9 @@ going:
 - Route, don’t restate: name each capability and the command to run; let the CLI’s
   `--help` and informational subcommands hold the flags and recipes.
   Carry the focused context an agent needs to judge that the tool is relevant, but don’t
-  blindly copy help into the skill; that wastes context and goes stale (§3.1, §6.5).
+  blindly copy help into the skill; that wastes context and goes stale (§3.1, §6.5). The
+  two failure modes: **slopdocs** (copying too much or unthinkingly) and **hiding
+  details** (copying too little—content hidden behind links the agent won’t follow).
 - Respect the budget; verify the current model for your target agent (Claude Code ≈ 1%
   of context window, not a flat char count).
 
@@ -1274,6 +1416,10 @@ going:
   This is tbd’s validated approach.
 - Path-ordered resource cache for project/user shadowing; generate `--list` dynamically.
 - Context-injection loop with explicit `cli command arg` references; depth ≤ 3.
+- Self-installing tools climb the §6.0 ladder and stop at the lowest rung.
+  A managed `AGENTS.md` block (the L2b variant) is the one L3 surface worth adopting
+  alone, but any rung that writes one must format-stamp it and refuse to clobber a newer
+  block.
 
 **Reach and surface**
 
@@ -1290,6 +1436,8 @@ going:
 - Scope `allowed-tools` tightly; gate destructive skills; design for sandboxes.
 - Idempotent multi-agent install with marker-bounded sections; version source files, not
   fully generated install artifacts; mark generated files “DO NOT EDIT.”
+- Pin a generated runner to a resolvable published release; never bake a dev or
+  pre-release version a teammate’s `uvx`/`npx` cannot resolve (§6.7).
 
 * * *
 
@@ -1301,6 +1449,9 @@ going:
 - [ ] Body carries the essential context to judge whether the tool is relevant and to
   name each key use case, but routes to `mycli <cmd> --help` or `--list` for flags and
   recipes instead of copying help wholesale
+- [ ] No **slopdocs** (help, flags, or recipes copied in unthinkingly) and no **hiding
+  details** (capabilities behind bare links with too little context to show they are
+  worth following)
 - [ ] Third-person description, trigger keywords front-loaded
 - [ ] Installable via commit to `.agents/skills/`, Claude mirror at `.claude/skills/`,
   and/or `npx skills add`
@@ -1309,16 +1460,26 @@ going:
 - [ ] `AGENTS.md` with build/test/style/conventions (concise)
 - [ ] Managed `AGENTS.md` block uses a stable begin/end marker with a `format=fNN` field
   on the begin line
+- [ ] Marker carries only `format=fNN` (artifact type is clear from location, no
+  `surface=` tag); duplicate stale blocks collapsed to one on install (the L2b variant
+  and L3)
 - [ ] `CLAUDE.md` strategy decided (symlink to `AGENTS.md`, copy, or separate)
 
 **CLI tool (if applicable)**
 - [ ] `--json` on all commands; `--brief`/`--quiet`; actionable errors
+
 - [ ] Idempotent `setup --auto`; `init` for surgical config
+
 - [ ] Help epilog with `IMPORTANT:` + Getting Started one-liner
+
 - [ ] `prime` (status/context) and `skill` (pure docs) commands
+
 - [ ] Invocation strategy chosen (§6.7): local-first plus pinned zero-install fallback
   by default, or global install + `SessionStart` bootstrap for cloud/ephemeral agents
 
+- [ ] Generated skill bakes a resolvable published pin, not the running dev or
+  pre-release version (§6.7)
+
 **Advanced (many subcommands / knowledge library)**
 - [ ] Meta-skill composition (header + baseline + dynamic directory)
 - [ ] Informational commands (`guidelines`/`shortcut`/`template`) with `--list`
@@ -1394,10 +1555,25 @@ going:
   https://vercel.com/changelog/introducing-skills-the-open-agent-skills-ecosystem
 - npx skills: https://github.com/vercel-labs/skills
 - Anthropic skills (examples): https://github.com/anthropics/skills
+- Discover and install plugins (official + community marketplaces, `/plugin` install
+  preview): https://code.claude.com/docs/en/discover-plugins
+- Create and distribute a plugin marketplace:
+  https://code.claude.com/docs/en/plugin-marketplaces
+- Community marketplace + submission flow:
+  https://github.com/anthropics/claude-plugins-community (submit via
+  https://clau.de/plugin-directory-submission)
 - gstack: https://github.com/garrytan/gstack
 - Beads (bd): https://github.com/gastownhall/beads
-- qmd (L2 reference: self-installing skill, discovery-dirs only, CLI + MCP + plugin):
+- qmd (L2 reference: self-installing skill, discovery-dirs only, CLI, MCP, and plugin):
   https://github.com/tobi/qmd
+- pprose (L2b variant reference: self-installing skill plus a format-stamped,
+  marker-bounded `AGENTS.md` block, no hooks/prime/setup):
+  https://github.com/jlevy/practical-prose
+- taste-skill (L0 reference: pure-prompt skill collection distributed via skills.sh, a
+  Claude plugin marketplace, `copilot-instructions.md`, and `llms.txt`):
+  https://github.com/Leonxlnx/taste-skill
+- anthropics/skills (L0 reference: skill collection bundled as Claude plugins):
+  https://github.com/anthropics/skills
 
 ### Security
 

package/dist/docs/guidelines/commit-conventions.md

@@ -2,6 +2,7 @@
 title: Commit Conventions
 description: Conventional Commits format with extensions for agentic workflows
 author: Joshua Levy (github.com/jlevy) with LLM assistance
+category: general
 ---
 # Commit Conventions
 

package/dist/docs/guidelines/common-doc-guidelines.md

@@ -2,6 +2,7 @@
 title: Common Documentation Guidelines
 description: Common cross-project standards for writing and organizing docs, code comments, and text files—how to organize, structure, write, and format documents, plus the guideline footer convention. Downstream of github.com/jlevy/practical-prose. Use whenever writing or editing any documentation, README, guideline, or design doc.
 author: Joshua Levy (github.com/jlevy) with LLM assistance
+category: general
 ---
 # Common Documentation Guidelines
 

package/dist/docs/guidelines/convex-limits-best-practices.md

@@ -2,6 +2,7 @@
 title: Convex Limits and Best Practices
 description: Comprehensive reference for Convex platform limits, workarounds, and performance best practices
 author: Joshua Levy (github.com/jlevy) with LLM assistance
+category: convex
 ---
 # Research Brief: Convex Database Limits, Best Practices, and Workarounds
 

package/dist/docs/guidelines/convex-rules.md

@@ -2,6 +2,7 @@
 title: Convex Rules
 description: Guidelines and best practices for building Convex projects, including database schema design, queries, mutations, and real-world examples
 author: Convex team
+category: convex
 ---
 # Convex Guidelines
 

package/dist/docs/guidelines/electron-app-development-patterns.md

@@ -1,6 +1,7 @@
 ---
 title: Electron App Development Patterns
 description: Guidelines for Electron development ecosystems including npm, pnpm, and Bun, with security baselines and framework comparisons
+category: electron
 ---
 # Electron App Development Patterns
 

package/dist/docs/guidelines/error-handling-rules.md

@@ -2,6 +2,7 @@
 title: Error Handling Rules
 description: Rules for handling errors, failures, and exceptional conditions
 author: Joshua Levy (github.com/jlevy) with LLM assistance
+category: general
 ---
 # Error Handling Rules
 
@@ -131,6 +132,9 @@ For every operation that can fail:
 Failure tests are harder to write but catch the bugs that matter most—the ones where the
 system lies about its state.
 
+See `general-testing-rules` and `general-tdd-guidelines` for the broader testing
+approach.
+
 ### Principle 8: Classify Errors as Transient or Permanent
 
 Not all errors are equal.

package/dist/docs/guidelines/general-coding-rules.md

@@ -2,6 +2,7 @@
 title: General Coding Rules
 description: Rules for constants, magic numbers, and general coding practices
 author: Joshua Levy (github.com/jlevy) with LLM assistance
+category: general
 ---
 # General Coding Rules
 
@@ -14,7 +15,8 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
   their purpose.
 
 - Constants should be defined in appropriate settings files (e.g., `settings.ts`) for
-  easy maintenance.
+  easy maintenance. Do not restate a constant’s value in a comment; see
+  `general-comment-rules`.
 
   ```typescript
   // BAD: Hardcoded numbers

package/dist/docs/guidelines/general-comment-rules.md

@@ -2,6 +2,7 @@
 title: General Comment Rules
 description: Language-agnostic rules for writing clean, maintainable comments
 author: Joshua Levy (github.com/jlevy) with LLM assistance
+category: general
 ---
 # General Comment Rules
 
@@ -93,7 +94,8 @@ These are language-agnostic rules on comments:
   prefer `/** ... */` comments wherever appropriate on variables, functions, methods,
   and at the top of files.
 
-- See language-specific comment rules for more details.
+- See language-specific comment rules for more details, e.g. `typescript-rules` or
+  `python-rules`.
 
 <!-- This document follows common-doc-guidelines.md.
 See github.com/jlevy/practical-prose and review guidelines before editing.