@migrateforce/skills

Skills library, CLI, and SKILL.md specification for AI agent workflows. Find, install, validate, derive, and compose agent skills.

What Are Skills?

Skills are the atomic unit of agent knowledge. They follow the Anthropic Agent Skills format — a markdown file (SKILL.md) with YAML frontmatter that tells AI agents what to do, when to activate, and how to execute.

---
name: patient-intake-automation
description: Automates patient intake workflows. Use when migrating paper forms to AI-assisted digital processes.
metadata:
  industry: healthcare
  complexity: medium
---

## Summary
Transforms manual patient intake into an AI-assisted digital workflow.

## Trigger Conditions
Use when a healthcare practice has paper-based intake processes.

| Without Skills | With Skills | |----------------|-------------| | Agents have tools but no context | Agents have tools + knowledge | | "Here's an API endpoint" | "Here's why/when/how to use this endpoint" | | Manual prompt engineering | Composable, reusable context | | One-off implementations | Skills compound over time |

Installation

npm install @migrateforce/skills

This gives you both the library (for programmatic use) and the CLI (for terminal use).

CLI

The skills CLI finds, installs, and validates skills from GitHub repositories.

# Run directly (no install needed)
npx --yes --package @migrateforce/skills skills --help

Find Skills

# List all skills in a repository
skills list migrateforce/migration-skills

# Filter by metadata
skills list migrateforce/migration-skills --industry=healthcare
skills list migrateforce/migration-skills --complexity=medium --search="patient"

# JSON output for programmatic use
skills list migrateforce/migration-skills --json

# Token-optimized output for AI agents
skills list migrateforce/migration-skills --format=context

Install Skills

# Interactive multi-select
skills add migrateforce/migration-skills

# Install a specific skill
skills add migrateforce/migration-skills#patient-intake-automation

# Install from a branch
skills add migrateforce/migration-skills@develop

Skills are downloaded to ./skills/<slug>/SKILL.md in your project.

Validate Skills

skills validate ./skills/my-skill/SKILL.md

Returns a JSON validation report with errors and warnings.

CLI Options

| Flag | Description | |------|-------------| | --industry <slug> | Filter by industry | | --vendor <vendor> | Filter by vendor | | --complexity <level> | Filter by complexity (low, medium, high) | | --value-driver <value> | Filter by value driver | | --search <text> | Free-text search | | --skill <slug> | Show detail for a specific skill | | --json | JSON output | | --format context | Agent-optimized output (minimal tokens) | | --verbose | Debug output |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Error | | 2 | Validation failed | | 3 | No skills found |

Repository Format

The CLI reads from GitHub repositories with this structure:

your-skills-repo/
├── skills.json          # Optional manifest (faster than GraphQL)
└── skills/
    ├── skill-one/
    │   └── SKILL.md
    └── skill-two/
        └── SKILL.md

If skills.json is missing, the CLI falls back to GitHub GraphQL (requires GITHUB_TOKEN).

Library API

Validation

import { validateSkillMd, isValidSkillMd, parseSkillFrontmatter } from '@migrateforce/skills'

// Quick check
isValidSkillMd(content) // → boolean

// Detailed validation
const result = validateSkillMd(content)
// { isValid, errors, warnings, frontmatter }

// Parse frontmatter only
const { isValid, frontmatter } = parseSkillFrontmatter(content)
// { name, description, metadata, license, compatibility }

| Function | Description | |----------|-------------| | validateSkillMd(content, expectedName?) | Full validation with errors/warnings | | isValidSkillMd(content) | Quick boolean check | | parseSkillFrontmatter(content) | Extract YAML frontmatter | | extractSkillSummary(content) | Get name + description only |

Derivation

Generate skills from domain knowledge:

import { deriveSkillFromUseCase, deriveSkillsFromUseCases } from '@migrateforce/skills'

const skill = deriveSkillFromUseCase({
  id: 'uc-123',
  title: 'Patient Appointment Scheduling',
  description: 'Automate appointment booking and reminders',
  function_name: 'Operations',
  industry_name: 'Healthcare',
  segment_name: 'Dental',
  value_driver: 'Efficiency',
  complexity_level: 'Medium',
})

console.log(skill.skill_md)     // Generated SKILL.md content
console.log(skill.name)         // "patient-appointment-scheduling"
console.log(skill.source_type)  // "use_case"

| Function | Description | |----------|-------------| | generateSkillName(title, prefix?) | Create valid skill name from title | | deriveSkillFromUseCase(input) | Generate SKILL.md from use case | | deriveSkillFromWorkflowTemplate(input) | Generate SKILL.md from workflow | | deriveSkillsFromUseCases(inputs) | Batch derivation |

Composition

Combine skills with MCP tools into workflows:

import { composeWorkflow, generateAgentWorkflowDefinition } from '@migrateforce/skills'

const workflow = composeWorkflow(
  'Healthcare Migration',
  'Migrate patient data from legacy to modern system',
  skills,    // Array of SkillReference
  mcpTools,  // Array of MCPToolReference
  'Healthcare',
  'Dental'
)

// Generate Anthropic-compatible agent instructions
const instructions = generateAgentWorkflowDefinition(workflow)

| Function | Description | |----------|-------------| | composeWorkflow(name, desc, skills, tools, ...) | Create workflow from Skills + MCP | | generateAgentWorkflowDefinition(workflow) | Export for agent consumption | | validateComposedWorkflow(workflow) | Check workflow validity | | mergeWorkflows(w1, w2, name?, desc?) | Combine two workflows |

SKILL.md Specification

See spec/SKILL.md for the full specification.

Required Frontmatter

---
name: skill-name        # 1-64 chars, lowercase, hyphens only
description: ...        # 1-1024 chars, describe what + when
---

Optional Frontmatter

---
license: MIT
compatibility: Requires docker
metadata:
  author: your-name
  version: "1.0"
  industry: healthcare
  complexity: medium
  value_driver: cost_reduction
allowed-tools: Bash(git:*) Read
---

Name Rules

• 1-64 characters
• Lowercase letters, numbers, hyphens only
• No leading/trailing hyphens
• No consecutive hyphens (--)
• Must match directory name

For AI Agents

This package is designed for both human and agent consumption:

Agent discovery:

skills list migrateforce/migration-skills --format=context

AVAILABLE_MIGRATION_TOOLS:
- id: patient-intake-automation (Automates patient intake workflows.)
INSTRUCTIONS: Use "skills add migrateforce/repo#<id>" to install.

Programmatic access:

skills list migrateforce/migration-skills --json

Skill detail extraction:

skills list migrateforce/migration-skills --skill=patient-intake-automation --json

Tessl Compatibility

Skills created with this library follow the Anthropic Agent Skills specification, the same format used by the Tessl Registry. A SKILL.md produced here can be published to Tessl via tessl skill publish and consumed by any Tessl-compatible agent.

Examples

See examples/ for sample skills:

• mcp-openapi-normalize — REST→MCP normalization skill

Integration with MigrateForce Platform

This package is the standalone skills library extracted from MigrateForce. The full platform adds:

• Web-based skills catalog and discovery
• MCP server generation from OpenAPI specs
• Assessment engine with ROI calculations
• Workflow export to LangGraph, CrewAI, AutoGen
• Enterprise features (SSO, audit, tenant isolation)

Contributing

We welcome contributions. See the Contributing Guide.

Adding Skills

1. Create a directory: examples/your-skill-name/
2. Add SKILL.md following the spec
3. Validate: skills validate examples/your-skill-name/SKILL.md
4. Submit a PR

License

MIT