Integration Overview

ModernizeSpec provides three integration mechanisms for AI agents, from lightweight to deep. All three ship together. Choose based on your environment and needs.

Three Mechanisms Compared

Mechanism	Reliability	Setup	Agent Coverage	Data Direction
A. AGENTS.md	Probabilistic (LLM follows prose)	Zero — just add Markdown	Universal (all agents)	Read-only
B. Agent Skill	Probabilistic (LLM triggers skill)	Low — add SKILL.md	Wide (Claude, Codex, Cursor, VS Code)	Read-only
C. MCP Server	Deterministic (structured tool call)	Medium — run server process	MCP hosts (Claude, VS Code, ChatGPT)	Read + Write

How AI Agents Work

All coding agents (Claude Code, Copilot, Cursor, Codex CLI) use the same fundamental mechanism to load project-level instructions: they read Markdown files from disk and concatenate them into the LLM prompt. There is no plugin compilation, no module loading, no binary extension. The files are read as text, injected into context, and the LLM follows the instructions via its instruction-following capability.

This is called context injection — and it is probabilistic, not deterministic. The LLM reads the instructions and usually follows them, but there is no compile-time guarantee.

The MCP Server integration is the exception: it provides deterministic tool access via structured API calls.

Choosing Your Integration

Use Mechanism A: AGENTS.md Section

Add a ## Modernization Context section to your project’s AGENTS.md. Works with every AI coding agent today — Claude Code, Copilot, Cursor, Codex, Gemini CLI, Amp, Aider, Zed.

Zero setup. Zero dependencies.

Read the guide

Use Mechanism B: Agent Skill

Install the @modernizespec/agent-skill package. The skill loads on demand when the user asks about modernization, migration, or legacy code. Token-efficient — only loads when relevant.

Works with Claude Code, Codex CLI, Cursor, VS Code.

Read the guide

Use Mechanism C: MCP Server

Run @modernizespec/mcp-server as a local process. Agents call typed tools to query spec data and update migration progress. Deterministic and structured.

Works with Claude Code, Claude Desktop, VS Code, ChatGPT.

Read the guide

Recommended Strategy

Use all three together. They are not mutually exclusive:

Minimal (any agent):     Drop AGENTS.md section → works immediately
Standard (skill-aware):  Add Agent Skill package → progressive disclosure
Full (MCP-capable):      Run MCP server → deterministic tools + progress updates

The AGENTS.md section is always available as a fallback. The Agent Skill provides richer context when supported. The MCP Server provides deterministic access and the ability to write back to spec files (e.g., updating migration progress).

Mechanism A: AGENTS.md

Universal. Zero setup. Prose instructions that any agent reads at session start. Best for broad compatibility.

Learn more

Mechanism B: Agent Skill

Progressive disclosure. Loads only when relevant. Bundles resources. Cross-agent compatible.

Learn more

Mechanism C: MCP Server

Deterministic tool calls. Typed inputs and outputs. Read + write access to spec files.

Learn more