docs: address cli-agent-skill-patterns gaps from issue #173 (pprose audit)

docs/project/research/current/research-agent-skills-standard-paths.md

@@ -134,6 +134,26 @@ No refreshed source changed the main recommendation: `.agents/skills/` should be
 portable project skill path, `.claude/skills/` should remain a Claude Code mirror, and
 `AGENTS.md` should remain a separate always-on instruction surface.
 
+### 2026-06-13 Refresh Notes (native per-agent skill dirs)
+
+A mid-2026 distribution audit
+([research-2026-06-13-skill-distribution-landscape.md](./research-2026-06-13-skill-distribution-landscape.md))
+found the ecosystem growing **native per-agent skill directories** alongside the
+portable `.agents/skills/`, which shifts two facts the guideline currently states:
+
+- **Cursor now scans `.agents/skills/` natively** (Cursor Agent Skills docs, verified
+  2026-06-13: native recursive discovery of `.agents/skills/` and `.cursor/skills/` plus
+  the `~/` user-level variants, including nested monorepo dirs, and compatibility
+  loading from `.claude/skills/` and `.codex/skills/`). The guideline’s older “Cursor
+  reaches `.agents/skills/` only via the skills.sh installer, not natively” is now
+  stale; it has been corrected to native (verified).
+- **Per-agent native dirs are multiplying** (community catalogs, directional): Cursor
+  `.cursor/skills/`, Copilot `.github/skills/`, Gemini `.gemini/skills/`, OpenCode
+  `.opencode/skills/`, Windsurf `.windsurf/skills/`, Google Antigravity
+  `.agent/skills/`. This does not change the recommendation (portable `.agents/skills/`
+  \+ Claude mirror), but it raises the value of letting the `npx skills add` installer
+  fan out per-agent mirrors rather than a tool writing each one.
+
 * * *
 
 ## Research Findings
@@ -180,7 +200,7 @@ project-local path. Native paths should be mirrors or compatibility targets.
 | --- | --- | --- | --- |
 | Claude Code | `.claude/skills/<name>/SKILL.md` | `~/.claude/skills/<name>/SKILL.md` | Official docs still center `.claude/skills/`. |
 | Codex | `.agents/skills/` from CWD through repo root (`SkillScope::Repo`) | `~/.agents/skills/` (`User`); admin; plugin roots; `$CODEX_HOME/skills` | **Source-verified** (not just docs): `codex-rs/core-skills/src/loader.rs` `repo_agents_skill_roots()` reads a bare repo-root `.agents/skills/` directly — no manifest. See 2026-05-26 note. |
-| Cursor | `.agents/skills/` per skills CLI support | `~/.cursor/skills/` | Changelog and best-practices docs support Agent Skills; path docs are thinner than Claude/Gemini. |
+| Cursor | `.agents/skills/` and `.cursor/skills/` (native recursive scan) | `~/.agents/skills/` and `~/.cursor/skills/` | **Docs-verified** (Cursor Agent Skills docs, 2026-06-13): native scan, plus compatibility loading from `.claude/skills/` and `.codex/skills/`. |
 | Gemini CLI | `.gemini/skills/` or `.agents/skills/` alias | `~/.gemini/skills/` or `~/.agents/skills/` alias | Official Gemini docs explicitly mention `.agents/skills` alias. |
 | GitHub Copilot | `.agents/skills/` per skills CLI support | `~/.copilot/skills/` | Included in Vercel skills supported-agent table. |
 | Amp | `.agents/skills/` per skills CLI support | `~/.config/agents/skills/` | Included in Vercel skills supported-agent table. |
