extract-skills

name	extract-skills
description	Extract reusable, framework-agnostic skills from an agent codebase analysis report and generate registry-ready skill files. TRIGGER when: a full_report.md has been generated by `/analyze-agent-codebase` (Claude Code) or `@analyze-agent-codebase` (Cursor), the user runs `/extract-skills` (Claude Code) or `@extract-skills` (Cursor), the user asks to extract skills from an analysis.

Extract Skills

When to use this skill

Reads classified decisions from _analysis/full_report.md and transforms them into generic, framework-agnostic skill files ready for the skill registry.

Zero skills is a valid outcome. Not every codebase contains extractable patterns. Do not force extraction — it is better to report nothing than to produce generic noise.

Prerequisites

{CODEBASE_ROOT}/_analysis/full_report.md must exist. If it doesn't, stop immediately and tell the user to run /analyze-agent-codebase (Claude Code) or @analyze-agent-codebase (Cursor) first.

All output goes to {CODEBASE_ROOT}/_analysis/extracted_skills_codebase/.

Instructions

Phase 1: Locate and read Section 14

Do not read full_report.md in full — it is a concatenation of all cluster files and is large. Section 14 is the only input needed for extraction.

First check whether _analysis/synthesis.md exists:

test -f _analysis/synthesis.md && echo "EXISTS" || echo "NOT_FOUND"

If synthesis.md exists: read _analysis/synthesis.md directly. It is the source of Section 14 and is much smaller than the assembled report. Skip the grep step.

If synthesis.md does not exist: locate Section 14 in full_report.md without loading the whole file:

grep -n "SECTION 14" _analysis/full_report.md | head -1

Read full_report.md starting from the line number returned by grep to EOF. Do not read any content before that line.

Section 14 contains:

• 14A: Classified decisions (tagged UNIVERSAL, ENGINEERING, or FRAMEWORK-SPECIFIC)
• 14B: Anti-patterns (missing, disabled, or broken implementations)
• 14C: Design trade-offs (decision frameworks with context-dependent options)

Drop all FRAMEWORK-SPECIFIC decisions.

For remaining UNIVERSAL and ENGINEERING decisions, apply the "would you say this unprompted" test at the decision level, not the concept level:

• Drop if you would give the specific decision with its specific failure mode unprompted (e.g., "use environment variables for secrets," "add retry logic").
• Keep if you know the general concept but not the specific production decisions within it. Example: You know "LLM-as-judge" exists, but do not know that you need model diversity between judge and production model to avoid shared blind spots, or that evaluation scores should be written to tracing spans for regression detection.

The test is: "Would you produce this specific architectural decision, with this specific failure mode, without having seen a production system that learned it the hard way?" If no, keep it — even if the parent concept is well-known.

If no decisions survive filtering, stop here. Report to the user that no reusable skills were found in this codebase and explain briefly why (e.g., all decisions were framework-specific, or all were common knowledge you would produce unprompted). This is a perfectly valid outcome — not every codebase contains extractable skills.

Do not output a table or summary of kept/dropped decisions.

Phase 2: Check for existing extracted skills

Before grouping, read all existing skill directories under _analysis/extracted_skills_codebase/. For each, read the SKILL.md to extract its description field and key decisions.

For each surviving decision from Phase 1, check: is this decision substantially covered by an existing extracted skill? A decision is covered if:

• The existing skill's TRIGGER conditions would fire in the same situation, AND
• The existing skill's key decisions teach the same lesson at the same abstraction level

Mark covered decisions as Already extracted — skip and do not include them in Phase 3. Tell the user which decisions were skipped and which existing skill covers them.

If _analysis/extracted_skills_codebase/ is empty or doesn't exist, skip this phase.

Phase 3: Group into skills

Cluster the surviving decisions into coherent skills by theme. Each skill should be a single lesson a developer needs at a single moment. Skills fall into two types — both are valid:

• Problem-pattern skills: Solve a specific failure mode in agent systems (context overflow, prompt injection, race conditions). Named after the problem.
• Operational-methodology skills: Cover practices that most developers know they should do (evaluate agents, add observability, manage prompt versions) but where the specific how-to-do-it-right decisions are non-obvious and only learned through production experience. Named after the practice + the agent-specific pitfall it addresses.

Methodology skills must still pass the decision-level filter — "evaluate your agent" is noise, but "use a different model family as judge to avoid shared blind spots" is a keepable decision.

Signs you need to split:

• Two decisions would trigger at different points in development (one during initial design, one during production optimization)
• A developer could need one without needing the other
• The trigger conditions would be meaningfully different

