Using Skills | MigrateForce Documentation | MigrateForce Documentation

What Are Skills?

A skill is a markdown file (SKILL.md) with YAML frontmatter that tells an AI agent what to do, when to do it, and how to execute it. Skills follow the Anthropic Agent Skills specification.

Think of it this way: an MCP tool exposes an action (create_patient_record). A skill provides the domain context around it — when should this tool be called, what data does it need, what compliance rules apply, what happens if it fails.

	Skills	MCP Tools
Format	Markdown (SKILL.md)	JSON-RPC endpoints
Contains	Instructions, constraints, examples	Tool schemas, input/output types
Purpose	Knowledge, context, playbooks	Actions, API calls
Used by	Agent planning/reasoning	Agent execution
Analogy	"The recipe"	"The kitchen tools"

When to Use Skills

Your MCP tools work but agents use them wrong

The agent calls create_order without first checking inventory. A skill adds the sequencing logic: "Always call check_stock before create_order."

Your domain has compliance rules

Healthcare API? HIPAA constraints, insurance verification steps, and data handling rules belong in a skill, not hardcoded into tool descriptions.

You want to share knowledge across projects

A "CRM data sync" skill works with any CRM API converted to MCP, not just yours. Skills are portable.

Tool descriptions aren't enough context

MCP tool descriptions are limited — a sentence or two. Skills provide multi-paragraph context with examples, constraints, and integration notes.

When you DON'T need a skill

If your MCP server has 3–5 tools with obvious semantics (get_user, create_user, delete_user), tool descriptions are probably enough. Skills add value when tool usage requires domain knowledge, sequencing, or constraints that aren't obvious from the schema alone.

Browse and Install

Browse the catalog

# List all available skills
npx @migrateforce/cli skills list migrateforce/migration-skills

# Filter by industry
npx @migrateforce/cli skills list migrateforce/migration-skills --industry=healthcare

# Filter by complexity
npx @migrateforce/cli skills list migrateforce/migration-skills --complexity=medium

# Search by keyword
npx @migrateforce/cli skills list migrateforce/migration-skills --search="patient"

Install a skill

# Install a specific skill into your project
npx @migrateforce/cli skills add migrateforce/migration-skills#mcp-openapi-normalize

# Interactive selection (multi-select TUI)
npx @migrateforce/cli skills add migrateforce/migration-skills

Skills are installed to ./skills/<name>/SKILL.md in your project. Point your agent at this directory and it will discover and use the skills automatically.

Cloud skill matching

When you convert with --cloud, the API automatically matches your spec against the skill catalog and suggests relevant skills. You don't have to browse manually.

npx @migrateforce/cli convert --spec api.yaml --base-url https://api.example.com --cloud

# Output includes:
#   Matched Skills:
#     • patient-intake-automation — Automates patient intake workflows
#     • hipaa-compliance-check — Validates HIPAA requirements

When to Customize a Skill

Installed skills are just markdown files. You own them. Here are the situations where customization makes sense:

Add your specific tool names

A catalog skill references generic tool names (create_patient_record). Your MCP server might use add_new_patient. Edit the Integration Points section to match your actual tool names.

Tighten constraints

A generic CRM skill might not mention your company's data retention policy. Add it to the Constraints section.

Add domain-specific trigger conditions

The catalog skill says "activate when migrating paper forms." Your use case is narrower — "activate when the user mentions dental intake forms specifically."

Remove irrelevant sections

A skill might cover 5 integration points. You only use 2. Delete the rest — agents work better with less noise.

Don't over-customize

If you find yourself rewriting more than 50% of a skill, you probably need a new skill, not a customized one. See Creating Skills.

When to Create Your Own Skill

Create a new skill from scratch when:

• No catalog skill covers your domain (niche industry, proprietary workflow)

• You need to encode company-specific SOPs that no public skill would have

• You're building a multi-step workflow that orchestrates 5+ tools in a specific sequence

• You want to publish a skill for your team or the community

The Creating Skills guide covers the SKILL.md format, frontmatter reference, validation, and publishing.

Example: Skill + MCP Together

Imagine you converted a healthcare scheduling API to an MCP server. You have tools like list_appointments, create_appointment, and verify_insurance.

Without a skill, an agent might call create_appointment directly — skipping insurance verification. With the patient-intake-automation skill installed, the agent knows:

## Constraints

- Insurance verification must happen BEFORE appointment confirmation
- All patient data must be encrypted in transit and at rest
- Fallback to manual process if EHR API is unavailable

## Integration Points

This skill pairs with these MCP tools:
- `create_appointment` — Creates new appointment in EHR
- `verify_insurance` — Checks insurance eligibility (MUST be called first)
- `list_appointments` — Shows available slots

Now the agent has the domain knowledge to use the tools correctly. The tools are the mechanism. The skill is the judgment.

Validate a Skill

Whether you installed or authored a skill, validate it before use:

npx @migrateforce/cli skills validate ./skills/my-skill/SKILL.md

The validator checks name format, description quality, frontmatter structure, and recommended sections. It exits with code 0 for valid, 2 for errors.

Next: Creating Skills from scratch — SKILL.md format, frontmatter reference, automated derivation from MCP tools, and publishing to the catalog.