@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-development/examples/create-skill/basic-inline-skill.md

@@ -0,0 +1,96 @@
+---
+name: basic-inline-skill
+reference: create-skill
+level: basic
+description: 'A minimal instruction-only skill with inline content and the function builder alternative.'
+tags: [development, skill, inline]
+features:
+  - 'Creating a class-based instruction-only skill with `@Skill` and `SkillContext`'
+  - 'Using inline string instructions for short, self-contained guides'
+  - 'The `skill()` function builder as a lighter alternative when no `build()` override is needed'
+  - 'Setting `visibility` to control where the skill is discoverable'
+---
+
+# Basic Inline Instruction Skill
+
+A minimal instruction-only skill with inline content and the function builder alternative.
+
+## Code
+
+```typescript
+// src/skills/typescript-conventions.skill.ts
+import { Skill, SkillContext } from '@frontmcp/sdk';
+
+@Skill({
+  name: 'typescript-conventions',
+  description: 'TypeScript coding conventions and patterns for the project',
+  instructions: `# TypeScript Conventions
+
+## Naming
+- Use PascalCase for classes and interfaces
+- Use camelCase for variables, functions, and methods
+- Use UPPER_SNAKE_CASE for constants
+- Use kebab-case for file names
+
+## Types
+- Always use explicit return types on public methods
+- Prefer \`unknown\` over \`any\` for generic defaults
+- Use strict mode (\`strict: true\` in tsconfig)
+- Define shared types in a common directory
+
+## Error Handling
+- Use specific error classes, not raw Error
+- Never use non-null assertions (\`!\`) -- throw proper errors
+- Use \`this.fail(err)\` in execution contexts
+
+## Imports
+- Use barrel exports (index.ts) for public APIs
+- No circular dependencies
+- Group imports: external, internal, relative`,
+})
+class TypeScriptConventionsSkill extends SkillContext {}
+```
+
+```typescript
+// src/skills/code-review-checklist.skill.ts
+import { skill } from '@frontmcp/sdk';
+
+// Function-style skill -- no class needed for simple instruction-only skills
+const CodeReviewChecklist = skill({
+  name: 'code-review-checklist',
+  description: 'Checklist for reviewing pull requests',
+  instructions: `# Code Review Checklist
+
+## Correctness
+- Does the code do what it claims?
+- Are edge cases handled?
+- Are error paths covered?
+
+## Style
+- Does it follow project conventions?
+- Are names descriptive and consistent?
+- Is the code self-documenting?
+
+## Testing
+- Are there tests for new functionality?
+- Do tests cover edge cases?
+- Is coverage above 95%?
+
+## Security
+- No secrets in code or config?
+- Input validation present?
+- Proper error handling without leaking internals?`,
+  visibility: 'both',
+});
+```
+
+## What This Demonstrates
+
+- Creating a class-based instruction-only skill with `@Skill` and `SkillContext`
+- Using inline string instructions for short, self-contained guides
+- The `skill()` function builder as a lighter alternative when no `build()` override is needed
+- Setting `visibility` to control where the skill is discoverable
+
+## Related
+
+- See `create-skill` for file-based instructions, parameters, and directory-based skills

package/catalog/frontmcp-development/examples/create-skill/directory-based-skill.md

@@ -0,0 +1,115 @@
+---
+name: directory-based-skill
+reference: create-skill
+level: advanced
+description: 'A skill loaded from a directory structure with SKILL.md frontmatter, plus file-based and URL-based instruction sources.'
+tags: [development, remote, skill, directory, based]
+features:
+  - 'Loading a skill from a directory with `skillDir()` including SKILL.md frontmatter and bundled resources'
+  - 'The SKILL.md YAML frontmatter format for metadata (name, description, tags, parameters, examples)'
+  - "File-based instructions with `{ file: './path.md' }` resolved relative to the skill file"
+  - "URL-based instructions with `{ url: '...' }` fetched at build time"
+  - 'ESM loading with `Skill.esm()` and remote loading with `Skill.remote()`'
+---
+
+# Directory-Based Skill with File References and Registration
+
+A skill loaded from a directory structure with SKILL.md frontmatter, plus file-based and URL-based instruction sources.
+
+## Code
+
+```text
+skills/
+  coding-standards/
+    SKILL.md           # Instructions with YAML frontmatter
+    scripts/
+      lint-check.sh    # Helper scripts referenced in instructions
+    references/
+      patterns.md      # Reference documentation appended to context
+    assets/
+      diagram.png      # Visual assets
+```
+
+```markdown
+## <!-- skills/coding-standards/SKILL.md -->
+
+name: coding-standards
+description: Project coding standards and patterns
+tags: [standards, conventions, quality]
+parameters:
+
+- name: language
+  description: Target programming language
+  type: string
+  default: typescript
+  examples:
+- scenario: Apply coding standards to a new module
+  expected-outcome: Code follows all project conventions
+
+---
+
+# Coding Standards
+
+Follow these standards when writing code for this project...
+```
+
+```typescript
+// src/skills/load-skills.ts
+import { skillDir, skill } from '@frontmcp/sdk';
+
+// Load a directory-based skill with bundled scripts, references, and assets
+const CodingStandards = await skillDir('./skills/coding-standards');
+
+// File-based instructions -- path resolves relative to this file's directory
+const DeployGuide = skill({
+  name: 'deploy-guide',
+  description: 'Step-by-step deployment checklist',
+  instructions: { file: './docs/deploy-guide.md' }, // resolves to src/skills/docs/deploy-guide.md
+});
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Skill, SkillContext } from '@frontmcp/sdk';
+
+// URL-based instructions fetched at build time
+@Skill({
+  name: 'api-standards',
+  description: 'REST API design standards',
+  instructions: { url: 'https://docs.example.com/standards/api-design.md' },
+})
+class ApiStandardsSkill extends SkillContext {}
+
+// ESM and remote loading
+const ExternalGuide = Skill.esm('@my-org/skills@^1.0.0', 'ExternalGuide', {
+  description: 'A skill loaded from an ES module',
+});
+
+const CloudGuide = Skill.remote('https://example.com/skills/style-guide', 'CloudGuide', {
+  description: 'A skill loaded from a remote server',
+});
+
+@App({
+  name: 'standards-app',
+  skills: [CodingStandards, DeployGuide, ApiStandardsSkill, ExternalGuide, CloudGuide],
+})
+class StandardsApp {}
+
+@FrontMcp({
+  info: { name: 'dev-server', version: '1.0.0' },
+  apps: [StandardsApp],
+})
+class DevServer {}
+```
+
+## What This Demonstrates
+
+- Loading a skill from a directory with `skillDir()` including SKILL.md frontmatter and bundled resources
+- The SKILL.md YAML frontmatter format for metadata (name, description, tags, parameters, examples)
+- File-based instructions with `{ file: './path.md' }` resolved relative to the skill file
+- URL-based instructions with `{ url: '...' }` fetched at build time
+- ESM loading with `Skill.esm()` and remote loading with `Skill.remote()`
+
+## Related
+
+- See `create-skill` for the complete `skillDir()` reference, instruction resolution, and HTTP discovery

package/catalog/frontmcp-development/examples/create-skill/parameterized-skill.md

@@ -0,0 +1,96 @@
+---
+name: parameterized-skill
+reference: create-skill
+level: intermediate
+description: 'A skill with customizable parameters, usage examples for AI guidance, and controlled visibility.'
+tags: [development, skill, parameterized]
+features:
+  - 'Defining `parameters` to let callers customize skill behavior at invocation time'
+  - 'Providing `examples` with `scenario` and `expectedOutcome` to guide AI application'
+  - 'Using `tags` for skill categorization and filtering'
+  - "Controlling discovery with `visibility: 'mcp'` (MCP-only) vs `visibility: 'both'` (default)"
+  - 'Using `hideFromDiscovery: true` to register a skill that is invocable by name but not listed'
+---
+
+# Parameterized Skill with Examples and Visibility
+
+A skill with customizable parameters, usage examples for AI guidance, and controlled visibility.
+
+## Code
+
+```typescript
+// src/skills/api-design-guide.skill.ts
+import { Skill, SkillContext } from '@frontmcp/sdk';
+
+@Skill({
+  name: 'api-design-guide',
+  description: 'REST API design guidelines',
+  instructions: `# API Design Guide
+
+Design APIs following these conventions.
+Adapt the versioning strategy based on the api-style parameter.
+Use the auth-required parameter to determine if authentication sections apply.`,
+  parameters: [
+    { name: 'api-style', description: 'API style to follow', type: 'string', default: 'rest' },
+    { name: 'auth-required', description: 'Whether to include auth guidelines', type: 'boolean', default: true },
+    { name: 'version-strategy', description: 'API versioning approach', type: 'string', default: 'url-path' },
+  ],
+  examples: [
+    {
+      scenario: 'Adding error handling to a new API endpoint',
+      expectedOutcome:
+        'Endpoint uses specific error classes with MCP error codes, validates input, and returns structured error responses',
+    },
+    {
+      scenario: 'Refactoring try-catch blocks in existing code',
+      expectedOutcome: 'Generic catches replaced with specific error types, proper error propagation chain established',
+    },
+  ],
+  tags: ['api', 'design', 'standards'],
+  visibility: 'both',
+})
+class ApiDesignGuideSkill extends SkillContext {}
+```
+
+```typescript
+// src/skills/internal-runbook.skill.ts
+import { Skill, SkillContext } from '@frontmcp/sdk';
+
+@Skill({
+  name: 'internal-runbook',
+  description: 'Internal operations runbook',
+  instructions: `# Operations Runbook
+
+## Incident Response
+1. Check monitoring dashboards
+2. Identify affected services
+3. Escalate if severity is P0 or P1`,
+  visibility: 'mcp', // Only visible to MCP clients, not HTTP discovery
+})
+class InternalRunbookSkill extends SkillContext {}
+```
+
+```typescript
+// src/skills/admin-procedures.skill.ts
+import { Skill, SkillContext } from '@frontmcp/sdk';
+
+@Skill({
+  name: 'admin-procedures',
+  description: 'Administrative procedures for internal use',
+  instructions: '...',
+  hideFromDiscovery: true, // Registered but hidden from listing endpoints
+})
+class AdminProceduresSkill extends SkillContext {}
+```
+
+## What This Demonstrates
+
+- Defining `parameters` to let callers customize skill behavior at invocation time
+- Providing `examples` with `scenario` and `expectedOutcome` to guide AI application
+- Using `tags` for skill categorization and filtering
+- Controlling discovery with `visibility: 'mcp'` (MCP-only) vs `visibility: 'both'` (default)
+- Using `hideFromDiscovery: true` to register a skill that is invocable by name but not listed
+
+## Related
+
+- See `create-skill` for the full parameters, examples, and visibility reference

package/catalog/frontmcp-development/examples/create-skill-with-tools/basic-tool-orchestration.md

@@ -0,0 +1,76 @@
+---
+name: basic-tool-orchestration
+reference: create-skill-with-tools
+level: basic
+description: 'A skill that guides an AI client through a deploy workflow using referenced MCP tools.'
+tags: [development, skill, tools, tool, orchestration]
+features:
+  - "Referencing tools by class (`BuildProjectTool`) and by string name (`'health_check'`)"
+  - 'Mixing class references and string names in a single `tools` array'
+  - 'Writing step-by-step instructions that guide the AI to use specific tools'
+  - 'The `skill()` function builder for tool-referencing skills that need no class'
+---
+
+# Basic Skill with Tool References
+
+A skill that guides an AI client through a deploy workflow using referenced MCP tools.
+
+## Code
+
+```typescript
+// src/skills/deploy-service.skill.ts
+import { Skill, SkillContext } from '@frontmcp/sdk';
+import { BuildProjectTool } from '../tools/build-project.tool';
+import { RunTestsTool } from '../tools/run-tests.tool';
+import { DeployToEnvTool } from '../tools/deploy-to-env.tool';
+
+@Skill({
+  name: 'deploy-service',
+  description: 'Deploy a service through the build, test, and release pipeline',
+  instructions: `# Deploy Service Workflow
+
+## Step 1: Build
+Use the \`build_project\` tool to compile the service.
+Pass the service name and target environment.
+
+## Step 2: Run Tests
+Use the \`run_tests\` tool to execute the test suite.
+If tests fail, stop and report the failures.
+
+## Step 3: Deploy
+Use the \`deploy_to_env\` tool to push the build to the target environment.
+Verify the deployment using \`health_check\` tool.
+
+## Step 4: Notify
+Use the \`send_notification\` tool to notify the team of the deployment status.`,
+  tools: [BuildProjectTool, RunTestsTool, DeployToEnvTool, 'health_check', 'send_notification'],
+})
+class DeployServiceSkill extends SkillContext {}
+```
+
+```typescript
+// src/skills/quick-deploy.skill.ts
+import { skill } from '@frontmcp/sdk';
+
+// Function-style skill with tool references
+const QuickDeploySkill = skill({
+  name: 'quick-deploy',
+  description: 'Quick deployment to staging',
+  instructions: `# Quick Deploy
+1. Use build_project to compile.
+2. Use deploy_to_env with environment=staging.
+3. Use health_check to verify.`,
+  tools: ['build_project', 'deploy_to_env', 'health_check'],
+});
+```
+
+## What This Demonstrates
+
+- Referencing tools by class (`BuildProjectTool`) and by string name (`'health_check'`)
+- Mixing class references and string names in a single `tools` array
+- Writing step-by-step instructions that guide the AI to use specific tools
+- The `skill()` function builder for tool-referencing skills that need no class
+
+## Related
+
+- See `create-skill-with-tools` for all three tool reference styles and validation modes

package/catalog/frontmcp-development/examples/create-skill-with-tools/directory-skill-with-tools.md

@@ -0,0 +1,149 @@
+---
+name: directory-skill-with-tools
+reference: create-skill-with-tools
+level: advanced
+description: 'A directory-based skill loaded with `skillDir()`, plus a class-based skill using Agent Skills spec metadata fields.'
+tags: [development, skill, tools, directory]
+features:
+  - 'Loading a directory-based skill with `skillDir()` including SKILL.md frontmatter with tool entries'
+  - 'Mixing all three tool reference styles in one `tools` array: class, string, and object'
+  - 'Agent Skills spec fields: `priority`, `license`, `compatibility`, `allowedTools`, `specMetadata`'
+  - 'Bundled resource directories: `scripts`, `references`, `assets`'
+  - "File-based instructions with `{ file: './docs/codebase-audit.md' }`"
+---
+
+# Directory-Based Skill with Tools, Agent Skills Spec Fields, and Registration
+
+A directory-based skill loaded with `skillDir()`, plus a class-based skill using Agent Skills spec metadata fields.
+
+## Code
+
+```text
+skills/
+  deploy-service/
+    SKILL.md           # Instructions with YAML frontmatter
+    scripts/
+      validate.sh      # Helper scripts
+      smoke-test.sh
+    references/
+      architecture.md  # Reference documentation
+      runbook.md
+    assets/
+      topology.png     # Visual assets
+```
+
+```markdown
+## <!-- skills/deploy-service/SKILL.md -->
+
+name: deploy-service
+description: Deploy a service through the full pipeline
+tags: [deploy, ci-cd, production]
+tools:
+
+- name: build_project
+  purpose: Compile the service
+  required: true
+- name: run_tests
+  purpose: Execute test suite
+  required: true
+- name: deploy_to_env
+  purpose: Push build to target environment
+  required: true
+  parameters:
+- name: environment
+  description: Target deployment environment
+  type: string
+  required: true
+  examples:
+- scenario: Deploy to staging
+  expected-outcome: Service deployed and health check passes
+
+---
+
+# Deploy Service
+
+Follow these steps to deploy the service...
+```
+
+```typescript
+// src/skills/load-skills.ts
+import { skillDir } from '@frontmcp/sdk';
+
+const DeployServiceSkill = await skillDir('./skills/deploy-service');
+```
+
+```typescript
+// src/skills/audit.skill.ts
+import { Skill, SkillContext, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'analyze_codebase',
+  description: 'Analyze a codebase for patterns and issues',
+  inputSchema: {
+    path: z.string().describe('Path to the codebase'),
+    checks: z.array(z.string()).describe('Checks to run'),
+  },
+})
+class AnalyzeCodebaseTool extends ToolContext {
+  async execute(input: { path: string; checks: string[] }) {
+    return { issues: [], score: 95 };
+  }
+}
+
+@Skill({
+  name: 'codebase-audit',
+  description: 'Perform a comprehensive codebase audit with reporting and issue creation',
+  instructions: { file: './docs/codebase-audit.md' },
+  tools: [
+    AnalyzeCodebaseTool,
+    'generate_report',
+    { name: 'create_issue', purpose: 'File GitHub issues for critical findings', required: false },
+  ],
+  toolValidation: 'strict',
+  priority: 10,
+  license: 'MIT',
+  compatibility: 'Node.js 24+',
+  allowedTools: 'Read Edit Bash(git status)',
+  specMetadata: {
+    author: 'platform-team',
+    version: '2.0.0',
+  },
+  resources: {
+    scripts: './scripts',
+    references: './references',
+    assets: './assets',
+  },
+})
+class CodebaseAuditSkill extends SkillContext {}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'audit-app',
+  skills: [DeployServiceSkill, CodebaseAuditSkill],
+  tools: [AnalyzeCodebaseTool, GenerateReportTool, CreateIssueTool],
+})
+class AuditApp {}
+
+@FrontMcp({
+  info: { name: 'audit-server', version: '1.0.0' },
+  apps: [AuditApp],
+})
+class AuditServer {}
+```
+
+## What This Demonstrates
+
+- Loading a directory-based skill with `skillDir()` including SKILL.md frontmatter with tool entries
+- Mixing all three tool reference styles in one `tools` array: class, string, and object
+- Agent Skills spec fields: `priority`, `license`, `compatibility`, `allowedTools`, `specMetadata`
+- Bundled resource directories: `scripts`, `references`, `assets`
+- File-based instructions with `{ file: './docs/codebase-audit.md' }`
+
+## Related
+
+- See `create-skill-with-tools` for the full Agent Skills spec fields reference and CodeCall compatibility

package/catalog/frontmcp-development/examples/create-skill-with-tools/incident-response-skill.md

@@ -0,0 +1,92 @@
+---
+name: incident-response-skill
+reference: create-skill-with-tools
+level: intermediate
+description: 'A skill that uses object-style tool references with purpose descriptions and required flags, plus strict validation.'
+tags: [development, skill, tools, incident, response]
+features:
+  - 'Object-style tool references with `name`, `purpose`, and `required` fields'
+  - "Using `toolValidation: 'strict'` to fail at startup if any referenced tool is missing"
+  - 'Combining tool references with `parameters` and `examples` for full skill metadata'
+  - "Setting `visibility: 'mcp'` to restrict discovery to MCP protocol only"
+  - 'Registering both skills and their referenced tools in the same `@App`'
+---
+
+# Incident Response Skill with Detailed Tool Metadata
+
+A skill that uses object-style tool references with purpose descriptions and required flags, plus strict validation.
+
+## Code
+
+```typescript
+// src/skills/incident-response.skill.ts
+import { Skill, SkillContext } from '@frontmcp/sdk';
+
+@Skill({
+  name: 'incident-response',
+  description: 'Respond to production incidents',
+  instructions: `# Incident Response
+
+## Step 1: Gather Information
+Use check_service_health to determine which services are affected.
+Use query_logs to find error patterns.
+
+## Step 2: Mitigate
+Use rollback_deployment if a recent deploy caused the issue.
+Use scale_service if the issue is load-related.
+
+## Step 3: Communicate
+Use send_notification to update the incident channel.`,
+  tools: [
+    { name: 'check_service_health', purpose: 'Check health status of services', required: true },
+    { name: 'query_logs', purpose: 'Search application logs for errors', required: true },
+    { name: 'rollback_deployment', purpose: 'Rollback to previous deployment', required: false },
+    { name: 'scale_service', purpose: 'Scale service replicas up or down', required: false },
+    { name: 'send_notification', purpose: 'Send notification to Slack channel', required: true },
+  ],
+  toolValidation: 'strict', // Fail at startup if any required tool is missing
+  parameters: [
+    { name: 'severity', description: 'Incident severity level', type: 'string', required: true },
+    { name: 'auto-rollback', description: 'Whether to auto-rollback on detection', type: 'boolean', default: false },
+  ],
+  examples: [
+    {
+      scenario: 'API latency spike after a deployment',
+      expectedOutcome: 'Health checked, logs queried, deployment rolled back, team notified',
+    },
+  ],
+  tags: ['incident', 'ops', 'on-call'],
+  visibility: 'mcp',
+})
+class IncidentResponseSkill extends SkillContext {}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'ops-app',
+  skills: [IncidentResponseSkill],
+  tools: [CheckServiceHealthTool, QueryLogsTool, RollbackDeploymentTool, ScaleServiceTool, SendNotificationTool],
+})
+class OpsApp {}
+
+@FrontMcp({
+  info: { name: 'ops-server', version: '1.0.0' },
+  apps: [OpsApp],
+})
+class OpsServer {}
+```
+
+## What This Demonstrates
+
+- Object-style tool references with `name`, `purpose`, and `required` fields
+- Using `toolValidation: 'strict'` to fail at startup if any referenced tool is missing
+- Combining tool references with `parameters` and `examples` for full skill metadata
+- Setting `visibility: 'mcp'` to restrict discovery to MCP protocol only
+- Registering both skills and their referenced tools in the same `@App`
+
+## Related
+
+- See `create-skill-with-tools` for all tool validation modes and the CodeCall compatibility section

package/catalog/frontmcp-development/examples/create-tool/basic-class-tool.md

@@ -0,0 +1,62 @@
+---
+name: basic-class-tool
+reference: create-tool
+level: basic
+description: 'A minimal tool using the class-based pattern with Zod input validation and output schema.'
+tags: [development, tool, class]
+features:
+  - 'Extending `ToolContext` and implementing the `execute()` method'
+  - 'Using a Zod raw shape for `inputSchema` (not wrapped in `z.object()`)'
+  - 'Defining `outputSchema` to validate and restrict output fields'
+  - 'Registering the tool in an `@App` via the `tools` array'
+---
+
+# Basic Class-Based Tool
+
+A minimal tool using the class-based pattern with Zod input validation and output schema.
+
+## Code
+
+```typescript
+// src/apps/main/tools/greet-user.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'greet_user',
+  description: 'Greet a user by name',
+  inputSchema: {
+    name: z.string().describe('The name of the user to greet'),
+  },
+  outputSchema: {
+    greeting: z.string(),
+  },
+})
+class GreetUserTool extends ToolContext {
+  async execute(input: { name: string }): Promise<{ greeting: string }> {
+    return { greeting: `Hello, ${input.name}!` };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  tools: [GreetUserTool],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Extending `ToolContext` and implementing the `execute()` method
+- Using a Zod raw shape for `inputSchema` (not wrapped in `z.object()`)
+- Defining `outputSchema` to validate and restrict output fields
+- Registering the tool in an `@App` via the `tools` array
+
+## Related
+
+- See `create-tool` for the full API reference including annotations, rate limiting, and elicitation