Standardize research, adoption, pinning and authoring of agent skills

Goal

Establish a repeatable skill lifecycle so agents prefer high-quality upstream skills and only build first-party skills after rigorous research.

Required process

Define decision rubric: functionality, trusted provenance, license, maintenance, supply-chain security, compatibility, test quality and total upkeep.
Document immutable upstream pinning and updater PR review: exact diff, upstream changelog, breaking changes, license changes, test results, rollback. Integrate existing Bundled upstream skills: reviewable updates and clear redistribution terms #581, Updater PRs state what changed upstream for each moved skill #583 and Review and safely release the temporary git-commit upstream pin #598.
Audit and improve the existing skill-creation skill rather than assuming it is sufficient. Align with the current Agent Skills specification and relevant host conventions; enforce frontmatter, concise triggers, progressive disclosure, examples, references and test fixtures.
Require a research brief and acceptance scenarios before writing new first-party skills; record why third-party options were rejected.
Add CI validation/evaluation and periodic review of legal/technical sources.

Acceptance criteria

Documented adopt-versus-build decision record template and scorecard.
One demonstrated pinned third-party adoption/update workflow (or link to existing verified implementation).
One demonstrated first-party skill authored via the approved authoring skill and validated in CI.
Explicit non-duplication and ownership policy.

🔗 Related PRs

#619 - feat(skills): own maintained sources in their plugins [closed]
#590 - ci: scope engineering-practice skill updates [closed]
#613 - chore: adopt the Marketplace skill updater [merged]
#597 - fix(ci): preserve safe skill pins across update scopes [merged]

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

Create Plan

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

chore: agent-claim #641 nonce=4faee600f2885718979932ddccf8c32c

docs(skill-lifecycle): fold in what a first trial of the skill found

🤖 Generated by the Agentic Engineer (interactive Claude Code session)

Research brief

Gap. Nothing written says how a skill gets adopted, written or updated here, so each adoption works a procedure out again, and none of them required reading a candidate's examples for correctness.

Evidence. Two real cases this week. On #653 the first decision was made on fit, licence and maintenance alone; review of #673 then found wrong examples in the candidate's access-rule guidance and the decision had to be reversed. On #654 a correctness read still missed two wrong examples that review of #675 found.

