fix(playbooks): boris/vendor/SKILL.md collides with boris/SKILL.md and carries a 5,484-char description (3.6x the listing cap)

[kyle-sexton]

Summary

plugins/playbooks/skills/boris/ contains two SKILL.md files that both resolve to the skill name boris, and the nested one carries by far the largest description in the entire marketplace.

Evidence

plugins/playbooks/skills/boris/SKILL.md          <- no `name:` field; falls back to dir name "boris"
plugins/playbooks/skills/boris/vendor/SKILL.md   <- frontmatter `name: boris`

boris/vendor/ contains nothing but SKILL.md — no scripts, no reference files. It reads as a vendored copy of the upstream skill that was committed alongside the adapted one.

Collision. Per Extend Claude with skills, a plugin skill's command name comes from the frontmatter name field, and a personal/project skill's from its directory. Both files here land on boris. Which definition wins follows directory-read order, so it can differ between machines.

Size. The vendored file's description is a YAML block scalar measuring 5,484 characters:

	chars
boris/vendor/SKILL.md description	5,484
Claude Code listing cap per entry (skillListingMaxDescChars default)	1,536
Agent Skills spec max for description	1,024
Marketplace mean	752

It is the only skill in the fleet over the 1,536-char listing cap, and it is 3.6x over it. It is also 5.4x the 1,024-char maximum the Agent Skills spec states for the field ("description: Must be non-empty, Maximum 1,024 characters").

The description also contains PROACTIVE MODE / BROWSE MODE behavioral instructions. Those are body content — the description field is metadata used for selection, and it is truncated in the listing anyway, so instructions placed there may never reach the model intact.

Proposed fix

Delete plugins/playbooks/skills/boris/vendor/. The adapted boris/SKILL.md already has a proper description + when_to_use pair (a combined ~200 chars) and is the one intended to ship.

If the vendored copy must be retained for provenance, move it out of the skills/ tree entirely (for example plugins/playbooks/reference/boris-upstream.md) so it is not discovered as a skill.

Acceptance criteria

• Exactly one SKILL.md resolves to the name boris within the playbooks plugin.
• No SKILL.md under any skills/ directory has a description over 1,024 chars.
• claude plugin validate plugins/playbooks reports no name collisions.

Related

Part of the fleet-wide listing-budget problem in #3505, but independently actionable and much smaller.

Sources

• https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices (frontmatter limits)
• https://code.claude.com/docs/en/skills (skillListingMaxDescChars, skill name resolution)

[kyle-sexton]

Closing as invalid — I was wrong, and acting on this would have broken drift detection.

Three claims in this issue do not survive checking against the repo's own conventions.

1. vendor/SKILL.md is a deliberate convention, not a stray committed copy.

plugins/*/skills/*/vendor/SKILL.md is an established pattern with explicit governance:

• docs/topics/context-engineering-claude-5/design/skill-inventory.md:12 names plugins/*/skills/*/vendor/SKILL.md as "hand-edit-prohibited".
• docs/PLUGIN-PHILOSOPHY.md:225 describes the boris one specifically as "a verbatim upstream baseline kept for drift detection, which is why it is deliberately not hand-edited here."
• plugins/claude-config/skills/audit-permission-grants/scripts/permission-rule-check.test.sh:248 asserts the permission checker "does NOT flag vendored direct-child SKILL.md" — the pattern is explicitly whitelisted in tooling.
• The same pattern exists for playwright/skills/playwright/vendor/, context7/skills/lookup/vendor/, and playbooks/skills/skill-authoring/vendor/. It is a fleet-wide convention.
• /playbooks:update refreshes this baseline; deleting it would break that refresh and the drift detection it feeds.

2. There is no name collision. Claude Code discovers skills at skills/<name>/SKILL.md — direct children only. skills/boris/vendor/SKILL.md is one level deeper and is never discovered. Verified against a live session's skill listing on a machine with the full fleet enabled: playbooks:boris appears exactly once, and no vendor entry appears at all. The two files cannot collide because only one is ever loaded.

3. The 5,484-char description costs nothing. It is in the undiscovered vendor baseline, so it never enters the skill listing and never consumes listing budget. My measurement wrongly globbed find -name SKILL.md recursively instead of restricting to discovery depth.

Corrected fleet measurement (direct-child skills/*/SKILL.md only, which is what Claude Code actually loads):

	I reported	Actual
Listing-eligible skills	170	163
Combined description + when_to_use	127,944 chars	120,723 chars
Longest single entry	5,484	1,528
Entries over the 1,536-char listing cap	1	0
Entries over the 1,024-char spec max	21	20

Seven nested SKILL.md files were wrongly counted: two playbooks vendor baselines, one playwright, two context7, and two docs-hygiene eval fixtures (evals/fixtures/broken-skill/SKILL.md, .../healthy-skill/SKILL.md — test data, deliberately malformed in one case).

#3505 has been corrected with the accurate numbers. Nothing here is actionable; closing rather than leaving a wrong issue in the queue.