@@ -192,16 +212,20 @@ Skills as capability packages.
 
 **Native scan vs. installer reach (be precise).** The `.agents/skills/` rows above mix
 two different mechanisms, and conflating them caused a downstream confusion (see
-2026-05-26 note):
-
-- **Scans repo-root `.agents/skills/` natively**: Codex (verified at source) and Gemini
-  CLI (documents the alias).
-  pi/OpenCode scan project Agent Skills dirs.
-- **Reached via the `npx skills add` installer**: for Cursor, Copilot, Cline, Amp,
-  Windsurf, the installer copies `SKILL.md` into `.agents/skills/` and **symlinks it
-  into each agent’s own dir** — the *installer* binds the path, not the agent.
-  “Works with Cursor/Copilot” means “via skills.sh”, not “Cursor scans `.agents/skills/`
-  itself.”
+2026-05-26 note). The bar for the first bucket is a **verified vendor-native scan**
+(source or vendor docs)—not mere presence in Vercel’s `skills` supported-agent table,
+which is evidence of installer reach, not proof a vendor’s own loader reads the path:
+
+- **Scans `.agents/skills/` natively (verified)**: Codex (verified at source), Gemini
+  CLI (documents the alias), and **Cursor** (Cursor Agent Skills docs, 2026-06-13:
+  native recursive scan of `.agents/skills/` and `.cursor/skills/`, plus
+  `.claude`/`.codex` compatibility loading).
+- **Reached via the `npx skills add` installer** (the *installer* binds the path, not
+  the agent): Copilot, Cline, Amp, Windsurf, OpenCode—the installer copies `SKILL.md`
+  into `.agents/skills/` and **symlinks it into each agent’s own dir**. “Works with
+  Copilot” means “via skills.sh,” not “Copilot scans `.agents/skills/` itself.”
+  Treat Vercel’s supported-agent table as installer-reach evidence only, not native
+  verification.
 - **Claude Code does not scan `.agents/` at all** — only `.claude/skills/` (confirmed;
   see claude-code#31005), which is why the mirror is mandatory.
 

docs/project/research/current/research-cli-as-agent-skill.md

@@ -1,6 +1,16 @@
 # Research Brief: CLI as Agent Skill - Best Practices for TypeScript CLIs in Claude Code
 
-**Last Updated**: 2026-05-24
+**Last Updated**: 2026-05-24 (addendum 2026-06-13)
+
+> **2026-06-13 addendum.** This brief is foundational but now lags the shipped guideline
+> (`cli-agent-skill-patterns`), which has since added the L0–L3 integration ladder,
+> format-versioned migration, and the §6.6.2 scope mechanics.
+> For the current distribution landscape (skills.sh leaderboard reality, the L2b
+> variant, dev-build pin selection, the `surface=` drop, multi-block collapse, and
+> native per-agent skill dirs), see
+> [research-2026-06-13-skill-distribution-landscape.md](./research-2026-06-13-skill-distribution-landscape.md)
+> and
+> [plan-2026-06-13-cli-skill-guideline-pprose-gaps.md](../../specs/active/plan-2026-06-13-cli-skill-guideline-pprose-gaps.md).
 
 **Related**:
 
@@ -195,7 +205,8 @@ letting agents use progressive disclosure.
 
 #### 1.3 Pinned CLI Invocation Fallbacks
 
-**Status**: Planned
+**Status**: ✅ Complete (shipped in guideline §6.7; generator-side rule open—see
+addendum)
 
 **Details**:
 
@@ -218,6 +229,18 @@ The pprose installer is a useful reference implementation: it injects a generate
 **Assessment**: tbd’s current guidance is too npm-global-specific.
 The guideline should teach pinned runner fallbacks as a supply-chain hardening pattern
 for all CLI-as-skill projects.
+(Shipped: guideline §6.7 now covers the consumer-side pinned `npx`/`uvx`/`pipx`/`go run`
+chain.)
+
+**2026-06-13 follow-up (generator-side pin selection).** A gap remains on the
+*generator* side: a tool installing from an editable/dev checkout has an unpublishable
+running version (`0.1.1.dev49+abc1234`, npm `0.0.0-dev.<sha>`) that `uvx pkg@<that>`
+cannot resolve, so the baked pin ships a broken skill.
+pprose solves it with a `DISCOVERY_VERSION` constant (last real PyPI release) gated by a
+PEP 440 release check `is_pypi_release` and a release-time guard (`install.py`
+L56/L96/L101–112). The rule: bake the running version only if it is a real, resolvable
+published release; otherwise fall back to a known-good published pin.
+This is issue #173 gap 3 — see the distribution-landscape brief.
 
 * * *
 

docs/project/research/current/research-skills-vs-meta-skill-architecture.md

@@ -42,6 +42,18 @@ The single tbd meta-skill should now be installed as a portable project skill at
 Code, and exposed as `skills/tbd/SKILL.md` for distribution.
 This keeps the meta-skill architecture while making the install path multi-agent.
 
+**2026-06-13 update**: Two corrections from the mid-2026 distribution audit
+([research-2026-06-13-skill-distribution-landscape.md](./research-2026-06-13-skill-distribution-landscape.md)).
+First, the “15K default limit” below is superseded: Claude Code now budgets the skill
+listing at roughly 1 percent of the model’s context window
+(`skillListingBudgetFraction`), truncating per-skill text at 1,536 characters, and drops
+least-recently-used descriptions on overflow.
+The meta-skill argument is unchanged and arguably stronger, since the budget is now a
+shared, contested pool.
+Second, the leaderboard supports the thesis directly: the single most-installed skill in
+the ecosystem is Vercel’s `find-skills` (a meta-skill that routes to other skills), and
+vendor knowledge skills dominate the top ranks over many-skill platforms.
+
 **Research Questions**:
 
 1. Should each tbd shortcut/guideline be a separate Claude Code skill?