# @frontmcp/skills

Curated skills catalog for FrontMCP projects. Skills are SKILL.md-based instructional packages that teach AI agents how to perform multi-step tasks with FrontMCP.

> **v1.2.0 — new manifest fields:** `rating` (0..5), `category` override, and `requires: string[]` (skill dependencies). The Skills HTTP API exposes them as `min-rating`, `category`, and resolves `requires` topologically before registration. See [Skills Adapter](../../docs/frontmcp/adapters/skills-adapter.mdx) for the runtime contract.

## Structure

The catalog uses a **router skill model** — domain-scoped router skills, each containing a SKILL.md with a routing table, a `references/` directory with detailed topic guides, and optional `examples/` directories for standalone example files.

```text
catalog/
├── skills-manifest.json       # Machine-readable index of all skills
├── frontmcp-setup/            # Project setup, scaffolding, Nx, storage backends
├── frontmcp-development/      # Tools, resources, prompts, agents, providers, jobs, workflows, skills
├── frontmcp-deployment/       # Deploy to Node, Vercel, Lambda, Cloudflare; build for CLI, browser, SDK
├── frontmcp-testing/          # Testing with Jest and @frontmcp/testing
├── frontmcp-config/           # Transport, HTTP, throttle, elicitation, auth, sessions, storage
└── frontmcp-guides/           # End-to-end examples and best practices
```

Each router skill directory follows this format:

```
frontmcp-development/
├── SKILL.md          # Required: frontmatter + routing table + instructions
└── references/       # Reference files with detailed per-topic guides
    ├── create-tool.md
    ├── create-resource.md
    ├── create-agent.md
    └── ...
```

Example files live under `examples/<reference-name>/` and are the canonical source of example metadata used by `skills-manifest.json` and the reference `## Examples` tables.

## SKILL.md Frontmatter

```yaml
---
name: my-skill # Required: kebab-case, max 64 chars
description: What the skill does # Required: short description
tags: [setup, redis] # Optional: categorization tags
tools: # Optional: tool references
  - tool_name
  - name: detailed_tool
    purpose: Why this tool is used
    required: true
parameters: # Optional: input parameters
  - name: param_name
    description: What it controls
    type: string
    default: value
examples: # Optional: usage examples
  - scenario: When to use this
    expected-outcome: What happens
priority: 5 # Optional: search ranking weight
visibility: both # Optional: mcp | http | both
compatibility: Node.js 24+ # Optional: environment requirements
license: MIT # Optional: license
allowed-tools: Read Edit # Optional: pre-approved tools
rating: 4.5 # Optional (v1.2): 0..5 quality rating, surfaced via Skills HTTP API min-rating filter
category: development # Optional (v1.2): catalog category override (defaults to the directory's parent category)
requires: [frontmcp-setup] # Optional (v1.2): other skill names this depends on; resolver registers deps first
---
# Skill Instructions

Step-by-step markdown instructions here...
```

## Adding a New Skill

> **Important:** The canonical catalog model is 6 router skills with reference markdown. Do not create new top-level skill directories — add new content as reference files within the appropriate router skill.

1. Identify which router skill your content belongs to (setup, development, deployment, testing, config, or guides)
2. Create a new `.md` reference file in that router's `references/` directory
3. Add a routing entry in the router's `SKILL.md` routing table
4. Run `nx test skills` to validate

## Adding Example Files

Each reference may have a matching `examples/<reference-name>/` directory with standalone example files.

```yaml
---
name: example-name
reference: parent-reference-name
level: basic
description: One sentence describing the exact scenario this example covers.
tags: [keyword1, keyword2, keyword3]
features:
  - Concrete API or pattern this example demonstrates
  - Another concrete behavior shown in the code
---
```

Rules:

- `name` must match the filename without `.md`
- `reference` must match the parent examples directory
- `description` is the canonical one-line summary reused by the manifest and reference table
- `tags` are searchable keywords for the example
- `features` are the concrete APIs or patterns demonstrated by the code
- The first paragraph under the H1 should semantically match `description`

## Manifest Entry

Each router skill has a corresponding entry in `skills-manifest.json`:

```json
{
  "name": "frontmcp-development",
  "category": "development",
  "description": "Domain router for building MCP components",
  "path": "frontmcp-development",
  "targets": ["all"],
  "hasResources": true,
  "tags": ["router", "development", "tools", "resources"],
  "bundle": ["recommended", "minimal", "full"]
}
```

### Target Values

- `all` — applies to all deployment targets
- `node` — Node.js / Docker deployments
- `vercel` — Vercel serverless
- `lambda` — AWS Lambda
- `cloudflare` — Cloudflare Workers

### Bundle Values

- `recommended` — included in default scaffold
- `minimal` — included in minimal scaffold
- `full` — only in full scaffold

## Scaffold Integration

Skills are automatically included when scaffolding projects:

```bash
# CLI (default: recommended bundle)
frontmcp create my-app --skills recommended

# Nx server generator
nx g @frontmcp/nx:server my-server --skills recommended
```

## Validation

```bash
nx test skills
```

Tests verify:

- All SKILL.md files parse correctly
- Manifest entries match filesystem (no orphans)
- Names match between manifest and frontmatter
- `hasResources` flags are accurate
- Targets, categories, and bundles use valid values
- Example metadata stays in sync across example files, reference tables, and the manifest
