Skip to content
ModernizeSpec

Agent Skill Integration

Agent Skills are a standard for on-demand context loading. The agent sees only the skill name and description at session start (~100 tokens). When the user asks a modernization-related question, the full skill body loads into context.

Who Reads It

Section titled “Who Reads It”

Claude Code, Codex CLI, Cursor, VS Code — agents supporting the Agent Skills standard.

How It Works

Section titled “How It Works”

A SKILL.md file with metadata is discovered at session start. The agent sees the name and trigger keywords. When the user asks about modernization, legacy code, extraction, or parity testing, the full skill content loads.

Directory Structure

Section titled “Directory Structure”
.agents/skills/modernize/
├── SKILL.md              # Progressive disclosure: metadata + full instructions
└── resources/
    ├── extraction-checklist.md
    ├── parity-test-template.md
    └── ddd-mapping-guide.md

SKILL.md Template

Section titled “SKILL.md Template”
---
name: modernize
description: Legacy modernization context — bounded contexts, extraction plan, parity tests
triggers:
  - legacy
  - migration
  - modernize
  - extract
  - parity
---


# ModernizeSpec Agent Skill


When the user asks about modernization, migration, or legacy code extraction:


1. Read `.agents/modernization/manifest.json` to understand the project scope
2. Read `domains.json` to identify which bounded context owns the relevant code
3. Check `complexity.json` for extraction tier (Extract Now / Extract With Care / Defer)
4. Follow `extraction-plan.json` for sequencing constraints
5. Reference `parity-tests.json` before claiming behavioral equivalence


## Rules


- NEVER extract a module before its dependencies (check sequencing)
- ALWAYS run parity tests after modifying extracted code
- Flag God-classes (>2,000 LOC) for decomposition before extraction
- Update `migration-state.json` after completing work on any context


## Quick Reference


### Check Extraction Safety


Before extracting module X:
1. Open `extraction-plan.json`
2. Find X in `sequencing` array
3. Verify all prerequisites are marked "complete" in `migration-state.json`


### Run Parity Tests


1. Open `parity-tests.json`
2. Find the suite for the relevant context
3. Run the command in the `command` field
4. Verify results meet the `acceptance` thresholds


### Update Progress


After completing extraction work:
1. Update `migration-state.json` with new entity counts
2. Update parity test results
3. Resolve blockers if applicable

Installing the Package

Section titled “Installing the Package”
Terminal window
npm install @modernizespec/agent-skill

This places the SKILL.md and resources in the correct location within your project’s .agents/skills/ directory.

Trigger Keywords

Section titled “Trigger Keywords”

The skill activates when the user mentions these keywords:

KeywordExample User Query
legacy”How should I approach this legacy code?”
migration”What’s the migration status of the Accounts module?”
modernize”Modernize the payment entry module”
extract”Extract the tax calculator into the new system”
parity”Run parity tests for the GL entry module”

Strengths and Limitations

Section titled “Strengths and Limitations”
AspectDetail
StrengthToken-efficient — loads only when relevant
StrengthBundles resources (checklists, templates, guides)
StrengthCross-agent compatible (open standard)
LimitationProbabilistic activation (~56% invocation rate per Vercel eval data)
LimitationTrigger keywords help but do not guarantee activation
LimitationRead-only — agent cannot update spec files

Next Steps

Section titled “Next Steps”