Where it shows up. Every adoption from the coverage audit (#652, #653, #654), and updater pull requests such as #671, which merge on a green check without anyone reading what changed upstream.

Acceptance scenarios.

Should load: "Should we get a skill for Helm chart authoring into the plugin?" -> a research brief first, a check of what is already bundled, candidates scored with the correctness gate, and a decision record; no install before the decision.
Should load: "Review the update that moved context7-mcp in chore(deps): update agent skills (plugins/agentic-engineering/skills/context7-mcp) #671" -> the two pinned tree hashes, the exact difference between them, what upstream says changed, the licence in the new tree, and how to roll back.
Should load: "Write a skill for our release process" -> a check for an existing owner first, then the authoring rules, with the scenarios kept as test cases.
Near miss: "Find me a skill for X" -> find-skills (discovery only).
Near miss: "Is this skill safe to install?" -> check-skills (the security read).
Must not load: "Write the README for this repository."

Already covered by. find-skills finds and installs skills. check-skills reviews one for unsafe instructions before install. The host's own authoring tool drafts and evaluates. None of them decides whether to adopt or build, keeps a licence and a pin, or reviews an update.

Would something else fix it better? Partly, and that part already exists: CI checks the manifests, the licence records, the provenance and the skill format. A check cannot read an example for correctness, weigh candidates or decide what to leave out, so those need a written procedure.

Out of scope. The activation and adherence suite (#651), and making updater pull requests say what changed upstream (#583, under #581).

Decision record: build `skill-lifecycle`

Candidates.

Candidate	Owner and licence	Reviewed at	What it covers	Verdict
`find-skills`	vercel-labs/skills, MIT	the bundled copy (`v1.5.16`)	Discovering and installing skills	Keep as is. It is the discovery step, not the decision
`check-skills`	openai/codex-security, Apache-2.0	the bundled copy (`npm-v0.8.3`)	A read-only security review before install	Keep as is. It is the supply-chain gate, not the decision
`skill-creator`	anthropics/skills, Apache-2.0 (licence file in the skill)	`main`, last pushed 2026-11-06	Drafting a skill, running it against a baseline, optimising its description	Not bundled. Claude already provides it, it ships nine Python scripts and an evaluation viewer, and it has nothing on adopting, pinning, licences or updates. It is named as the drafting tool where the host has it
`writing-skills`	obra/superpowers, MIT	`main`, last pushed 2026-11-03	Test-first authoring of skills	Rejected. It overlaps the drafting tool above, leans on its own collection's workflow, and has nothing on adopting, pinning, licences or updates

What was read. For the two bundled skills, their descriptions and opening sections: both are already carried here and say plainly what they cover. For skill-creator (485 lines) and writing-skills (399 lines), the description, the full section outline and the file list of each, which is enough to see what they cover and what they leave out, and that the first ships Python scripts. No example of theirs was checked for correctness, and none needs to be: none of the four is adopted by this change.

Why build. The gap is this marketplace's own procedure plus rules that hold wherever a skill is adopted. No candidate covers it, and the two that come closest cover a different step. The new skill is small (about 100 lines and four short reference files), points to the three existing tools instead of repeating them, and holds nothing specific to this repository; the local commands and worked examples are in docs/skill-lifecycle.md.

Description cost. 346 characters added to the skill listing.

Acceptance scenarios. Tried in #677; the trial comment there has what happened for each.

What would change this decision. An upstream skill that covers adopt-or-build, pinning with a licence record and update review. Then this one is retired in the same change that adopts it.

🤖 Generated with Claude Code

docs(skill-lifecycle): state the correctness-gate exception and re-ru…

docs(skill-lifecycle): make the reject rule agree with the stated exc…

feat(agentic-engineering): add the skill-lifecycle skill and adoption…

🤖 Generated by the Agentic Engineer (interactive Claude Code session)

Closed by #677 (merged, released as agentic-engineering 7.4.0). Against the four acceptance criteria:

Decision record template and scorecard: in the new skill-lifecycle skill (references/decision-record.md and references/scorecard.md).
A demonstrated pinned adoption and update workflow: docs/skill-lifecycle.md links the worked examples (feat(agentic-engineering): bundle Grafana's PromQL and Prometheus skills #675 adopted, docs(coverage): record why the Supabase Postgres skill is not adopted #673 rejected after review, Report the PromQL skill's staleness and label-drop example defects upstream #676 known defects), and the trial on feat(agentic-engineering): add the skill-lifecycle skill and adoption guide #677 reviewed a real updater change (chore(deps): update agent skills (plugins/agentic-engineering/skills/context7-mcp) #671) with the new checklist.
A first-party skill authored under the approved rules and validated in CI: skill-lifecycle itself, with its research brief and decision record above and a trial by a fresh agent on feat(agentic-engineering): add the skill-lifecycle skill and adoption guide #677.
Non-duplication and ownership policy: in the skill and in docs/skill-lifecycle.md.

Three things the issue text asks for are not fully delivered, so nobody has to find that out later:

Anthropic's skill-creator was audited by outline only and not changed (it is upstream-owned). The guide names it as the drafting tool and layers this repository's rules on top. It was not used to draft skill-lifecycle and its evaluation loop was not run.
The authoring rules are written, not enforced. CI already validates the skill format, licences and provenance, but nothing checks the size, reference depth, description length or the presence of scenarios. Enforce the first-party skill authoring rules in CI #678 tracks that.
Evaluation in CI is the activation suite in Measure skill activation and adherence with a claude plugin eval suite #651, still open; and updater pull requests still do not say what changed upstream (Updater PRs state what changed upstream for each moved skill #583).

If "the approved authoring skill" was meant as running skill-creator end to end, reopen this and say so; that would be one more worked example, not a redesign.

🤖 Generated with Claude Code

Navigation Menu

Repository navigation

Standardize research, adoption, pinning and authoring of agent skills #641

Goal

Required process

Acceptance criteria

Research brief

Decision record: build `skill-lifecycle`

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Standardize research, adoption, pinning and authoring of agent skills #641

Description

Goal

Required process

Acceptance criteria

Activity

coderabbitai commented on Nov 4, 2026

devantler commented on Nov 10, 2026

Research brief

Decision record: build skill-lifecycle

devantler commented on Nov 10, 2026

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions

Decision record: build `skill-lifecycle`