AI Skill Report Card
Managing Skill Registry
Skill Registry Agent
Quick Start13 / 15
Given a set of skills/capabilities (files, modules, agent definitions, APIs), produce three artifacts:
- Skill Matrix — inventory of capabilities with metadata
- Dependency Tree — what depends on what
- Capability Report — narrative summary, gaps, versioning notes
Input: /skills directory with 12 skill files
Output:
Skill Matrix (table of 12 rows)
Dependency Tree (hierarchical graph)
Capability Report (coverage, overlaps, gaps, version drift)
Recommendation▾
Add a fully worked example with actual output tables filled in (not just descriptions of what the output would contain) for at least one scenario
Workflow14 / 15
Progress:
- Step 1: Discover — enumerate all skills/capabilities from source (files, registry, docs)
- Step 2: Extract metadata — name, purpose, version, inputs/outputs, triggers
- Step 3: Map dependencies — which skills call/require/extend other skills or external tools
- Step 4: Version — assign or read semantic version; flag stale/deprecated/duplicate skills
- Step 5: Build Skill Matrix table
- Step 6: Build Dependency Tree
- Step 7: Write Capability Report (gaps, overlaps, risks, recommendations)
Step details
Discovery: Scan the given source exhaustively. Don't skip skills that look trivial or undocumented — flag undocumented ones explicitly rather than omitting them.
Metadata extraction: For each skill capture:
id(unique slug)namecategoryversion(use0.0.0-unversionedif none found)status(active / deprecated / experimental)triggers(when it's invoked)dependencies(other skills, libraries, external APIs)
Dependency mapping: Build edges as A → B meaning "A requires/calls B". Detect cycles and flag them as errors, not silent omissions.
Versioning: If no version present, infer maturity from last-modified date or complexity; mark inferred values as (inferred).
Recommendation▾
Include guidance on handling very large skill sets (100+ skills) where full matrix/tree output may be impractical
Output Format
Skill Matrix
| ID | Name | Category | Version | Status | Triggers | Dependencies |
|---|---|---|---|---|---|---|
| skl-01 | writing-proposals | Content | 1.2.0 | active | "write a proposal" | none |
| skl-02 | reviewing-code | Engineering | 0.9.0 | experimental | "review this PR" | skl-07 (linting) |
Dependency Tree
skl-02 reviewing-code
└── skl-07 linting-code
└── external: eslint-api
skl-05 deploying-service
├── skl-02 reviewing-code
└── skl-09 running-tests
Capability Report
Summary
- Total skills discovered: N
- Active: X | Experimental: Y | Deprecated: Z
- Unversioned/undocumented: N
Gaps
- No skill covers [capability area]
Overlaps / Redundancy
- skl-03 and skl-11 both handle [X] — consider merging
Dependency Risks
- Circular dependency: skl-04 → skl-06 → skl-04
- skl-08 depends on deprecated skl-02-legacy
Recommendations
- Bump skl-07 to 1.0.0 (stable, in production use)
- Deprecate skl-11 in favor of skl-03
Examples14 / 20
Example 1:
Input: "Here are 3 agent skill files: writing-proposals.md (has frontmatter, v1.0), code-review.md (no version), code-review-v2.md (v2.0, overlaps with code-review.md)."
Output:
- Skill Matrix listing all 3 with
code-review.mdmarked0.0.0-unversioned (inferred: legacy) - Dependency Tree shows no cross-dependencies (flat)
- Capability Report flags: overlap between
code-review.mdandcode-review-v2.md, recommends deprecating the older one and assigning itstatus: deprecated
Example 2: Input: "Agent has skills: data-ingestion → data-cleaning → data-analysis → report-generation, plus a standalone chatbot skill."
Output:
- Skill Matrix: 5 rows, all active
- Dependency Tree: linear chain for the pipeline, chatbot skill shown as isolated node
- Capability Report notes single point of failure (linear chain, no parallelism) and no fallback if data-ingestion fails
Recommendation▾
Clarify how to handle ambiguous trigger overlaps beyond just 'recommend consolidation' — e.g., a decision framework for merge vs. keep-separate
Best Practices
- Always produce all three artifacts together — they cross-reference each other.
- Flag undocumented/unversioned capabilities rather than silently defaulting them.
- Treat circular dependencies as a hard flag, never suppress them.
- Prefer semantic versioning (
MAJOR.MINOR.PATCH); mark inferred versions clearly. - When skills overlap significantly, recommend consolidation instead of just listing both.
Common Pitfalls
- Don't guess dependencies without evidence — mark as
unknownif unclear. - Don't omit deprecated or broken skills from the matrix; mark their status instead of hiding them.
- Don't flatten the dependency tree into a list — preserve hierarchy/direction.
- Don't skip the Capability Report's gap analysis — an inventory without gaps/risks is incomplete.