Skip to content

docs(philosophy): ship no ecosystem-specific examples in skills - #16634

Open
kyle-sexton wants to merge 3 commits into
mainfrom
docs/no-per-stack-examples
Open

kyle-sexton wants to merge 3 commits into
mainfrom
docs/no-per-stack-examples

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

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:research for 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.
  • The rule narrows ADR 0101's source-citation exception; the "Consumer-tool port exception" paragraph and the skills-and-agents review rule now point at it.

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, rust and similar) in plugins/*/skills/** and plugins/*/reference/**, excluding evals/, 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 (rg over plugins/, 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.
  • Every new relative link target exists and both anchors (#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

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
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 16, 2026 20:28
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T20:29:19.104728Z c634527 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@kyle-sexton kyle-sexton added the do-not-merge Hard merge gate: do not merge while applied. label Nov 16, 2026
@kyle-sexton

Copy link
Copy Markdown
Member Author

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.

@kyle-sexton kyle-sexton removed the do-not-merge Hard merge gate: do not merge while applied. label Nov 16, 2026
@kyle-sexton

Copy link
Copy Markdown
Member Author

Hold lifted: the owner decided to record the rule now, in both files (2026-11-16).

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/fix-docs
Model rung 0
Leg handoff
Run job success
Activity step success
Commits pushed none (read lane)
Run 43962272164

Failed GitHub API calls

Method Path Status
GET /repos/{repo}/git/ref/tags/* 404

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

claude-review: 1 inline finding(s) on d066f8772674fc3f8b21f7c90066061a93dd44ce; the summary is in this lane's pull request comment.

claude-lane: claude-review

Comment thread docs/plugin-philosophy.md Resolved
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

claude-review reviewed c1e1a7197433ab9c69b5a2863a6756b8718ebeab: read 1 of 1 changed file(s); 0 finding(s), 0 as inline comments.

Code review: PR #16634, incremental (d066f87 → c1e1a71)

This was an incremental review covering one file, docs/plugin-philosophy.md. I read its single hunk in the incremental diff and checked the surrounding text at the head (L151-L161).

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:

  • Closing issue: none. The PR records an owner decision instead, so there are no acceptance criteria to check.
  • Embedded instructions: none in the PR context or the settled threads.
  • Plugin manifests: none changed.
  • Spend or billing: none.

Verifier dropped 0 of 0 candidates.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review reviewed c1e1a7197433ab9c69b5a2863a6756b8718ebeab: read 1 of 1 changed file(s); 0 finding(s), 0 as inline comments.

Security review: PR #16634, head c1e1a71 (incremental since d066f87)

No security issues found.

This was an incremental review covering one file, docs/plugin-philosophy.md. I read every hunk of its change in the incremental diff. This lane already reviewed an earlier head, so the review was blocking only.

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

  • Instruction-surface lens. The edit removes, narrows and softens nothing. It puts ADR 0101's security and safety floor exception back into the list of items the new rule leaves in place. The previous review raised this gap as an observation, not a finding. Checks such as secret patterns and guards on destructive commands now clearly stay out of the rule's reach.
  • Trust controls. The change touches no trusted-actor list, token scope, kill switch, merge hold, workflow, manifest, userConfig key or executable code.
  • PR context. The description holds no embedded instructions aimed at the lane.
  • Prior findings. The one earlier post was the clean summary from the last review. It held no findings, so nothing is repeated here.

Spend: none.

critical-findings: 0

…xception list

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant