@frontmcp/skills 0.0.1 → 1.0.0-beta.9

package/catalog/frontmcp-guides/references/example-weather-api.md

@@ -0,0 +1,292 @@
+# Example: Weather API (Beginner)
+
+> Skills used: setup-project, create-tool, create-resource, setup-testing, deploy-to-node
+
+A complete beginner MCP server that exposes a weather lookup tool and a static resource listing supported cities. Demonstrates server setup, Zod input/output schemas, `this.fetch()` for HTTP calls, `this.fail()` for error handling, and both unit and E2E tests.
+
+---
+
+## Project Setup
+
+```jsonc
+// package.json
+{
+  "name": "weather-api",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build": "frontmcp build",
+    "start": "frontmcp start",
+    "test": "jest --coverage",
+  },
+  "dependencies": {
+    "@frontmcp/sdk": "^1.0.0",
+    "zod": "^3.23.0",
+  },
+  "devDependencies": {
+    "@frontmcp/testing": "^1.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.4.0",
+  },
+}
+```
+
+---
+
+## Server Entry Point
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { WeatherApp } from './weather.app';
+
+@FrontMcp({
+  info: { name: 'weather-api', version: '1.0.0' },
+  apps: [WeatherApp],
+})
+export default class WeatherServer {}
+```
+
+---
+
+## App Registration
+
+```typescript
+// src/weather.app.ts
+import { App } from '@frontmcp/sdk';
+import { GetWeatherTool } from './tools/get-weather.tool';
+import { CitiesResource } from './resources/cities.resource';
+
+@App({
+  name: 'Weather',
+  description: 'Weather lookup tools and city data',
+  tools: [GetWeatherTool],
+  resources: [CitiesResource],
+})
+export class WeatherApp {}
+```
+
+---
+
+## Tool: Get Weather
+
+```typescript
+// src/tools/get-weather.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'get_weather',
+  description: 'Get current weather for a city',
+  inputSchema: {
+    city: z.string().min(1).describe('City name'),
+    units: z.enum(['celsius', 'fahrenheit']).default('celsius').describe('Temperature units'),
+  },
+  outputSchema: {
+    temperature: z.number(),
+    condition: z.string(),
+    humidity: z.number(),
+    city: z.string(),
+  },
+})
+export class GetWeatherTool extends ToolContext {
+  async execute(input: { city: string; units: 'celsius' | 'fahrenheit' }) {
+    const url = `https://api.weather.example.com/v1/current?city=${encodeURIComponent(input.city)}&units=${input.units}`;
+
+    let response: Response;
+    try {
+      response = await this.fetch(url);
+    } catch (err) {
+      this.fail(new Error(`Weather API unreachable: ${String(err)}`));
+    }
+
+    if (!response.ok) {
+      this.fail(new Error(`Weather API error: ${response.status} ${response.statusText}`));
+    }
+
+    const data = await response.json();
+
+    return {
+      temperature: data.temp,
+      condition: data.condition,
+      humidity: data.humidity,
+      city: input.city,
+    };
+  }
+}
+```
+
+---
+
+## Resource: Supported Cities
+
+```typescript
+// src/resources/cities.resource.ts
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+
+const SUPPORTED_CITIES = ['London', 'Tokyo', 'New York', 'Paris', 'Sydney', 'Berlin', 'Toronto', 'Mumbai'];
+
+@Resource({
+  uri: 'weather://cities',
+  name: 'Supported Cities',
+  description: 'List of cities with available weather data',
+  mimeType: 'application/json',
+})
+export class CitiesResource extends ResourceContext {
+  async read() {
+    return JSON.stringify(SUPPORTED_CITIES);
+  }
+}
+```
+
+---
+
+## Unit Test: GetWeatherTool
+
+```typescript
+// test/get-weather.tool.spec.ts
+import { ToolContext } from '@frontmcp/sdk';
+import { GetWeatherTool } from '../src/tools/get-weather.tool';
+
+describe('GetWeatherTool', () => {
+  let tool: GetWeatherTool;
+
+  beforeEach(() => {
+    tool = new GetWeatherTool();
+  });
+
+  it('should return weather data for a valid city', async () => {
+    const mockResponse = {
+      ok: true,
+      json: async () => ({
+        temp: 22,
+        condition: 'Sunny',
+        humidity: 45,
+      }),
+    } as unknown as Response;
+
+    const ctx = {
+      fetch: jest.fn().mockResolvedValue(mockResponse),
+      fail: jest.fn((err: Error) => {
+        throw err;
+      }),
+      mark: jest.fn(),
+      get: jest.fn(),
+      tryGet: jest.fn(),
+      notify: jest.fn(),
+      respondProgress: jest.fn(),
+    } as unknown as ToolContext;
+    Object.assign(tool, ctx);
+
+    const result = await tool.execute({ city: 'London', units: 'celsius' });
+
+    expect(result).toEqual({
+      temperature: 22,
+      condition: 'Sunny',
+      humidity: 45,
+      city: 'London',
+    });
+    expect(ctx.fetch).toHaveBeenCalledWith(expect.stringContaining('city=London'));
+  });
+
+  it('should fail when city is empty (Zod validation)', () => {
+    const { z } = require('zod');
+    const schema = z.object({
+      city: z.string().min(1),
+      units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
+    });
+
+    expect(() => schema.parse({ city: '' })).toThrow();
+  });
+
+  it('should fail when the weather API returns an error', async () => {
+    const mockResponse = {
+      ok: false,
+      status: 404,
+      statusText: 'Not Found',
+    } as unknown as Response;
+
+    const failFn = jest.fn((err: Error) => {
+      throw err;
+    });
+    const ctx = {
+      fetch: jest.fn().mockResolvedValue(mockResponse),
+      fail: failFn,
+      mark: jest.fn(),
+      get: jest.fn(),
+      tryGet: jest.fn(),
+      notify: jest.fn(),
+      respondProgress: jest.fn(),
+    } as unknown as ToolContext;
+    Object.assign(tool, ctx);
+
+    await expect(tool.execute({ city: 'Atlantis', units: 'celsius' })).rejects.toThrow(
+      'Weather API error: 404 Not Found',
+    );
+
+    expect(failFn).toHaveBeenCalled();
+  });
+});
+```
+
+---
+
+## E2E Test: Weather Server
+
+```typescript
+// test/weather.e2e.spec.ts
+import { McpTestClient, TestServer } from '@frontmcp/testing';
+import Server from '../src/main';
+
+describe('Weather Server E2E', () => {
+  let client: McpTestClient;
+  let server: TestServer;
+
+  beforeAll(async () => {
+    server = await TestServer.start({ command: 'npx tsx src/main.ts' });
+    client = await McpTestClient.create({ baseUrl: server.info.baseUrl }).buildAndConnect();
+  });
+
+  afterAll(async () => {
+    await client.disconnect();
+    await server.stop();
+  });
+
+  it('should list tools including get_weather', async () => {
+    const { tools } = await client.listTools();
+
+    expect(tools.length).toBeGreaterThan(0);
+    expect(tools).toContainTool('get_weather');
+  });
+
+  it('should call get_weather with a valid city', async () => {
+    const result = await client.callTool('get_weather', {
+      city: 'London',
+      units: 'celsius',
+    });
+
+    expect(result).toBeSuccessful();
+    expect(result.content[0].text).toBeDefined();
+
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed).toHaveProperty('temperature');
+    expect(parsed).toHaveProperty('condition');
+    expect(parsed).toHaveProperty('humidity');
+    expect(parsed).toHaveProperty('city', 'London');
+  });
+
+  it('should read the cities resource', async () => {
+    const { resources } = await client.listResources();
+    const citiesResource = resources.find((r) => r.uri === 'weather://cities');
+    expect(citiesResource).toBeDefined();
+
+    const result = await client.readResource('weather://cities');
+    const cities = JSON.parse(result.contents[0].text);
+
+    expect(Array.isArray(cities)).toBe(true);
+    expect(cities).toContain('London');
+    expect(cities).toContain('Tokyo');
+  });
+});
+```

package/catalog/frontmcp-setup/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: frontmcp-setup
+description: "Domain router for project setup and scaffolding \u2014 new projects, project structure, Nx workspaces, storage backends, multi-app composition, and the skills system. Use when starting or organizing a FrontMCP project."
+tags: [router, setup, scaffold, project, nx, redis, sqlite, structure, guide]
+priority: 10
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/getting-started/quickstart
+---
+
+# FrontMCP Setup Router
+
+Entry point for project setup and scaffolding. This skill helps you find the right setup guide based on your project needs — from initial scaffolding to storage backends, project structure, and multi-app composition.
+
+## When to Use This Skill
+
+### Must Use
+
+- Starting a new FrontMCP project from scratch and need to choose between standalone vs Nx monorepo
+- Setting up storage backends (Redis, SQLite) for session or state management
+- Organizing an existing project and need canonical directory layout guidance
+
+### Recommended
+
+- Onboarding to the FrontMCP project structure and naming conventions
+- Setting up multi-app composition within a single server
+- Understanding the skills system and how to browse, install, and manage skills
+
+### Skip When
+
+- You need to build specific components like tools or resources (see `frontmcp-development`)
+- You need to configure transport, auth, or throttling (see `frontmcp-config`)
+- You need to deploy or build for a target platform (see `frontmcp-deployment`)
+
+> **Decision:** Use this skill when you need to CREATE or ORGANIZE a project. Use other routers when you need to build, configure, deploy, or test.
+
+## Prerequisites
+
+- Node.js 22+ and npm/yarn installed
+- `frontmcp` CLI available globally (`npm install -g frontmcp`)
+
+## Steps
+
+1. Use the Scenario Routing Table below to find the right setup guide for your task
+2. Scaffold your project with `frontmcp create` (standalone) or `frontmcp create --nx` (monorepo)
+3. Configure storage and project structure per the relevant reference files
+4. Follow the Recommended Reading Order for a complete setup walkthrough
+
+## Scenario Routing Table
+
+| Scenario                                      | Reference                                    | Description                                                            |
+| --------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------- |
+| Scaffold a new project with `frontmcp create` | `references/setup-project.md`                | CLI scaffolder, manual setup, deployment-specific config               |
+| Organize a standalone (non-Nx) project        | `references/project-structure-standalone.md` | File layout, naming conventions (`<name>.<type>.ts`), folder hierarchy |
+| Organize an Nx monorepo                       | `references/project-structure-nx.md`         | apps/, libs/, servers/ layout, generators, dependency rules            |
+| Set up Redis for production storage           | `references/setup-redis.md`                  | Docker Redis, Vercel KV, pub/sub for subscriptions                     |
+| Set up SQLite for local development           | `references/setup-sqlite.md`                 | WAL mode, migration helpers, encryption                                |
+| Compose multiple apps into one server         | `references/multi-app-composition.md`        | `@FrontMcp` with multiple `@App` classes, cross-app providers          |
+| Use Nx build, test, and CI commands           | `references/nx-workflow.md`                  | `nx build`, `nx test`, `nx run-many`, caching, affected commands       |
+| Browse, install, and manage skills            | `references/frontmcp-skills-usage.md`        | CLI commands, bundles, categories, search                              |
+
+## Recommended Reading Order
+
+1. **`references/setup-project.md`** — Start here for any new project
+2. **`references/project-structure-standalone.md`** or **`references/project-structure-nx.md`** — Choose your layout
+3. **`references/setup-redis.md`** or **`references/setup-sqlite.md`** — Add storage if needed
+4. **`references/multi-app-composition.md`** — Scale to multiple apps (when needed)
+5. **`references/nx-workflow.md`** — Nx-specific build and CI commands (if using Nx)
+6. **`references/frontmcp-skills-usage.md`** — Learn the skills system
+
+## Cross-Cutting Patterns
+
+| Pattern        | Rule                                                                             |
+| -------------- | -------------------------------------------------------------------------------- |
+| Project type   | Standalone for single-app projects; Nx for multi-app or team projects            |
+| File naming    | `<name>.<type>.ts` (e.g., `fetch-weather.tool.ts`) everywhere                    |
+| Test naming    | `.spec.ts` extension (not `.test.ts`)                                            |
+| Entry point    | `main.ts` must `export default` the `@FrontMcp` class                            |
+| Storage choice | Redis for production/serverless; SQLite for local dev/CLI; memory for tests only |
+| App boundaries | Each `@App` is a self-contained module; shared logic goes in providers           |
+
+## Common Patterns
+
+| Pattern               | Correct                                         | Incorrect                                    | Why                                                               |
+| --------------------- | ----------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------- |
+| Project scaffolding   | `frontmcp create` or `frontmcp create --nx`     | Manual setup from scratch                    | CLI sets up correct structure, dependencies, and config files     |
+| Entry point           | `export default class MyServer` in `main.ts`    | Named export or no default export            | FrontMCP loads the default export at startup                      |
+| Storage in production | Redis or platform-native (Vercel KV, DynamoDB)  | Memory store or SQLite                       | Memory is lost on restart; SQLite doesn't work on serverless      |
+| Multi-app composition | Separate `@App` classes composed in `@FrontMcp` | One giant `@App` with all components         | Separate apps enable independent testing and modular architecture |
+| File organization     | Feature folders for 10+ components              | Flat `tools/` directory with dozens of files | Feature folders make domain boundaries visible                    |
+
+## Verification Checklist
+
+### Project Structure
+
+- [ ] `main.ts` exists with `export default` of `@FrontMcp` class
+- [ ] At least one `@App` class registered in the server
+- [ ] Files follow `<name>.<type>.ts` naming convention
+- [ ] Test files use `.spec.ts` extension
+
+### Storage
+
+- [ ] Storage backend chosen and configured (Redis/SQLite/memory)
+- [ ] Connection string in environment variables, not hardcoded
+- [ ] Storage accessible from the server process
+
+### Build and Dev
+
+- [ ] `frontmcp dev` starts successfully with file watching
+- [ ] `frontmcp build --target <target>` completes without errors
+- [ ] Tests pass with `jest` or `nx test`
+
+## Troubleshooting
+
+| Problem                  | Cause                            | Solution                                                              |
+| ------------------------ | -------------------------------- | --------------------------------------------------------------------- |
+| `frontmcp create` fails  | Missing Node.js 22+ or npm/yarn  | Install Node.js 22+ and ensure npm/yarn is available                  |
+| Server fails to start    | `main.ts` missing default export | Add `export default MyServerClass` to `main.ts`                       |
+| Redis connection refused | Redis not running or wrong URL   | Start Redis (`docker compose up redis`) or fix `REDIS_URL` env var    |
+| Nx generator not found   | `@frontmcp/nx` not installed     | Run `npm install -D @frontmcp/nx`                                     |
+| Skills not loading       | Skills placed in wrong directory | Catalog skills go in top-level `skills/`, app skills in `src/skills/` |
+
+## Reference
+
+- [Getting Started](https://docs.agentfront.dev/frontmcp/getting-started/quickstart)
+- Domain routers: `frontmcp-development`, `frontmcp-deployment`, `frontmcp-testing`, `frontmcp-config`, `frontmcp-guides`

package/catalog/frontmcp-setup/references/frontmcp-skills-usage.md

@@ -0,0 +1,265 @@
+# FrontMCP Skills — Search, Install, and Usage
+
+FrontMCP ships with a catalog of development skills that teach AI agents (Claude Code, Codex) how to build FrontMCP servers. You can deliver these skills **statically** (copy to disk) or **dynamically** (search on demand via CLI).
+
+## When to Use This Skill
+
+### Must Use
+
+- Setting up a new FrontMCP project and need to discover which skills to install for your workflow
+- Configuring AI-assisted development (Claude Code or Codex) with FrontMCP skill files for the first time
+- Deciding between static skill installation and dynamic on-demand search for your team
+
+### Recommended
+
+- Exploring the FrontMCP skill catalog to find skills for a specific topic (auth, deployment, plugins, etc.)
+- Onboarding a new team member who needs to understand how FrontMCP skills are delivered and consumed
+- Optimizing token usage by switching from fully-static to a hybrid static/dynamic skill strategy
+
+### Skip When
+
+- You already know which specific skill you need and want to learn its content (use that skill directly, e.g., `frontmcp-development` or `frontmcp-config`)
+- You are scaffolding a brand-new FrontMCP project from scratch (use `frontmcp-setup` instead)
+- You need to create a custom skill for your own organization (use the `create-skill` reference in `frontmcp-development`)
+
+> **Decision:** Use this skill when you need to understand the skills system itself -- how to browse, install, manage, and deliver FrontMCP skills to AI agents.
+
+## Available Skills
+
+The catalog contains 6 router skills, each covering a domain:
+
+| Skill Name             | Category    | Description                                                                    |
+| ---------------------- | ----------- | ------------------------------------------------------------------------------ |
+| `frontmcp-setup`       | setup       | Project setup, scaffolding, Nx workspaces, storage backends                    |
+| `frontmcp-development` | development | Creating tools, resources, prompts, agents, providers, jobs, workflows, skills |
+| `frontmcp-deployment`  | deployment  | Build and deploy to Node, Vercel, Lambda, Cloudflare, CLI, browser, SDK        |
+| `frontmcp-testing`     | testing     | Testing with Jest and @frontmcp/testing                                        |
+| `frontmcp-config`      | config      | Transport, HTTP, throttle, elicitation, auth, sessions, storage                |
+| `frontmcp-guides`      | guides      | End-to-end examples and best practices                                         |
+
+Each router skill contains a SKILL.md with a routing table and a `references/` directory with detailed reference files.
+
+## Quick Start
+
+```bash
+# List all skills
+frontmcp skills list
+
+# List skills by category
+frontmcp skills list --category development
+
+# Show full skill content
+frontmcp skills show frontmcp-development
+
+# Install a skill for Claude Code
+frontmcp skills install frontmcp-development --provider claude
+
+# Install a skill for Codex
+frontmcp skills install frontmcp-setup --provider codex
+```
+
+## CLI Commands
+
+### `frontmcp skills search <query>`
+
+Semantic search through the catalog using weighted text matching (description 3x, tags 2x, name 1x):
+
+```bash
+frontmcp skills search "authentication oauth"
+frontmcp skills search "deploy vercel" --category deployment
+frontmcp skills search "plugin hooks" --tag middleware --limit 5
+```
+
+### `frontmcp skills list`
+
+List all skills, optionally filtered:
+
+```bash
+frontmcp skills list                          # All skills
+frontmcp skills list --category development   # Development skills only
+frontmcp skills list --tag redis              # Skills tagged with redis
+frontmcp skills list --bundle recommended     # Recommended bundle
+```
+
+### `frontmcp skills show <name>`
+
+Print the full SKILL.md content to stdout — useful for piping to AI context:
+
+```bash
+frontmcp skills show frontmcp-development    # Print development skill
+frontmcp skills show frontmcp-config         # Print config skill
+```
+
+### `frontmcp skills install <name>`
+
+Copy a skill to a provider-specific directory:
+
+```bash
+# Claude Code — installs to .claude/skills/<name>/SKILL.md
+frontmcp skills install frontmcp-development --provider claude
+
+# Codex — installs to .codex/skills/<name>/SKILL.md
+frontmcp skills install frontmcp-setup --provider codex
+
+# Custom directory
+frontmcp skills install frontmcp-guides --dir ./my-skills
+```
+
+## Two Approaches: Static vs Dynamic
+
+### Static Installation (Copy to Disk)
+
+Install skills once — they live in your project and are always available:
+
+```bash
+# Install for Claude Code
+frontmcp skills install frontmcp-setup --provider claude
+frontmcp skills install frontmcp-development --provider claude
+frontmcp skills install frontmcp-config --provider claude
+
+# Install for Codex
+frontmcp skills install frontmcp-development --provider codex
+```
+
+**Directory structure after install:**
+
+```text
+my-project/
+├── .claude/
+│   └── skills/
+│       ├── frontmcp-setup/
+│       │   ├── SKILL.md
+│       │   └── references/
+│       ├── frontmcp-development/
+│       │   ├── SKILL.md
+│       │   └── references/
+│       └── frontmcp-config/
+│           ├── SKILL.md
+│           └── references/
+├── .codex/
+│   └── skills/
+│       └── frontmcp-development/
+│           ├── SKILL.md
+│           └── references/
+└── src/
+    └── ...
+```
+
+### Dynamic Search (On-Demand via CLI)
+
+Use the CLI to search and show skills on demand — no installation needed:
+
+```bash
+# Search for what you need
+frontmcp skills search "how to create a tool with zod"
+
+# Pipe skill content directly into context
+frontmcp skills show frontmcp-development
+```
+
+This works because `frontmcp skills show` outputs the full SKILL.md content to stdout.
+
+## Comparison: Static vs Dynamic
+
+| Aspect            | Static Install                        | Dynamic CLI Search                              |
+| ----------------- | ------------------------------------- | ----------------------------------------------- |
+| **Setup**         | `frontmcp skills install <name>` once | No setup — just use `frontmcp skills search`    |
+| **Availability**  | Always loaded by AI agent             | On-demand, requires CLI invocation              |
+| **Context usage** | Skills in system prompt (uses tokens) | Only loaded when searched (saves tokens)        |
+| **Updates**       | Re-install to update                  | Uses catalog bundled with the installed package |
+| **Offline**       | Works offline after install           | Needs catalog available                         |
+| **Best for**      | Core skills you use daily             | Occasional reference, exploration               |
+| **Token cost**    | Higher (all installed skills loaded)  | Lower (only searched skills loaded)             |
+
+### Recommended Approach
+
+**Install 2-4 core skills statically** for your most common workflows, and use dynamic search for everything else:
+
+```bash
+# Core skills — install statically
+frontmcp skills install frontmcp-setup --provider claude
+frontmcp skills install frontmcp-development --provider claude
+frontmcp skills install frontmcp-config --provider claude
+
+# Everything else — search on demand
+frontmcp skills search "deploy to vercel"
+frontmcp skills search "rate limiting"
+frontmcp skills show frontmcp-deployment
+```
+
+## Provider Directories
+
+| Provider    | Install directory                | Auto-loaded by            |
+| ----------- | -------------------------------- | ------------------------- |
+| Claude Code | `.claude/skills/<name>/SKILL.md` | Claude Code system prompt |
+| Codex       | `.codex/skills/<name>/SKILL.md`  | Codex agent context       |
+
+## Bundle Presets
+
+When scaffolding a project, use `--skills` to install a preset bundle:
+
+```bash
+# Recommended bundle (core skills for the deployment target)
+frontmcp create my-app --skills recommended
+
+# Minimal bundle (just project setup + create-tool)
+frontmcp create my-app --skills minimal
+
+# Full bundle (all skills)
+frontmcp create my-app --skills full
+
+# No skills
+frontmcp create my-app --skills none
+```
+
+## Available Categories
+
+```bash
+frontmcp skills list --category setup        # Project setup and scaffolding
+frontmcp skills list --category config       # Server configuration (transport, HTTP, throttle, auth)
+frontmcp skills list --category development  # Creating tools, resources, prompts, agents, skills
+frontmcp skills list --category deployment   # Build and deploy (node, vercel, lambda, cloudflare, cli, browser, sdk)
+frontmcp skills list --category testing      # Testing with Jest and @frontmcp/testing
+frontmcp skills list --category guides       # End-to-end examples and best practices
+```
+
+## Common Patterns
+
+| Pattern                     | Correct                                                                   | Incorrect                                       | Why                                                                                                    |
+| --------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Installing a skill          | `frontmcp skills install frontmcp-development --provider claude`          | `cp node_modules/.../SKILL.md .claude/skills/`  | The CLI handles directory creation, naming, and reference files automatically                          |
+| Searching skills            | `frontmcp skills search "oauth authentication"`                           | `frontmcp skills list \| grep oauth`            | Search uses weighted text matching (description 3x, tags 2x) for better relevance                      |
+| Choosing delivery mode      | Install 2-4 core skills statically; search the rest on demand             | Install every skill statically into the project | Static skills consume tokens on every agent invocation; keep the set small                             |
+| Updating an installed skill | `frontmcp skills install frontmcp-development --provider claude` (re-run) | Manually editing the installed SKILL.md file    | Re-installing overwrites with the catalog bundled in the installed CLI version and preserves structure |
+| Filtering by category       | `frontmcp skills list --category deployment`                              | `frontmcp skills search "deployment"`           | `--category` uses the manifest taxonomy; search is for free-text queries                               |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] FrontMCP CLI is installed and available on PATH (`frontmcp --version`)
+- [ ] Target provider directory exists or will be created (`.claude/skills/` or `.codex/skills/`)
+- [ ] Desired skills are listed in `frontmcp skills list` output
+- [ ] Bundle preset matches project needs (`minimal`, `recommended`, or `full`)
+
+### Runtime
+
+- [ ] Installed skills appear in the correct provider directory after `frontmcp skills install`
+- [ ] `frontmcp skills show <name>` outputs the full SKILL.md content to stdout
+- [ ] `frontmcp skills search <query>` returns relevant results ranked by relevance
+- [ ] AI agent (Claude Code or Codex) loads installed skills in its system prompt context
+
+## Troubleshooting
+
+| Problem                                               | Cause                                                               | Solution                                                                                                  |
+| ----------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `frontmcp skills search` returns no results           | Query terms do not match any skill name, description, or tags       | Broaden the query, try synonyms, or use `frontmcp skills list` to browse all available skills             |
+| Installed skill not picked up by Claude Code          | Skill was installed to wrong directory or provider flag was omitted | Re-install with `--provider claude` and verify the file exists at `.claude/skills/<name>/SKILL.md`        |
+| `frontmcp skills install` fails with permission error | Target directory is read-only or owned by a different user          | Check directory permissions; use `--dir` flag to specify an alternative writable path                     |
+| Skill content is outdated after a CLI upgrade         | Static installs are point-in-time snapshots of the catalog          | Re-run `frontmcp skills install <name> --provider claude` to fetch the latest version                     |
+| Too many tokens consumed by agent context             | All skills installed statically, inflating the system prompt        | Uninstall rarely-used skills and switch to dynamic search (`frontmcp skills search`) for occasional needs |
+
+## Reference
+
+- **Docs:** <https://docs.agentfront.dev/frontmcp/servers/skills>
+- **Related skills:** `frontmcp-setup`, `frontmcp-development`, `frontmcp-config`, `frontmcp-deployment`