| name | askit-capability-gap-analysis |
| description | Assesses a new agent capability against the capability matrix, the Standard, and every skill, subagent and command this plugin ships, then proposes a matrix update, a backlog entry or an ADR draft without implementing any of them. Use when deciding whether a new Claude Code, Cowork or Codex capability should be modelled or adopted, when analysing a capability gap after a survey reports one, or when checking which components were last verified against an older agent version. |
| metadata | {"version":"0.1.0","tier":"universal","audience":"advanced"} |
askit-capability-gap-analysis
Purpose
askit-capability-whats-new answers what shipped upstream. This skill answers the harder question: what does that mean for us?
Three separate things can be true of one finding, and conflating them is how a capability gets adopted for the wrong reason:
| Question | Owner |
|---|
| Does the capability matrix describe it? | this skill, directly |
| Should the Standard model it? | an ADR. This skill drafts; a human ratifies |
| Do our own components use or need it? | this skill, per component |
It owns foundation/synthesis/capability-matrix.md. askit-capability-advisor reads that file to advise an author; this skill is what keeps it true.
When to use
After a survey reports a capability finding; when deciding whether a new agent capability belongs in the Standard; when asking which components were last verified against an older agent version; or before a release that claims to be current with the vendors.
The one hard rule
This skill PROPOSES. A human ratifies.
It may update the capability matrix, because that is a description of the world and it owns it. It may not edit a check module, STANDARD.md, library.json, or vendor-claims.json.
One carve-out in component frontmatter, and only one: metadata.verified-against, on components this run actually assessed. references/component-staleness.md assigns that key to this skill by name and explains why it can belong to no other - a survey examines vendors rather than components, so a bulk stamp from a survey run asserts readings that never happened. Everything else in a component's frontmatter is still off limits. Stamping a version onto a component nobody re-read is the defect this key exists to prevent, so the carve-out is exactly as wide as "components you assessed" and no wider.
A capability finding is never itself a reason to add a check. The Standard grows only by ADR, with the warn-first burndown of STANDARD.md sec 7.7, and this repository has measured what happens when that order is skipped: a recommendation that looks obvious before measurement is overturned by measurement about as often as not.
Procedure
1. Take a finding from the survey record, and read the page it cites
Not the release note. If the finding carries no documentation reference it is a lead, not a finding - send it back.
2. Update the capability matrix first, because describing is not deciding
Does the matrix have a row for this component type, a column for this agent, and the right value? Fix it. This is the one output that needs no ADR, because the matrix records what agents do, not what this Standard requires.
Two standing obligations, both from the matrix's own audit:
- Every value carries the agent version it was confirmed against. The matrix claimed for a long time to be "pinned to specific agent versions" while recording no version anywhere, which is a currency claim with no currency evidence.
- Cowork is modelled, but deliberately NOT as a column.
U6 skips its computer: local-artifact scheme and U11 tolerates its managed-connector pattern, so the gate already accommodates an agent the matrix did not model. The matrix records that in prose rather than a column, because Cowork is not a plugin-distribution target the way Claude Code and Codex are, and the matrix owns that modelling decision. Do not add the column; report the gap and let an ADR move the boundary if it should move.
3. Ask the four questions in order, and stop at the first NO
a. Is the capability real and stable? A research preview, an alpha flag, or an unreleased entry is a watch item, not a gap. Record it and stop.
b. Is it plugin-distributable? The matrix's whole framing is what ships inside a distributed plugin. A capability that exists but cannot be shipped in a plugin belongs in the matrix's notes and nowhere else - the Codex subagent case is the standing example.
c. Does anything break, or become possible, for a plugin author? If neither, it is documentation. Say so and stop. Most findings stop here, and that is the skill working.
d. Does it touch a component type any TIER requires? Check foundation/synthesis/tier-basis.md. If yes, this is a tier question and not merely a matrix update, and it routes to an ADR rather than to an edit. Added 2026-08-20 (v1.16.0 W3), because until tier-basis.md existed there was no way to ask it: nothing recorded which vendor fact each boundary rested on, so a finding could change the ground under a tier with no artifact noticing.
Two ways this question comes back YES, and they need different handling. If the boundary's row is pinned, the finding may falsify a live claim - go read that claim's onChange. If the row reads unverified, the finding is landing on ground nothing was watching, and the proposal should say so plainly rather than quietly treating the new reading as a correction of an old one that was never recorded.
4. Only for a finding that survives all three: assess our own components
For each of skills/, agents/, commands/, _workflows/, .claude-plugin/marketplace.json and library.json, ask what the finding changes. Report per component, not in aggregate: "3 of 26 skills declare agent-targets including codex" is actionable; "some skills may be affected" is not.
Use metadata.verified-against (ADR 0054) where it is present, and treat its absence as unknown rather than as current. The staleness report is a list of components whose recorded agent version predates the finding - not a list of components that are wrong.
5. Measure before you recommend, or say that you did not
If a recommendation depends on how many components, plugins or skills are affected, count them before writing it down. This repository has overturned three of seven ratified recommendations on their own measurements, including one that would have failed 44.9 percent of 2342 measured skills and one that fired on 99.9 percent of 2068 descriptions.
If measuring is not practical, the proposal must say the number is unmeasured. An unmeasured proposal is still useful; an unmeasured proposal presented as measured is not.
6. Route each conclusion, and never to more than one place
| Conclusion | Goes to |
|---|
| the matrix was wrong or incomplete | the matrix, in this change |
| a vendor sentence is now quotable | a candidate claim for vendor-claims.json |
| it touches a component type a tier requires | a tier question: an ADR, plus the row in tier-basis.md |
| the Standard should model this | an ADR draft, following askit-decision |
| a component should adopt this | a backlog entry in docs/internal/backlog/enhancements.md |
| real, but nothing to do yet | the backlog, with the trigger condition that would change the answer |
That last row is the one people skip, and it is the most valuable. A finding filed as "not yet, because the measured population is zero" with a stated re-measurement trigger is a decision. The same finding filed as "no" is a decision nobody can revisit.
7. Stop
Open the ADR draft or the backlog entry for review. Do not implement it, do not add a check, do not bump a Standard version.
What this can and cannot do
It reliably reports what the matrix says, which components declare which agent-targets, and which carry a verified-against older than a finding. Those are lookups over tracked files.
It does not determine whether a capability is worth adopting - that is a judgment, and its output is a proposal a human ratifies. It cannot see a capability nobody surveyed. And it cannot tell you a component is broken, only that its recorded verification predates a change: absence of verified-against, or an old value, is a prompt to look, never a finding on its own.
Scope
One skill, one obligation: keep the distance between what the agents can do and what this repository models an answerable question. It does not discover findings (askit-capability-whats-new), advise an author (askit-capability-advisor), author the ADR's argument (askit-decision), grade a plugin (askit-evaluate), or cut a release (askit-release).
