Repository navigation
docs(philosophy): ship no ecosystem-specific examples in skills - #16634
kyle-sexton wants to merge 3 commits into
Conversation
A shipped skill body or reference file now carries no example tied to one language, framework or tool: no code sample for one stack and no link to one tool's documentation. Such examples change with the stack they show, each change becomes the marketplace's maintenance, and a sample reads as a choice the skill made for the consumer. A skill states its rule in ecosystem-agnostic terms and resolves the specifics at run time from the consumer's own rules, conventions and agent instructions, with /discovery:research for the current idiomatic form when the repository does not settle it. Detail that must persist goes into the consumer's configuration first, and into a generated repository-specific skill only where configuration cannot express it. Tool names stay where a skill's behavior depends on detecting them, along with ADR 0101's executed adapters and declared-ecosystem surfaces and links to the platform a skill runs on. The rule narrows ADR 0101's source-citation exception, and the skills-and-agents review rule points at it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MWmASPFjTu4anSp6BowqVC
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Held: the owner said the repo-wide rule "may be something we want to adopt repo-wide at some point". Whether to record it as doctrine now, including the review rule, is the owner's call. The hold comes off on their answer. |
|
Hold lifted: the owner decided to record the rule now, in both files (2026-11-16). |
Lane run report
Failed GitHub API calls
|
|
claude-review reviewed Code review: PR #16634, incremental (d066f87 → c1e1a71)This was an incremental review covering one file, Result: no new findings. This lane had already reviewed an earlier head, so this pass reported blocking findings only. Previous finding is fixed. The earlier review said the "Three things stay" list left out ADR 0101's security and safety floors. The second bullet now reads "the executed adapters, security and safety floors, and declared-ecosystem surfaces ADR 0101 keeps". That matches the fix suggested in the earlier finding and the four exceptions listed in the file's "Two-lane convention posture" paragraph. The count "Three things stay" is still correct. The owner resolved that thread, and nothing in this push reopens it. Other checks:
Verifier dropped 0 of 0 candidates. |
|
claude-security-review reviewed Security review: PR #16634, head c1e1a71 (incremental since d066f87)No security issues found. This was an incremental review covering one file, What changed: one line at plugin-philosophy.md L155. The list of what stays exempt from the "no ecosystem-specific examples" rule now names "security and safety floors" next to the executed adapters and declared-ecosystem surfaces that ADR 0101 keeps. What I checked
Spend: none. critical-findings: 0 |
…xception list Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
No related issue: owner decision of 2026-11-16, recorded in the plugin philosophy by this PR.
Summary
Shipped skills now carry no ecosystem-specific examples: no code sample written for one language, framework or tool, and no link to one tool's documentation, in skill bodies or reference files. Such examples change with the stack they show, every change becomes our maintenance, and a sample reads as a choice the skill made for the consumer. A skill states its rule in ecosystem-agnostic terms and resolves the specifics at run time from the consumer's own rules, conventions and agent instructions, with
/discovery:researchfor the current idiomatic form when the repository does not settle it.Fix
docs/plugin-philosophy.md, "Design boundary": one sentence names a consumer's languages, frameworks and tools as consumer-varying values, linking to the rule.docs/plugin-philosophy.md, "Hardcoded consumer specifics": the rule, its reason, and pointers to the procedure that already exists (the ecosystem-resolution contract and the skill standard's "Stack-specific tools"), restating neither. Persistent detail goes to the consumer's configuration first and to a generated repository-specific skill only where configuration cannot express it (the skill standard's "Config before a generated skill"). What stays: tool names a skill detects, ADR 0101's executed adapters and declared-ecosystem surfaces, and links to the platform a skill runs on.Proposed check
A bare code-fence lint would be imprecise: skill bodies fence their own commands, output templates and JSON contracts. A precise version counts fences whose info string names a programming language (
csharp,python,typescript,js,go,rustand similar) inplugins/*/skills/**andplugins/*/reference/**, excludingevals/, and runs as a count ratchet (/toolchain:ratchet) rather than a hard fail, since declared-ecosystem surfaces (for example a TypeScript type-discipline reference, the Playwright plugin) keep theirs. Today's count: 179 such fences across 51 files (rgoverplugins/,evals/excluded). Matching tool-documentation links would need a per-stack domain list, the same maintenance the rule exists to avoid, so it is not proposed. Not built in this PR.Verification
scripts/check-affected.sh --no-fetch: 14 passed, 5 skipped over 2 changed files.scripts/check-vocabulary.py: no findings.scripts/check-purged-em-dashes.sh: no em dashes.#hardcoded-consumer-specifics,#stack-specific-tools) resolve to headings in their files. Lychee runs in CI.Related
🤖 Generated with Claude Code
https://claude.ai/code/session_01MWmASPFjTu4anSp6BowqVC