How to incorporate 14B anti-patterns

Use 14B items as seeds, not content.

For each 14B item that belongs to a skill:

1. Ask: "What is the general failure mode this reveals?"
2. Generalize one level up — from this repo's specific gap to how this pattern commonly fails across codebases.
3. Write the anti-pattern at that generalized level.

Do not transcribe the repo's specific gap verbatim. The source item is evidence of a pattern — not the pattern itself.

If a 14B item doesn't map to any skill's domain, discard it.

How to incorporate 14C trade-offs

Incorporate 14C trade-offs as key decisions within the relevant skill. The "when to choose X over Y" framing is the decision. If a trade-off doesn't fit any skill, discard it.

Phase 4: Generate skill files

Before writing any files, first check for a cached session file:

cat _analysis/.meta 2>/dev/null

If _analysis/.meta exists, read author, repository, source_hash, and source from it. Set commit_date to today in DD-MM-YYYY format. Skip the rest of this block.

If the file does not exist, auto-detect:

git config user.name 2>/dev/null
git remote get-url origin 2>/dev/null
git rev-parse --short HEAD 2>/dev/null

Set automatically (no confirmation):

• author → git config user.name, or "unknown" if absent
• repository → last path segment of remote URL with .git stripped, or directory name if no remote
• source_hash → short hash from git rev-parse, or null if not a git repo
• commit_date → today in DD-MM-YYYY format
• category → suggested based on skill content; applied directly

Then ask the user:

"Is this an internal (your organization) or external (open-source) repo? If external, please provide the GitHub repo URL."

Do not proceed until the user answers.

Set source to internal or external <url> based on the answer.

Write _analysis/.meta:

author: {value}
repository: {value}
source_hash: {value}
source: {value}

For each skill, generate two files inside {CODEBASE_ROOT}/_analysis/extracted_skills_codebase/{skill-name}/:

plugin.json:

Read ~/.prism/schemas/plugin.schema.json for the authoritative field specification, required fields, valid category enum, and format patterns. Write one plugin.json per skill that validates against it.

SKILL.md:

Frontmatter contains only name and description. All registry metadata lives in plugin.json.

---
name: [pattern-name, no framework in the name]
description: "[One sentence: the problem this solves, stated universally]. TRIGGER when: [Situation a developer would recognize, no framework names],[Second trigger condition], [Third if needed]"
---

## Key Decisions

[Numbered list. Each item is 2-3 sentences max. First sentence
is the decision. Second sentence is what goes wrong if you
don't follow it. Third sentence (optional) is the nuance or
exception.]

## Anti-patterns

[Structured list. Each anti-pattern has three parts:
- **What**: The mistake (one sentence)
- **Why**: The causal chain (one sentence)
- **Symptom**: How it manifests in production — the bug
  report or alert that leads you here (one sentence)

Each one should describe a failure that takes more than
an hour to diagnose.]

## Structural Template

[Abstract pseudocode showing the architectural shape of
the solution. NOT implementation code — structural
relationships, data flow, and control flow decisions.

Language-agnostic. Framework-agnostic. Shows component
boundaries, function signatures, and decision points.

Keep to 15-30 lines. One template per skill.]

Output Rules

• Name skills after the problem, not the solution. A developer searching for help doesn't know the solution yet.
• Every sentence must fail the "would you say this unprompted" test. Generic best practices are noise.
• The DO NOT TRIGGER section is as important as the TRIGGER section. The most common failure mode for skills is triggering when they shouldn't.
• If a problem-pattern skill has fewer than 3 key decisions, it's probably too thin to exist. Merge it or discard it. Operational-methodology skills may have 2 high-impact decisions and still stand on their own — judge by decision weight, not count.
• If a skill has more than 7 key decisions, it's probably two skills. Split it.
• Structural templates encode architecture, not implementation. If the template could be copy-pasted into a project, it's too specific.
• No framework names in skill content. Not in decisions, not in anti-patterns, not in templates, not in plugin.json.

Error handling

• If full_report.md does not exist, fail immediately with a message to run /analyze-agent-codebase (Claude Code) or @analyze-agent-codebase (Cursor) first.
• If Section 14 is missing or empty, fall back to reading the full report and performing extraction + classification inline (Phases 1-2 become: extract from all sections, classify each decision).
• If fewer than 2 skills would be extracted, tell the user that the report does not contain enough reusable patterns to justify extraction. Write a brief summary explaining what was found and why it didn't qualify. Do not force extraction — zero skills is a valid result.