From c0747461529a5e241c4e2e84ddfc46db4dd2c6e5 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Tue, 10 Nov 2026 20:14:43 +0100 Subject: [PATCH 1/4] feat(agentic-engineering): add the skill-lifecycle skill and this marketplace's guide Adopting, writing and updating skills had no written procedure, so each adoption re-derived one, and one decision this week was made on fit alone and had to be reversed after review found wrong examples. - skill-lifecycle is a first-party skill with the portable procedure: research brief, adopt-or-build scorecard with four pass-or-fail gates (licence, provenance, supply chain, correctness of the examples), decision record, first-party authoring rules and the update-review checklist. It pairs with find-skills and check-skills instead of repeating them. - docs/skill-lifecycle.md holds what is specific to this marketplace: the commands, the files a change touches, worked examples of an adoption, an adoption with known defects and a rejection, the ownership and non-duplication policy, and what CI does and does not check. Part of #641 Co-Authored-By: Claude Fable 5.2 --- .claude-plugin/marketplace.json | 2 +- .github/plugin/marketplace.json | 2 +- AGENTS.md | 2 + docs/plugins.md | 3 +- docs/skill-coverage.md | 6 +- docs/skill-lifecycle.md | 112 ++++++++++++++++++ .../.claude-plugin/plugin.json | 2 +- .../.codex-plugin/plugin.json | 2 +- plugins/agentic-engineering/CHANGELOG.md | 11 ++ plugins/agentic-engineering/README.md | 1 + plugins/agentic-engineering/plugin.json | 2 +- .../skills/skill-lifecycle/SKILL.md | 85 +++++++++++++ .../skill-lifecycle/references/authoring.md | 45 +++++++ .../references/decision-record.md | 48 ++++++++ .../skill-lifecycle/references/scorecard.md | 46 +++++++ .../skill-lifecycle/references/updates.md | 21 ++++ 16 files changed, 382 insertions(+), 8 deletions(-) create mode 100644 docs/skill-lifecycle.md create mode 100644 plugins/agentic-engineering/skills/skill-lifecycle/SKILL.md create mode 100644 plugins/agentic-engineering/skills/skill-lifecycle/references/authoring.md create mode 100644 plugins/agentic-engineering/skills/skill-lifecycle/references/decision-record.md create mode 100644 plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md create mode 100644 plugins/agentic-engineering/skills/skill-lifecycle/references/updates.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 819d286..507d66a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -20,7 +20,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "7.3.0", + "version": "7.4.0", "source": "./plugins/agentic-engineering" }, { diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 819d286..507d66a 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -20,7 +20,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "7.3.0", + "version": "7.4.0", "source": "./plugins/agentic-engineering" }, { diff --git a/AGENTS.md b/AGENTS.md index f39b4b9..d015ebc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -113,6 +113,8 @@ checkout. Run `bash scripts/plugin-version-boundaries.test.sh` with the existing ## Authored and externally sourced skills +Before adding, replacing, writing or updating a skill, follow [`docs/skill-lifecycle.md`](docs/skill-lifecycle.md): the research brief and decision record, the adopt-or-build scorecard, the files a change touches here, and the update review. The portable procedure is the bundled `skill-lifecycle` skill. + The maintained first-party skills are canonical at `plugins//skills//` in this repository. Edit them here, with their resources and tests. Their conformant frontmatter has no `metadata.github-*` install provenance, so native `gh skill update --all` skips them rather than overwriting authored work. Validate both authored and external skills against agentskills.io. The catalogue records this repository as the authored skills' license source. External skills retain their original `metadata.github-repo`, `github-path`, `github-ref` and `github-tree-sha`. Install and refresh them through `gh skill install` and the existing `update-agent-skills.yaml` workflow. Never hand-edit an external skill or strip its provenance: fix its owning upstream, then accept the programmed update. The base-tree edit guard retains that boundary even when a PR removes the header. A new skill authored here and an external skill are different authoring paths. diff --git a/docs/plugins.md b/docs/plugins.md index c00b14c..a152be0 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -6,7 +6,7 @@ A **skill** teaches an assistant a task. An **agent** gives it a specialized rol | Plugin | Resources | Description | |--------|-----------|-------------| -| [`agentic-engineering`](../plugins/agentic-engineering/) | `accessibility-review`, `agent-improvement`, `agent-instructions`, `architecture`, `audit-support`, `autofix`, `brand-review`, `campaign-plan`, `check-skills`, `close-management`, `code-review`, `codeql`, `competitive-brief`, `connector-setup`, `content-creation`, `context7-mcp`, `conventional-release`, `debug`, `dependabot`, `dependency-scanning`, `deploy-checklist`, `design-critique`, `design-handoff`, `design-system`, `documentation`, `draft-content`, `email-sequence`, `financial-statements`, `find-skills`, `frontend-design`, `gh-cli`, `gh-stack`, `git-commit`, `github-actions-docs`, `github-actions-efficiency`, `github-actions-hardening`, `github-issues`, `gitops-cluster-debug`, `gitops-knowledge`, `gitops-tenant-onboarding`, `golang-pro`, `grilling`, `incident-response`, `journal-entry`, `journal-entry-prep`, `memory-management`, `metrics-review`, `performance-report`, `portfolio-maintenance`, `product-brainstorming`, `product-documentation`, `product-engineering`, `prometheus`, `promql`, `prototype`, `reconciliation`, `refactor`, `research-synthesis`, `roadmap-update`, `secret-scanning`, `self-improvement`, `seo-audit`, `siderolabs`, `sox-testing`, `sprint-planning`, `stakeholder-update`, `standup`, `start`, `stripe-best-practices`, `stripe-docs`, `svelte-core-bestpractices`, `synthesize-research`, `system-design`, `task-management`, `tech-debt`, `test-driven-development`, `testing-strategy`, `update`, `upgrade-stripe`, `user-research`, `ux-copy`, `variance-analysis`, `ways-of-working`, `web-design-guidelines`, `workspace-conventions`, `write-contributing`, `write-docs-introduction`, `write-readme`, `write-spec` (skills) · `agent-improver`, `agentic-engineer`, `flux-troubleshooter`, `portfolio-surveyor` (agents) · `aws-knowledge`, `cloudflare-docs`, `context7`, `coroot`, `flux-operator-mcp`, `github`, `github-ghas-tools`, `kubescape`, `siderolabs-docs`, `stripe`, `svelte`, `terraform-registry` (MCP servers) | The autonomous engineering system for a whole repository portfolio, and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; operating, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use. Configured by the consumer's `AGENTS.md` | +| [`agentic-engineering`](../plugins/agentic-engineering/) | `accessibility-review`, `agent-improvement`, `agent-instructions`, `architecture`, `audit-support`, `autofix`, `brand-review`, `campaign-plan`, `check-skills`, `close-management`, `code-review`, `codeql`, `competitive-brief`, `connector-setup`, `content-creation`, `context7-mcp`, `conventional-release`, `debug`, `dependabot`, `dependency-scanning`, `deploy-checklist`, `design-critique`, `design-handoff`, `design-system`, `documentation`, `draft-content`, `email-sequence`, `financial-statements`, `find-skills`, `frontend-design`, `gh-cli`, `gh-stack`, `git-commit`, `github-actions-docs`, `github-actions-efficiency`, `github-actions-hardening`, `github-issues`, `gitops-cluster-debug`, `gitops-knowledge`, `gitops-tenant-onboarding`, `golang-pro`, `grilling`, `incident-response`, `journal-entry`, `journal-entry-prep`, `memory-management`, `metrics-review`, `performance-report`, `portfolio-maintenance`, `product-brainstorming`, `product-documentation`, `product-engineering`, `prometheus`, `promql`, `prototype`, `reconciliation`, `refactor`, `research-synthesis`, `roadmap-update`, `secret-scanning`, `self-improvement`, `seo-audit`, `siderolabs`, `skill-lifecycle`, `sox-testing`, `sprint-planning`, `stakeholder-update`, `standup`, `start`, `stripe-best-practices`, `stripe-docs`, `svelte-core-bestpractices`, `synthesize-research`, `system-design`, `task-management`, `tech-debt`, `test-driven-development`, `testing-strategy`, `update`, `upgrade-stripe`, `user-research`, `ux-copy`, `variance-analysis`, `ways-of-working`, `web-design-guidelines`, `workspace-conventions`, `write-contributing`, `write-docs-introduction`, `write-readme`, `write-spec` (skills) · `agent-improver`, `agentic-engineer`, `flux-troubleshooter`, `portfolio-surveyor` (agents) · `aws-knowledge`, `cloudflare-docs`, `context7`, `coroot`, `flux-operator-mcp`, `github`, `github-ghas-tools`, `kubescape`, `siderolabs-docs`, `stripe`, `svelte`, `terraform-registry` (MCP servers) | The autonomous engineering system for a whole repository portfolio, and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; operating, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use. Configured by the consumer's `AGENTS.md` | | [`vibe-coding`](../plugins/vibe-coding/) | `needs-stack-mapping`, `allowed-stack-guardrail`, `jargon-free-voice` (skills) · `vibe-coding-companion` (agent) | Build a product by conversation alone — plain-language companion agent + guardrailed needs-to-stack skills for people with no technical background | | [`ksail`](../plugins/ksail/) | `ksail` (skill) · `ksail` (MCP server) | Create and operate Kubernetes clusters and GitOps workloads with the KSail CLI — needs `ksail` on `PATH`; PolyForm Shield licensed | @@ -83,6 +83,7 @@ license file the plugin ships; keep both when you copy or redistribute those ski | `self-improvement` | `agentic-engineering` | devantler-tech/agent-plugins | Apache-2.0 | | `seo-audit` | `agentic-engineering` | anthropics/knowledge-work-plugins | Apache-2.0 | | `siderolabs` | `agentic-engineering` | siderolabs/docs | Apache-2.0 | +| `skill-lifecycle` | `agentic-engineering` | devantler-tech/agent-plugins | Apache-2.0 | | `sox-testing` | `agentic-engineering` | anthropics/knowledge-work-plugins | Apache-2.0 | | `sprint-planning` | `agentic-engineering` | anthropics/knowledge-work-plugins | Apache-2.0 | | `stakeholder-update` | `agentic-engineering` | anthropics/knowledge-work-plugins | Apache-2.0 | diff --git a/docs/skill-coverage.md b/docs/skill-coverage.md index 3cd0139..bf333a0 100644 --- a/docs/skill-coverage.md +++ b/docs/skill-coverage.md @@ -105,8 +105,10 @@ with SvelteKit and a Go server. An agent that trusts the card would choose `astr ## Prioritized gaps -1. **Prerequisites for every adoption:** the adopt-or-build rubric and pinning lifecycle - ([#641](https://github.com/devantler-tech/agent-plugins/issues/641), with #581, #583 and #598), +1. **Prerequisites for every adoption:** the adopt-or-build rubric and pinning lifecycle are + delivered in 7.4.0 as the `skill-lifecycle` skill and [`skill-lifecycle.md`](skill-lifecycle.md) + ([#641](https://github.com/devantler-tech/agent-plugins/issues/641)); still open are updater + pull requests that say what changed upstream (#583, under #581), the activation suite (#651), and stale user-level copies that shadow plugin skills ([monorepo#4840](https://github.com/devantler-tech/monorepo/issues/4840)). Each adoption also adds description text, and #642 found 30 of 94 listed skills shown by name only. So every adoption diff --git a/docs/skill-lifecycle.md b/docs/skill-lifecycle.md new file mode 100644 index 0000000..bafaf2b --- /dev/null +++ b/docs/skill-lifecycle.md @@ -0,0 +1,112 @@ +# Skill lifecycle in this marketplace + +How a skill gets into a plugin here, stays current, and leaves. The decision procedure itself +(research brief, adopt-or-build scorecard, decision record, authoring rules, update checklist) +is the [`skill-lifecycle`](../plugins/agentic-engineering/skills/skill-lifecycle/SKILL.md) skill, +so agents load it wherever they work. This page adds only what is specific to this repository: +the commands, the files a change touches, and worked examples. [`AGENTS.md`](../AGENTS.md) links +here. + +## Ownership and non-duplication + +- **One capability, one skill, one owner.** Before adding a skill, check the + [catalogue](plugins.md) and the [coverage page](skill-coverage.md). If a bundled skill already + covers the gap, improve its owner; do not add a second. +- **External skills are owned by their upstream.** They keep their `metadata.github-*` + provenance and are never edited here; the base-tree edit guard enforces it. A defect is fixed + upstream and arrives through the updater. This repository owns only the decision to carry the + skill, its pin and its licence record. +- **First-party skills are owned here**, at `plugins//skills//`, and carry no + install provenance. [ADR 0006](adr/0006-maintained-skill-ownership.md) records that boundary. +- **Replacing a skill removes the old one in the same change**, with the reason in the + changelog. The 7.0.0 entry for `astro` is the model. +- **Guidance that is true for one repository stays in that repository.** A skill here holds + what is true wherever the tool is used. + +## Adopting an external skill + +1. Post the research brief and the decision record on the issue (templates in the skill's + [`decision-record.md`](../plugins/agentic-engineering/skills/skill-lifecycle/references/decision-record.md)). +2. Install with provenance, from a clean tree: + `gh skill install / --dir plugins//skills`. + The copy records the repository, path, ref and tree hash. That tree hash is the pin. +3. Record the licence: a row in [`plugins.md`](plugins.md), and for third-party content a row + and a `## /` section with the copyright notice and licence text in + `plugins//resources/THIRD-PARTY-NOTICES.md`. +4. Add the skill to the catalogue cell in [`plugins.md`](plugins.md) and to the plugin's README. +5. Bump the plugin version with `./scripts/bump-plugin-version.sh minor` and add a + changelog entry that names the source, what was deliberately not taken, and any known defect. +6. Update the [coverage page](skill-coverage.md): the matrix row, the candidate row and the + priority list. +7. Run the checks in [`validation.md`](validation.md): `./scripts/validate-manifests.sh`, + `bash scripts/check-skill-licenses.sh` and the spec validation. +8. Try it as a user: install the skill from the pull request's head into an empty directory + (`gh skill install devantler-tech/agent-plugins --pin --dir `), compare it + with a fresh upstream install, and run the acceptance scenarios from the brief. + +**Worked examples.** + +| Outcome | Where | What it shows | +|---|---|---| +| Adopted | #654, merged in #675 | Two skills taken from a larger collection and two rejected, with the scorecard reasons; the pin and licence record; an install-and-compare trial | +| Adopted with known defects | #675, follow-up #676 | Review found two wrong examples. They fail loudly and sit outside what the portfolio relies on, so the changelog and the coverage page name them and the upstream fix is tracked | +| Rejected after review | #653, merged in #673, follow-up #674 | A vendor-maintained skill whose examples were wrong where it mattered (access rules). The first decision was made on fit alone and had to be reversed: read for correctness before deciding | +| Not bundled | the 7.0.0 changelog entry | A skill removed from the bundle, with the one command that installs it from upstream where it is needed | + +## Reviewing an updater pull request + +`update-agent-skills.yaml` opens one pull request per skill whose upstream moved (#671 is a +recent one). Its body does not yet say what changed upstream; #583 tracks that, under #581 +(reviewable updates and redistribution terms). Until it lands, the reviewer does the reading by hand, with the +skill's [update checklist](../plugins/agentic-engineering/skills/skill-lifecycle/references/updates.md): + +- the difference between the old and new `github-tree-sha`, for every file in the skill; +- the upstream commits in that range; +- a changed licence or notice (the licence check fails on a missing record, or one that + disagrees with the licence the skill declares, but it does not compare licence texts except + where a dedicated check exists); +- the same validation as an adoption. + +Rolling back is reverting the updater pull request, which restores the previous tree hash. +A skill pinned to a tag or commit stays there until the pin is moved on purpose; #598 is the +record of one temporary pin and its release. + +## Authoring a first-party skill + +Only after a decision record says build. Draft with the host's skill-authoring tool where it +has one (Anthropic's `skill-creator` in Claude); the rules it must meet are the skill's +[`authoring.md`](../plugins/agentic-engineering/skills/skill-lifecycle/references/authoring.md). +Then, in this repository: + +1. Create `plugins//skills//SKILL.md` with `name`, `description` and + `license: Apache-2.0`, and no `metadata.github-*` fields. +2. Add its row and catalogue entry in [`plugins.md`](plugins.md) with this repository as the + source, and list it in the plugin's README. +3. Bump the version and write the changelog entry, as for an adoption. +4. Run the same checks. CI validates every skill folder against the open skill format. +5. Record the acceptance scenarios on the issue and list them for the activation suite (#651). + +`skill-lifecycle` itself was written this way: its brief, the candidates it was weighed against +and its scenarios are on #641. + +## What CI checks, and what it does not + +Checked on every pull request: the two marketplace manifests agree, every skill folder is +catalogued, external skills keep their provenance and are not edited, every bundled skill has a +licence record, each `SKILL.md` validates against the open skill format, and a changed plugin +has a changed version. [`validation.md`](validation.md) has the commands. + +Not checked by CI: whether a skill's examples are correct, and whether it loads for the tasks +it is meant for. The first is the correctness gate in the scorecard. The second is what the +activation suite in #651 will measure; until then it is the trial in each pull request. + +## Keeping sources current + +- **On every updater pull request**: the update checklist above. +- **When a product changes its stack**: update the [coverage page](skill-coverage.md) in the + same piece of work, so the matrix does not describe a stack that is gone. +- **Dated facts**: a skill that lists products, limits or legal requirements says when they + were checked. Re-check them when the skill is next changed, and at least when the coverage + page is re-audited. +- **The coverage audit** is repeated when a gap it lists is closed or a new product joins the + portfolio. It is the place a stale or duplicated skill gets noticed. diff --git a/plugins/agentic-engineering/.claude-plugin/plugin.json b/plugins/agentic-engineering/.claude-plugin/plugin.json index 749b325..d699612 100644 --- a/plugins/agentic-engineering/.claude-plugin/plugin.json +++ b/plugins/agentic-engineering/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "7.3.0", + "version": "7.4.0", "author": { "name": "devantler-tech", "url": "https://github.com/devantler-tech" diff --git a/plugins/agentic-engineering/.codex-plugin/plugin.json b/plugins/agentic-engineering/.codex-plugin/plugin.json index b4a168e..bb762f2 100644 --- a/plugins/agentic-engineering/.codex-plugin/plugin.json +++ b/plugins/agentic-engineering/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "7.3.0", + "version": "7.4.0", "author": { "name": "devantler-tech", "url": "https://github.com/devantler-tech" diff --git a/plugins/agentic-engineering/CHANGELOG.md b/plugins/agentic-engineering/CHANGELOG.md index 77a22ef..aae6308 100644 --- a/plugins/agentic-engineering/CHANGELOG.md +++ b/plugins/agentic-engineering/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog — `agentic-engineering` +## 7.4.0 — 2026-11-10 + +**Added** — `skill-lifecycle`, a first-party skill: how to decide whether to adopt, build or reject +an agent skill, and how to carry the decision through. It holds the research brief, the +adopt-or-build scorecard with its four pass-or-fail gates (licence, provenance, supply chain and +the correctness of the examples), the decision record, the rules for writing a first-party skill, +and the checklist for reviewing an update to an adopted skill. It pairs with `find-skills` for +discovery and `check-skills` for the security review, and leaves drafting and evaluation to the +host's own skill-authoring tool. This marketplace's commands and worked examples are in +`docs/skill-lifecycle.md` (#641). + ## 7.3.0 — 2026-11-10 **Added** — `promql` and `prometheus` from `https://github.com/grafana/skills` at `refs/heads/main`: diff --git a/plugins/agentic-engineering/README.md b/plugins/agentic-engineering/README.md index 416c6fb..aa3f482 100644 --- a/plugins/agentic-engineering/README.md +++ b/plugins/agentic-engineering/README.md @@ -127,6 +127,7 @@ are maintained here. | Finance | `audit-support`, `close-management`, `financial-statements`, `journal-entry`, `journal-entry-prep`, `reconciliation`, `sox-testing`, `variance-analysis` | | Productivity | `memory-management`, `start`, `task-management`, `update`, `workspace-conventions` (where their notes and tasks go) | | Connectors | `connector-setup` (which official mail, calendar, LinkedIn or security connector to ask for) | +| Skills | `skill-lifecycle` (adopt, build, pin and update a skill; pairs with `find-skills` and `check-skills`) | `dependency-scanning` runs only when asked, and asks again before it downloads the Dependabot CLI or audits a whole repository. KSail has its own [`ksail`](../ksail/) plugin, made for KSail's users; diff --git a/plugins/agentic-engineering/plugin.json b/plugins/agentic-engineering/plugin.json index 749b325..d699612 100644 --- a/plugins/agentic-engineering/plugin.json +++ b/plugins/agentic-engineering/plugin.json @@ -1,7 +1,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "7.3.0", + "version": "7.4.0", "author": { "name": "devantler-tech", "url": "https://github.com/devantler-tech" diff --git a/plugins/agentic-engineering/skills/skill-lifecycle/SKILL.md b/plugins/agentic-engineering/skills/skill-lifecycle/SKILL.md new file mode 100644 index 0000000..bcf3d82 --- /dev/null +++ b/plugins/agentic-engineering/skills/skill-lifecycle/SKILL.md @@ -0,0 +1,85 @@ +--- +name: skill-lifecycle +description: Decide whether to adopt, build or reject an agent skill, and carry the choice through - research brief, adopt-or-build scorecard, pinned install with licence and provenance, first-party authoring rules, and review of skill updates. Use when adding, writing, replacing or updating a skill, or when asked whether a skill for something should exist. +license: Apache-2.0 +--- + +# Skill lifecycle + +A skill is an instruction an agent will follow without re-checking it. A wrong example in a +skill becomes wrong work in every repository that loads it. So a skill earns its place the way +a dependency does: by evidence, with a recorded decision and a pinned source. + +Prefer a good upstream skill over a new one. Build only when the research shows nothing fits. +Never do both: one capability has one skill and one owner. + +## The order of work + +1. **Write the research brief** before reading any candidate closely + ([template](references/decision-record.md#research-brief)). State the gap in one sentence, + the repositories and tasks it shows up in, and three to five acceptance scenarios: tasks that + should load the skill, a near miss that should not, and what a correct result looks like. +2. **Look for what already exists.** Check the skills already installed, then search upstream + (use `find-skills` if it is available). Stop here if an installed skill already covers the + gap: improve its owner instead of adding a second one. +3. **Score every serious candidate** with the [scorecard](references/scorecard.md). Four gates + are pass or fail; the rest are scored. Read the candidate's examples for correctness, not + only for fit. This is the step that gets skipped, and it is the one that matters. +4. **Record the decision** where the request lives + ([template](references/decision-record.md#decision-record)): adopt, adopt with known + defects, reject, or build. Name every candidate you rejected and why. +5. **Carry it out**: [adopt and pin](#adopting-an-upstream-skill), or + [author a first-party skill](#authoring-a-first-party-skill). +6. **Prove it loads and helps.** Install it the way a user would, run the acceptance scenarios + from the brief, and say what you saw. + +## Adopting an upstream skill + +- **Install it with its provenance, never by copying files.** Use the installer the repository + uses (for example `gh skill install / `), so the copy records its source + repository, path, ref and tree hash. That record is the pin: it names exactly which upstream + content was reviewed. +- **Never edit an adopted skill.** A fix goes to its upstream and arrives through an update. + If you find a defect you cannot fix upstream today, either reject the skill or adopt it with + the defect written down where users will read it, and track the upstream fix. +- **Keep its licence with it.** Record the licence and copyright notice the way the repository + records third-party content. No licence, or one that forbids redistribution, is a rejection. +- **Take only what was reviewed.** Adopt single skills, not a whole collection. +- **Run the security review** before installing anything with scripts, downloads, tool + permissions or network calls (use `check-skills` if it is available). + +## Reviewing a skill update + +An update to an adopted skill is new instruction text from someone else. Read it as a change, +not as a version bump. [The update checklist](references/updates.md) has the steps: the exact +diff against the pinned tree, what upstream says changed, anything that breaks a documented +behaviour, a licence change, the validation result, and how to roll back. + +## Authoring a first-party skill + +Only after the decision record says build. The full rules are in +[authoring.md](references/authoring.md); the ones that fail most often: + +- The description says what the skill does and when to use it, in the words a user would + type. It is the only part loaded before the skill is chosen. +- The body is the procedure, in the order the work happens. Detail that only some tasks need + moves to `references/`, one level deep. +- Every example is one you ran or checked against the tool's own documentation, with the date + you checked it when the fact can go stale. +- The acceptance scenarios from the brief become the skill's test cases. +- Draft and evaluate with the host's own skill-authoring tool when it has one. That tool + covers drafting and evaluation; this skill covers the decision and the rules. + +## Ownership + +- An adopted skill is owned by its upstream. The repository that bundles it owns the decision + to carry it, its pin and its licence record, and nothing inside it. +- A first-party skill is owned by the repository that holds its source. Change it there. +- Do not carry two skills for one capability. When a better one arrives, the same change + removes or retires the old one and says so. + +## What to hand back + +The decision record, the scorecard for each candidate, what was installed or written and from +which pinned source, the acceptance scenarios with what you observed, and anything left open +with its owner. diff --git a/plugins/agentic-engineering/skills/skill-lifecycle/references/authoring.md b/plugins/agentic-engineering/skills/skill-lifecycle/references/authoring.md new file mode 100644 index 0000000..fa4ce42 --- /dev/null +++ b/plugins/agentic-engineering/skills/skill-lifecycle/references/authoring.md @@ -0,0 +1,45 @@ +# Authoring a first-party skill + +Write one only after the decision record says build. + +## Shape + +- **Folder and name.** The folder name is the skill name: lowercase letters, digits and single + hyphens, at most 64 characters. `SKILL.md` sits at its root. +- **Frontmatter.** `name` and `description` are required; add `license`. Add other fields only + when a host needs them, and say which host. +- **Description.** One or two sentences, at most 1024 characters and much shorter when you can. + Say what the skill does, then when to use it, in the words a user would type. It is loaded in + every session, before the skill is chosen, so it pays for itself or it costs everyone. +- **Body.** The procedure in the order the work happens, under 500 lines. Start with what the + reader must not get wrong. +- **References.** Detail that only some tasks need goes in `references/`, linked from the body, + one level deep. Scripts go in `scripts/` and say what they need to run. + +## Content + +- **Every example is checked.** Run it, or check it against the tool's own documentation, and + name the version it is true for when that matters. +- **Facts that go stale carry a date.** "Checked 2026-11-04" beside a list of products or + limits tells the next reader when to look again. +- **Say what the skill does not cover** and what does. A near miss that loads the wrong skill + is worse than no skill. +- **No secrets, private hostnames or account details**, and nothing that only works in one + person's environment. +- **Do not restate another skill.** Point to it. + +## Proof + +- The acceptance scenarios from the research brief are the test cases. Keep them with the + skill's decision record, and add them to the repository's evaluation suite when it has one. +- Validate the folder against the open skill format (`skills-ref validate `), and run + whatever else the repository runs for its skills. +- Install the skill the way a user would and try each scenario. A skill that validates but + never loads for its own scenarios is not finished: fix the description first. + +## Change + +- A first-party skill changes in the repository that holds its source, with the same review + as code. +- A change to the description is a change to when the skill loads. Re-run the scenarios. +- Retire a skill in the same change that replaces it. diff --git a/plugins/agentic-engineering/skills/skill-lifecycle/references/decision-record.md b/plugins/agentic-engineering/skills/skill-lifecycle/references/decision-record.md new file mode 100644 index 0000000..84ea38d --- /dev/null +++ b/plugins/agentic-engineering/skills/skill-lifecycle/references/decision-record.md @@ -0,0 +1,48 @@ +# Research brief and decision record + +Both go where the request lives (the issue or the pull request), so the reasoning stays with +the change. + +## Research brief + +Write this first, before reading candidates closely. + +```markdown +## Research brief + +**Gap.** + +**Where it shows up.** + +**Acceptance scenarios.** +- Should load: "" -> +- Should load: "" -> +- Near miss: "" -> +- Must not load: "" + +**Already covered by.** + +**Out of scope.** +``` + +## Decision record + +```markdown +## Decision record: `` + +**Candidates.** + +| Candidate | Owner and licence | Reviewed at | Gates | Score | Verdict | +|---|---|---|---|---|---| +| | , | | | /10 | | + +**What was read.** + +**Known defects.** + +**Description cost.** + +**Acceptance scenarios.** + +**What would change this decision.** +``` diff --git a/plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md b/plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md new file mode 100644 index 0000000..e1beb77 --- /dev/null +++ b/plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md @@ -0,0 +1,46 @@ +# Adopt-or-build scorecard + +Fill one scorecard per candidate. A candidate that fails any gate is rejected, whatever it +scores elsewhere. Write down what you looked at, not only the verdict: the next reader has to +be able to check it. + +## Gates (pass or fail) + +| Gate | Passes when | How to check | +|---|---|---| +| Licence | The licence allows redistribution, and its notice can be kept with the copy | Read the licence file in the candidate's repository, not a badge or a registry field | +| Provenance | The owner is who it claims to be, the repository is not archived, and the skill can be pinned to an exact tree | Open the repository; confirm the owner; note the commit and the tree hash you reviewed | +| Supply chain | Nothing in the skill downloads and runs unpinned code, asks for credentials, or widens tool permissions without saying why | Read every script and every command in the text; run the security review if one is available | +| Correctness | Every example you read is right for the tool and version it names | Check the examples against the tool's own documentation or by running them. Read all of them for a small skill, and at least every example in the areas you will rely on for a large one | + +The correctness gate is the one most often skipped. A skill that reads well and is from a +known vendor can still carry an example that is wrong in a way that only shows in production. +Fit is not correctness: read for both. + +## Scored (0 to 2 each) + +| Dimension | 0 | 1 | 2 | +|---|---|---|---| +| Functionality | Misses the gap in the brief | Covers part of it | Covers the acceptance scenarios | +| Maintenance | No change in a year, or issues unanswered | Occasional activity | Active, with releases or regular commits | +| Compatibility | Tied to one host or one hosted product you do not use | Works with caveats | Follows the open skill format and names no product you lack | +| Test quality | No examples of expected behaviour | Examples only | Evaluation cases or tests upstream | +| Upkeep | Large, changes often, or needs local patches | Moderate | Small, stable, used unmodified | + +Add the description length in characters. Every listed skill costs every session some of its +skill-listing budget, so a long description needs a reason. + +## Reading the result + +- **Adopt**: all gates pass and Functionality is 2. +- **Adopt with known defects**: the gates pass except for defects in examples that are few, + outside the areas you rely on, and that fail loudly (an error or an obvious wrong result, + never a silent one). Name each defect where users read about the skill, and track the + upstream fix. +- **Reject**: a gate fails, or the defects are in the areas you rely on, or they fail silently + (security rules, data loss, access control). +- **Build**: no candidate can be adopted and the gap is still worth closing. Say why each + candidate was rejected. + +A rejection is a result. Record it so the next person does not repeat the evaluation, and say +what would change the answer. diff --git a/plugins/agentic-engineering/skills/skill-lifecycle/references/updates.md b/plugins/agentic-engineering/skills/skill-lifecycle/references/updates.md new file mode 100644 index 0000000..d40a859 --- /dev/null +++ b/plugins/agentic-engineering/skills/skill-lifecycle/references/updates.md @@ -0,0 +1,21 @@ +# Reviewing an update to an adopted skill + +An update replaces instruction text that agents follow. Review the text, not the version. + +1. **Find the two pins.** The tree hash the copy records now, and the one the update moves to. +2. **Read the exact difference** between those two trees, for every file in the skill. An + update tool's summary is not the diff. +3. **Read what upstream says changed**: the commits or release notes in that range. If + upstream publishes no notes, the commit list is the record. +4. **Look for breaking changes**: a renamed or removed command, a changed default, a new + requirement (a tool, a network call, a hosted service), or a narrower or wider description + that changes when the skill loads. +5. **Check the licence** in the new tree. A changed licence or a removed notice stops the + update until the record is corrected or the skill is dropped. +6. **Repeat the correctness read** for every example the update adds or changes. +7. **Run the repository's validation**, and try one acceptance scenario from the skill's + decision record against the new copy. +8. **Know the way back.** Rolling back is reverting the update, which restores the previous + pin. Say so in the review if anything is uncertain. + +Hold the update when any step cannot be completed. An unread update is not a reviewed one. From c32e96264afd5706b7417d108be835f7c91d169d Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Tue, 10 Nov 2026 21:25:50 +0100 Subject: [PATCH 2/4] docs(skill-lifecycle): fold in what a first trial of the skill found A fresh agent used the skill on two real requests (reviewing a merged skill update, and deciding whether a new skill should exist) and reported where the text left it guessing: - which hash to compare, and that a recorded tag can move while the tree hash cannot; - scoping upstream changes to the skill's own path, and reading the release notes of the tool the skill tells agents to use; - checking a new requirement against the consumer's own setup, and what to do with an instruction that cannot run there; - examples that cannot be run, skills adopted before there was a record, and a review that happens after the merge; - the order of work: show the gap is real, and ask whether a CI check would fix it better, before searching for candidates; - scoring: a stable finished skill is not abandoned, and the scores are for comparison, not a total. Part of #641 Co-Authored-By: Claude Fable 5.2 --- .../skills/skill-lifecycle/SKILL.md | 59 ++++++++++++------- .../references/decision-record.md | 22 ++++--- .../skill-lifecycle/references/scorecard.md | 19 ++++-- .../skill-lifecycle/references/updates.md | 51 +++++++++++----- 4 files changed, 99 insertions(+), 52 deletions(-) diff --git a/plugins/agentic-engineering/skills/skill-lifecycle/SKILL.md b/plugins/agentic-engineering/skills/skill-lifecycle/SKILL.md index bcf3d82..49a77b3 100644 --- a/plugins/agentic-engineering/skills/skill-lifecycle/SKILL.md +++ b/plugins/agentic-engineering/skills/skill-lifecycle/SKILL.md @@ -15,45 +15,60 @@ Never do both: one capability has one skill and one owner. ## The order of work -1. **Write the research brief** before reading any candidate closely - ([template](references/decision-record.md#research-brief)). State the gap in one sentence, - the repositories and tasks it shows up in, and three to five acceptance scenarios: tasks that - should load the skill, a near miss that should not, and what a correct result looks like. -2. **Look for what already exists.** Check the skills already installed, then search upstream - (use `find-skills` if it is available). Stop here if an installed skill already covers the - gap: improve its owner instead of adding a second one. -3. **Score every serious candidate** with the [scorecard](references/scorecard.md). Four gates +1. **Show the gap is real.** Find at least two real cases where the work went wrong for lack + of this guidance. "Agents keep getting it wrong" is a claim until it is linked. With no + cases, stop and say so. +2. **Draft the research brief** before reading any candidate closely + ([template](references/decision-record.md#research-brief)): the gap in one sentence, the + cases, and three to five acceptance scenarios (requests that should load the skill, a near + miss that should not, and what a correct result looks like). +3. **Ask whether a skill is the right fix.** A check in CI, a linter or a line in the + repository's own documentation often fixes a recurring mistake more reliably than guidance + an agent may or may not load. Say which you weighed. +4. **Look for what already exists.** First the skills already installed, then upstream: use + `find-skills` if it is available; otherwise look in the tool vendor's own repositories, the + skill collections your team already installs from, and a code search for the tool's name + beside `SKILL.md`. If an installed skill already covers the same requests, stop and improve + its owner. If it covers a neighbouring task, a new skill is allowed only with the boundary + written into both descriptions; the near-miss scenario is that boundary. +5. **Score every serious candidate** with the [scorecard](references/scorecard.md). Four gates are pass or fail; the rest are scored. Read the candidate's examples for correctness, not only for fit. This is the step that gets skipped, and it is the one that matters. -4. **Record the decision** where the request lives +6. **Record the decision** where the request lives ([template](references/decision-record.md#decision-record)): adopt, adopt with known - defects, reject, or build. Name every candidate you rejected and why. -5. **Carry it out**: [adopt and pin](#adopting-an-upstream-skill), or + defects, reject, build, or no skill. Name every candidate you rejected and why. +7. **Carry it out**: [adopt and pin](#adopting-an-upstream-skill), or [author a first-party skill](#authoring-a-first-party-skill). -6. **Prove it loads and helps.** Install it the way a user would, run the acceptance scenarios - from the brief, and say what you saw. +8. **Prove it loads and helps.** Install it from the change itself into a clean location. Give + each acceptance scenario to a fresh session or agent that can see only the skill's name and + description, without naming the skill. It passes when the skill is chosen for the scenarios + that should load it, is left alone for the near miss, and the result is the one the brief + describes. Ask that session what in the text was unclear, and fix what it reports. ## Adopting an upstream skill - **Install it with its provenance, never by copying files.** Use the installer the repository uses (for example `gh skill install / `), so the copy records its source - repository, path, ref and tree hash. That record is the pin: it names exactly which upstream - content was reviewed. + repository, path, ref and tree hash. The tree hash is the pin: it names exactly which + upstream content was reviewed. A tag or a branch name can move; the hash cannot. - **Never edit an adopted skill.** A fix goes to its upstream and arrives through an update. If you find a defect you cannot fix upstream today, either reject the skill or adopt it with the defect written down where users will read it, and track the upstream fix. -- **Keep its licence with it.** Record the licence and copyright notice the way the repository - records third-party content. No licence, or one that forbids redistribution, is a rejection. +- **Keep its licence with it.** Record the licence and copyright notice in the place the + repository keeps its third-party notices. No licence, or one that forbids redistribution, is + a rejection. - **Take only what was reviewed.** Adopt single skills, not a whole collection. +- **Check what it needs against your setup.** A skill that tells agents to use a tool or a + service you do not provide is partly inert, or misleading. Say which. - **Run the security review** before installing anything with scripts, downloads, tool permissions or network calls (use `check-skills` if it is available). ## Reviewing a skill update An update to an adopted skill is new instruction text from someone else. Read it as a change, -not as a version bump. [The update checklist](references/updates.md) has the steps: the exact -diff against the pinned tree, what upstream says changed, anything that breaks a documented -behaviour, a licence change, the validation result, and how to roll back. +not as a version bump. [The update checklist](references/updates.md) has the steps: the two +pins, the exact difference between them, what upstream says changed, new requirements checked +against your own setup, the licence, the validation result, and how to roll back. ## Authoring a first-party skill @@ -81,5 +96,5 @@ Only after the decision record says build. The full rules are in ## What to hand back The decision record, the scorecard for each candidate, what was installed or written and from -which pinned source, the acceptance scenarios with what you observed, and anything left open -with its owner. +which pinned source, the acceptance scenarios with what you observed, anything left +unverified, and anything left open with its owner. diff --git a/plugins/agentic-engineering/skills/skill-lifecycle/references/decision-record.md b/plugins/agentic-engineering/skills/skill-lifecycle/references/decision-record.md index 84ea38d..528df7c 100644 --- a/plugins/agentic-engineering/skills/skill-lifecycle/references/decision-record.md +++ b/plugins/agentic-engineering/skills/skill-lifecycle/references/decision-record.md @@ -1,18 +1,22 @@ # Research brief and decision record Both go where the request lives (the issue or the pull request), so the reasoning stays with -the change. +the change. A request that arrived in conversation has no such place yet: open an issue in the +repository that would carry the skill, and record them there. ## Research brief -Write this first, before reading candidates closely. +Draft this first, before reading candidates closely. Fill in "Already covered by" once you +have looked at what is installed. ```markdown ## Research brief **Gap.** -**Where it shows up.** +**Evidence.** + +**Where it shows up.** **Acceptance scenarios.** - Should load: "" -> @@ -22,21 +26,23 @@ Write this first, before reading candidates closely. **Already covered by.** +**Would something else fix it better?** + **Out of scope.** ``` ## Decision record ```markdown -## Decision record: `` +## Decision record: `` **Candidates.** -| Candidate | Owner and licence | Reviewed at | Gates | Score | Verdict | +| Candidate | Owner and licence | Reviewed at | Gates | Scores | Verdict | |---|---|---|---|---|---| -| | , | | | /10 | | +| | , | | | | | -**What was read.** +**What was read.** **Known defects.** @@ -44,5 +50,5 @@ Write this first, before reading candidates closely. **Acceptance scenarios.** -**What would change this decision.** +**What would change this decision.** ``` diff --git a/plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md b/plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md index e1beb77..f025ef0 100644 --- a/plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md +++ b/plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md @@ -8,30 +8,37 @@ be able to check it. | Gate | Passes when | How to check | |---|---|---| -| Licence | The licence allows redistribution, and its notice can be kept with the copy | Read the licence file in the candidate's repository, not a badge or a registry field | +| Licence | The licence allows redistribution, and its notice can be kept with the copy | Read the licence file in the candidate's repository, not a badge or a registry field. It may sit at the repository root, outside the skill's folder | | Provenance | The owner is who it claims to be, the repository is not archived, and the skill can be pinned to an exact tree | Open the repository; confirm the owner; note the commit and the tree hash you reviewed | | Supply chain | Nothing in the skill downloads and runs unpinned code, asks for credentials, or widens tool permissions without saying why | Read every script and every command in the text; run the security review if one is available | -| Correctness | Every example you read is right for the tool and version it names | Check the examples against the tool's own documentation or by running them. Read all of them for a small skill, and at least every example in the areas you will rely on for a large one | +| Correctness | Every example you read is right for the tool and version it names | Check the examples against the tool's own documentation or by running them. Read all of them when the skill is under about 300 lines in total, and at least every example in the areas you will rely on when it is larger | The correctness gate is the one most often skipped. A skill that reads well and is from a known vendor can still carry an example that is wrong in a way that only shows in production. -Fit is not correctness: read for both. +Fit is not correctness: read for both. An example you cannot run or check is unverified, and +counts against the gate unless it is inert in your setup. ## Scored (0 to 2 each) | Dimension | 0 | 1 | 2 | |---|---|---|---| | Functionality | Misses the gap in the brief | Covers part of it | Covers the acceptance scenarios | -| Maintenance | No change in a year, or issues unanswered | Occasional activity | Active, with releases or regular commits | +| Maintenance | Abandoned: reported defects go unanswered | Answered slowly, or one maintainer | Defects are answered and fixes are released | | Compatibility | Tied to one host or one hosted product you do not use | Works with caveats | Follows the open skill format and names no product you lack | | Test quality | No examples of expected behaviour | Examples only | Evaluation cases or tests upstream | | Upkeep | Large, changes often, or needs local patches | Moderate | Small, stable, used unmodified | -Add the description length in characters. Every listed skill costs every session some of its -skill-listing budget, so a long description needs a reason. +A skill that is finished and rarely changes is not abandoned: Maintenance is about whether +defects get fixed, not about how often the text moves. + +Record the description length in characters. Every listed skill costs every session some of +its skill-listing budget, so a description over about 400 characters needs a reason. ## Reading the result +The scores are there to make the comparison between candidates visible; they are not added up. +Any 0 needs a sentence in the decision record saying why it is acceptable or why it is not. + - **Adopt**: all gates pass and Functionality is 2. - **Adopt with known defects**: the gates pass except for defects in examples that are few, outside the areas you rely on, and that fail loudly (an error or an obvious wrong result, diff --git a/plugins/agentic-engineering/skills/skill-lifecycle/references/updates.md b/plugins/agentic-engineering/skills/skill-lifecycle/references/updates.md index d40a859..8e0d3ce 100644 --- a/plugins/agentic-engineering/skills/skill-lifecycle/references/updates.md +++ b/plugins/agentic-engineering/skills/skill-lifecycle/references/updates.md @@ -2,20 +2,39 @@ An update replaces instruction text that agents follow. Review the text, not the version. -1. **Find the two pins.** The tree hash the copy records now, and the one the update moves to. -2. **Read the exact difference** between those two trees, for every file in the skill. An - update tool's summary is not the diff. -3. **Read what upstream says changed**: the commits or release notes in that range. If - upstream publishes no notes, the commit list is the record. -4. **Look for breaking changes**: a renamed or removed command, a changed default, a new - requirement (a tool, a network call, a hosted service), or a narrower or wider description - that changes when the skill loads. -5. **Check the licence** in the new tree. A changed licence or a removed notice stops the - update until the record is corrected or the skill is dropped. -6. **Repeat the correctness read** for every example the update adds or changes. -7. **Run the repository's validation**, and try one acceptance scenario from the skill's - decision record against the new copy. -8. **Know the way back.** Rolling back is reverting the update, which restores the previous - pin. Say so in the review if anything is uncertain. +1. **Find the two pins.** The pin is the upstream tree hash the copy records: the exact content + that was reviewed. A recorded ref (a tag or a branch) is only how it was found, and can + move. Take the hash recorded before the update and the one it moves to, and when the ref is + a tag, confirm it still resolves to the recorded tree. +2. **Read the exact difference** between those two upstream trees, for every file in the skill. + An update tool's summary is not the diff. The installed copy never has the upstream hash + itself, because the installer adds its provenance to the frontmatter. So show that the copy + is the reviewed content another way: the change to the copy must equal the upstream + difference apart from those provenance lines. +3. **Read what upstream says changed**, limited to the skill's own path: the commits or release + notes in that range. A whole-repository range is mostly noise. Also read the release notes of + whatever the skill instructs agents to use (a tool, a server, a command), because that is + where a new requirement or a preview feature is announced. +4. **Look for breaking changes**: a renamed or removed command, a changed default, or a + narrower or wider description that changes when the skill loads. +5. **Check new requirements against your own setup.** If the update tells agents to use a tool, + a server option or a service, check whether your configuration provides it. An instruction + that cannot run here is inert: note it, and note what would switch it on. An instruction + that would run and do the wrong thing here is a defect. +6. **Check the licence.** It may sit at the root of the upstream repository, outside the + skill's folder: check the file your licence record points to, at the new commit. A changed + licence or a removed notice stops the update until the record is corrected or the skill is + dropped. +7. **Repeat the correctness read** for every example the update adds or changes. An example + you cannot run or check is unverified: say so, and accept it only when it is inert in your + setup. +8. **Run the repository's validation**, and try one acceptance scenario from the skill's + decision record against the new copy. A skill adopted before there was a record has none: + write two scenarios now and keep them with the review. +9. **Know the way back.** Rolling back is reverting the update, which restores the previous + pin. If an automatic updater would propose the same version again, pin the skill at the + reviewed tree until upstream moves on. -Hold the update when any step cannot be completed. An unread update is not a reviewed one. +Before merge, hold the update when any step cannot be completed: an unread update is not a +reviewed one. For an update that already merged, the result is one of two words, keep or +revert, with the steps above as the evidence. From b8d0badc35e3c8065867c02759dc20d93e81eb76 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Tue, 10 Nov 2026 21:50:10 +0100 Subject: [PATCH 3/4] docs(skill-lifecycle): state the correctness-gate exception and re-run the licence gate on a changed licence Two contradictions the review found: - The scorecard said any failed gate rejects a candidate, while the reading rules allow adopting with known defects. The gate rule now states that one narrow exception and points to its terms. - The update checklist let a changed licence through once the record was corrected. A changed licence is now a fresh licence gate: an update whose new terms forbid redistribution is refused. Part of #641 Co-Authored-By: Claude Fable 5.2 --- .../skills/skill-lifecycle/references/scorecard.md | 10 +++++++--- .../skills/skill-lifecycle/references/updates.md | 6 ++++-- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md b/plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md index f025ef0..23d8f04 100644 --- a/plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md +++ b/plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md @@ -1,7 +1,10 @@ # Adopt-or-build scorecard -Fill one scorecard per candidate. A candidate that fails any gate is rejected, whatever it -scores elsewhere. Write down what you looked at, not only the verdict: the next reader has to +Fill one scorecard per candidate. A candidate that fails the licence, provenance or supply-chain +gate is rejected, whatever it scores elsewhere. So is one that fails the correctness gate, with +one narrow exception: wrong examples that are few, outside the areas you rely on, and that fail +loudly can be accepted as known defects, on the terms under [Reading the result](#reading-the-result). +Write down what you looked at, not only the verdict: the next reader has to be able to check it. ## Gates (pass or fail) @@ -40,7 +43,8 @@ The scores are there to make the comparison between candidates visible; they are Any 0 needs a sentence in the decision record saying why it is acceptable or why it is not. - **Adopt**: all gates pass and Functionality is 2. -- **Adopt with known defects**: the gates pass except for defects in examples that are few, +- **Adopt with known defects**: the licence, provenance and supply-chain gates pass, and the + only correctness failures are defects in examples that are few, outside the areas you rely on, and that fail loudly (an error or an obvious wrong result, never a silent one). Name each defect where users read about the skill, and track the upstream fix. diff --git a/plugins/agentic-engineering/skills/skill-lifecycle/references/updates.md b/plugins/agentic-engineering/skills/skill-lifecycle/references/updates.md index 8e0d3ce..069ad34 100644 --- a/plugins/agentic-engineering/skills/skill-lifecycle/references/updates.md +++ b/plugins/agentic-engineering/skills/skill-lifecycle/references/updates.md @@ -23,8 +23,10 @@ An update replaces instruction text that agents follow. Review the text, not the that would run and do the wrong thing here is a defect. 6. **Check the licence.** It may sit at the root of the upstream repository, outside the skill's folder: check the file your licence record points to, at the new commit. A changed - licence or a removed notice stops the update until the record is corrected or the skill is - dropped. + licence is a new licence gate: read the new terms. If they still allow redistribution, + correct the record and keep the new notice with the copy. If they do not, refuse the update: + stay on the last tree released under terms you can redistribute, or drop the skill. A + removed or altered notice stops the update until the record matches what upstream ships. 7. **Repeat the correctness read** for every example the update adds or changes. An example you cannot run or check is unverified: say so, and accept it only when it is inert in your setup. From d2cd67636a3c1618116ce948c60b6513e73609fc Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Tue, 10 Nov 2026 21:50:29 +0100 Subject: [PATCH 4/4] docs(skill-lifecycle): make the reject rule agree with the stated exception Part of #641 Co-Authored-By: Claude Fable 5.2 --- .../skills/skill-lifecycle/references/scorecard.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md b/plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md index 23d8f04..47f5d12 100644 --- a/plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md +++ b/plugins/agentic-engineering/skills/skill-lifecycle/references/scorecard.md @@ -48,7 +48,8 @@ Any 0 needs a sentence in the decision record saying why it is acceptable or why outside the areas you rely on, and that fail loudly (an error or an obvious wrong result, never a silent one). Name each defect where users read about the skill, and track the upstream fix. -- **Reject**: a gate fails, or the defects are in the areas you rely on, or they fail silently +- **Reject**: the licence, provenance or supply-chain gate fails, or the wrong examples are + many, are in the areas you rely on, or fail silently (security rules, data loss, access control). - **Build**: no candidate can be adopted and the gap is still worth closing. Say why each candidate was rejected.