Skip to content
ModernizeSpec

@modernizespec/agent-skill

@modernizespec/agent-skill is a pre-packaged Agent Skill that installs the SKILL.md and supporting resources into your project. Skill-aware AI agents (Claude Code, Codex CLI, Cursor, VS Code) discover it automatically and load modernization context on demand.

Installation

Section titled “Installation”
Terminal window
npm install @modernizespec/agent-skill

This places files into .agents/skills/modernize/:

.agents/skills/modernize/
├── SKILL.md                      # Progressive disclosure metadata + instructions
└── resources/
    ├── extraction-checklist.md    # Step-by-step extraction guide
    ├── parity-test-template.md   # Template for writing parity tests
    └── ddd-mapping-guide.md      # How to identify bounded contexts

How It Works

Section titled “How It Works”
  1. Agent starts a session and discovers .agents/skills/modernize/SKILL.md
  2. Agent sees only the skill name and description (~100 tokens)
  3. User asks about modernization, migration, legacy code, extraction, or parity
  4. Agent loads the full skill body into context
  5. Skill instructions guide the agent to read the ModernizeSpec JSON files

What the Skill Contains

Section titled “What the Skill Contains”

SKILL.md

Section titled “SKILL.md”

The skill file includes:

  • Metadata — name, description, trigger keywords
  • Discovery instructions — which JSON files to read and in what order
  • Rules — constraints the agent must follow (e.g., never extract before dependencies)
  • Quick reference — common workflows for extraction safety, parity testing, and progress updates

Resources

Section titled “Resources”
ResourcePurpose
extraction-checklist.mdStep-by-step guide: verify dependencies, create ACL, extract module, run parity tests, update state
parity-test-template.mdTemplate for writing behavior-preservation tests with baseline comparison
ddd-mapping-guide.mdHow to identify bounded contexts from legacy code: module analysis, coupling assessment, entity grouping

Trigger Keywords

Section titled “Trigger Keywords”

The skill activates when users mention:

  • legacy — “How should I handle this legacy code?”
  • migration — “What is the migration status?”
  • modernize — “Modernize the payment module”
  • extract — “Extract the tax calculator”
  • parity — “Run parity tests for GL entry”

Relationship to Other Packages

Section titled “Relationship to Other Packages”
PackageWhen to Use
@modernizespec/agent-skillYou want AI agents to discover modernization context via skills
@modernizespec/sdkYou are building tools that read/write spec files programmatically
@modernizespec/coreYou only need TypeScript types and schemas

The agent-skill package does not depend on the SDK. It provides Markdown-based instructions that guide agents to read the JSON files directly.

Customization

Section titled “Customization”

After installation, you can edit SKILL.md and the resources to add project-specific instructions:

## Project-Specific Rules


- Our legacy system uses Django, not Frappe
- Tax calculation must be verified by a CA before marking as complete
- All extracted modules must pass integration tests against the staging database

Next Steps

Section titled “Next Steps”