devantler · Nov 10, 2026 · Nov 10, 2026 · Nov 10, 2026 · Nov 10, 2026 · Nov 10, 2026
diff --git 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
@@ -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
@@ -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/<plugin>/skills/<skill>/` 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
@@ -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
@@ -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
@@ -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/<plugin>/skills/<skill>/`, 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 <owner>/<repo> <path-in-repo> --dir plugins/<plugin>/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 `## <owner>/<repo>` section with the copyright notice and licence text in
+   `plugins/<plugin>/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 <plugin> 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 <path> --pin <head> --dir <tmp>`), 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/<plugin>/skills/<skill>/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
@@ -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
@@ -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
@@ -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`: