Creating Skills | MigrateForce Documentation

File Structure

Each skill lives in its own directory:

skill-name/
├── SKILL.md          # Required — the skill definition
├── scripts/          # Optional — automation helpers
├── references/       # Optional — supporting docs
└── assets/           # Optional — templates, data

Minimal Example

---
name: mcp-openapi-normalize
description: Normalizes OpenAPI specs into MCP tool schemas. Use when ingesting REST APIs for MCP generation.
---

## Summary
Transforms a raw OpenAPI document into an MCP tool schema with deterministic naming and parameter mapping.

## Inputs
- OpenAPI spec (JSON or YAML)

## Outputs
- MCP tool schema
- Validation errors and warnings

Frontmatter Reference

Field	Required	Rules
name	Yes	1–64 chars, lowercase, hyphens only. Must match directory name.
description	Yes	1–1024 chars. Must describe what it does AND when to use it.
license	No	SPDX identifier (e.g., `MIT`)
compatibility	No	1–500 chars. Runtime requirements.
metadata	No	Key/value map. Common keys: `industry`, `complexity`, `value_driver`, `vendor`, `tags`.
allowed-tools	No	Space-delimited list of tools the skill may invoke.

Description is critical

Agents scan descriptions to decide which skill to activate. Bad: "A healthcare skill." Good: "Automates patient intake workflows. Use when migrating paper forms to AI-assisted digital processes."

Recommended Body Sections

Section	Purpose
Summary	What the skill does (1–3 sentences)
Trigger Conditions	When an agent should activate this skill
Inputs Required	Data/context the skill needs
Outputs	What the skill produces
Integration Points	Connected MCP tools and other skills
Constraints	Rules, compliance, limitations

Keep SKILL.md under ~500 lines. Move detailed reference material into references/.

Validate

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

Returns JSON with isValid, errors, and warnings. Exit code 0 for valid, 2 for errors.

Auto-Derive from MCP Tools

MigrateForce can generate skills automatically from your MCP tool mappings. Tools scoring above 60 on quality are considered auto-convertible.

# Via API
curl -X POST https://migrateforce.com/api/projects/$PROJECT_ID/derive-skills \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "quality_threshold": 60, "create_bundles": true }'

Publish

Skills can be published to the MigrateForce catalog through the web platform (Skills dashboard → New Skill Bundle) or the API. Community submissions go through review before appearing publicly.

Back: Using Skills — browse, install, and customize skills from the catalog.