From c634527bcdef26e439040b2e23618187337048a0 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:25:32 -0500 Subject: [PATCH 1/2] docs(philosophy): ship no ecosystem-specific examples in skills 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 Claude-Session: https://claude.ai/code/session_01MWmASPFjTu4anSp6BowqVC --- docs/plugin-philosophy.md | 34 +++++++++++++++++++++++++++++--- docs/review/skills-and-agents.md | 4 +++- 2 files changed, 34 insertions(+), 4 deletions(-) diff --git a/docs/plugin-philosophy.md b/docs/plugin-philosophy.md index faf417e5d47..2ee8c53fa1d 100644 --- a/docs/plugin-philosophy.md +++ b/docs/plugin-philosophy.md @@ -34,8 +34,9 @@ repository names, absolute machine paths, or an undocumented consumer layout. `m `standards/engineering/shareable-artifact-design.md` owns the artifact-agnostic form of this doctrine: consumer-agnostic behavior, externalized consumer-varying configuration, consumer tiers, explicit adoption. This document specializes it for Claude Code plugins and adds only what is -plugin-specific. [Hardcoded consumer specifics](#hardcoded-consumer-specifics) routes the -machine-path and layout half to the audits that check it. +plugin-specific. A consumer's languages, frameworks and tools vary per consumer too, so shipped +skills carry no ecosystem-specific examples. [Hardcoded consumer specifics](#hardcoded-consumer-specifics) +states that rule and routes the machine-path and layout half to the audits that check it. **Org-agnosticism** names the publisher half of that boundary, and it governs *tokens in shipped content*, not only runtime behavior: the publishing organization's name, its marketplace id, its own @@ -134,6 +135,31 @@ audits cite it instead of restating the rule: - `coupling:reduce` remediation catalog (code and document altitude). - `harness-config:audit-permission-grants` (concrete home paths in permission grants only). +**No ecosystem-specific examples.** A shipped skill body or reference file carries no example tied +to one language, framework or tool: no code sample written for one stack, and no link to one tool's +documentation. 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 +repository's and organization's own rules, conventions and agent instructions, which override or +enrich the skill, and with `/discovery:research` for the current idiomatic form when the repository +does not settle it. The order is the [ecosystem-resolution contract](contracts/ecosystem-resolution/README.md) +and the skill standard's +[Stack-specific tools](../plugins/playbooks/skills/skill-authoring/reference/skill-criteria.md#stack-specific-tools); +this rule restates neither. Detail that must persist between runs goes into the consumer's +configuration first; only where configuration cannot express the difference does the skill +generate a repository-specific skill in the consumer repository, as `/app-control:map` generates a +control skill (the skill standard's "Config before a generated skill"). Three things stay: + +- a tool name the skill's own behavior depends on detecting, such as a manifest, lockfile or + config file it looks for; +- the executed adapters and declared-ecosystem surfaces + [ADR 0101](adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md) keeps; +- links to the platform a skill runs on or the provider behind its adapter, which + [skill bodies state current rules](../.claude/rules/skill-bodies-state-current-rules.md) requires. + +This narrows ADR 0101's source-citation exception: a link to one ecosystem's tool documentation is +not a sanctioned citation in a skill body or reference file. + ## Naming A skill name is an imperative verb phrase; the plugin namespace supplies the object @@ -418,7 +444,9 @@ builds on one of the consumer's languages, frameworks, tools, libraries or comma lane-1 default, however safe one looks: when the consumer's choice does not resolve, the skill reports it unresolved and skips the step. The named exceptions (executed adapters, security and safety floors, declared-ecosystem surfaces, source citations) are in -[ADR 0101](adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md). +[ADR 0101](adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md); source citations +exclude one ecosystem's tool documentation, per +[Hardcoded consumer specifics](#hardcoded-consumer-specifics). Lane 2's discovery for a consumer-tool port is the [ecosystem-resolution contract](contracts/ecosystem-resolution/README.md): read the record, then diff --git a/docs/review/skills-and-agents.md b/docs/review/skills-and-agents.md index aa8d6ec19df..5cbdf1f8bd1 100644 --- a/docs/review/skills-and-agents.md +++ b/docs/review/skills-and-agents.md @@ -14,7 +14,9 @@ [ADR 0060](../adr/0060-abstract-provider-details-in-skills-behind-consumer-conventions-and-adapters.md). - A generic skill or agent ships no model-read language, framework, tool or library choice outside the named exceptions; it resolves the choice from the consumer repository: - [ADR 0101](../adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md). + [ADR 0101](../adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md). Nor does it + ship an ecosystem-specific example (a code sample for one stack, a link to one tool's docs): + [plugin philosophy](../plugin-philosophy.md#hardcoded-consumer-specifics). - A new skill that recommends, places or builds enforcement, or an instruction, reads the enforcement ladder, prefers the strongest tier that can decide the matter, and discovers the consumer's tooling first: From c1e1a7197433ab9c69b5a2863a6756b8718ebeab Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 16 Nov 2026 17:08:22 -0500 Subject: [PATCH 2/2] docs(philosophy): keep ADR 0101's security and safety floors in the exception list Co-Authored-By: Claude Opus 5.5 --- docs/plugin-philosophy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugin-philosophy.md b/docs/plugin-philosophy.md index 2ee8c53fa1d..65270ca5140 100644 --- a/docs/plugin-philosophy.md +++ b/docs/plugin-philosophy.md @@ -152,7 +152,7 @@ control skill (the skill standard's "Config before a generated skill"). Three th - a tool name the skill's own behavior depends on detecting, such as a manifest, lockfile or config file it looks for; -- the executed adapters and declared-ecosystem surfaces +- the executed adapters, security and safety floors, and declared-ecosystem surfaces [ADR 0101](adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md) keeps; - links to the platform a skill runs on or the provider behind its adapter, which [skill bodies state current rules](../.claude/rules/skill-bodies-state-current-rules.md) requires.