npm package: @migrateforce/skills
Description: Skills library and SKILL.md specification for AI agent workflows. Turn domain knowledge into agent-executable capabilities.
Author: MigrateForce
Latest version: 0.1.0

# @migrateforce/skills

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

[![npm version](https://img.shields.io/npm/v/%40migrateforce%2Fskills)](https://www.npmjs.com/package/%40migrateforce%2Fskills)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## What Are Skills?

**Skills** are the atomic unit of agent knowledge. They follow the [Anthropic Agent Skills](https://github.com/anthropics/anthropic-cookbook) format — a markdown file (`SKILL.md`) with YAML frontmatter that tells AI agents **what** to do, **when** to activate, and **how** to execute.

```yaml
---
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

```bash
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.

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

### Find Skills

```bash
# 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

```bash
# 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

```bash
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

```typescript
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:

```typescript
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:

```typescript
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`](./spec/SKILL.md) for the full specification.

### Required Frontmatter

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

### Optional Frontmatter

```yaml
---
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:**
```bash
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:**
```bash
skills list migrateforce/migration-skills --json
```

**Skill detail extraction:**
```bash
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](https://tessl.io/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/`](./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](https://migrateforce.com). 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](https://github.com/sprotolabs/migrateforce-skills/blob/main/CONTRIBUTING.md).

### Adding Skills

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

## License

MIT