@frontmcp/skills 0.0.1 → 1.0.0-beta.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/skills",
-  "version": "0.0.1",
+  "version": "1.0.0-beta.11",
   "description": "Curated skills catalog for FrontMCP projects",
   "author": "AgentFront <info@agentfront.dev>",
   "homepage": "https://docs.agentfront.dev",
@@ -25,7 +25,7 @@
   "main": "./src/index.js",
   "types": "./index.d.js",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
   "dependencies": {
     "tslib": "^2.3.0"

package/src/index.d.ts

@@ -1,3 +1,3 @@
-export type { SkillCatalogEntry, SkillManifest, SkillTarget, SkillCategory, SkillBundle, SkillDestination, SkillMergeStrategy, SkillInstallConfig, } from './manifest';
+export type { SkillCatalogEntry, SkillManifest, SkillReferenceEntry, SkillTarget, SkillCategory, SkillBundle, SkillDestination, SkillMergeStrategy, SkillInstallConfig, } from './manifest';
 export { VALID_TARGETS, VALID_CATEGORIES, VALID_BUNDLES } from './manifest';
 export { loadManifest, getSkillsByTarget, getSkillsByCategory, getSkillsByBundle, getInstructionOnlySkills, getResourceSkills, resolveSkillPath, } from './loader';

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAWA,uCAA4E;AAAnE,yGAAA,aAAa,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAAE,yGAAA,aAAa,OAAA;AAEvD,mCAQkB;AAPhB,sGAAA,YAAY,OAAA;AACZ,2GAAA,iBAAiB,OAAA;AACjB,6GAAA,mBAAmB,OAAA;AACnB,2GAAA,iBAAiB,OAAA;AACjB,kHAAA,wBAAwB,OAAA;AACxB,2GAAA,iBAAiB,OAAA;AACjB,0GAAA,gBAAgB,OAAA","sourcesContent":["export type {\n  SkillCatalogEntry,\n  SkillManifest,\n  SkillTarget,\n  SkillCategory,\n  SkillBundle,\n  SkillDestination,\n  SkillMergeStrategy,\n  SkillInstallConfig,\n} from './manifest';\n\nexport { VALID_TARGETS, VALID_CATEGORIES, VALID_BUNDLES } from './manifest';\n\nexport {\n  loadManifest,\n  getSkillsByTarget,\n  getSkillsByCategory,\n  getSkillsByBundle,\n  getInstructionOnlySkills,\n  getResourceSkills,\n  resolveSkillPath,\n} from './loader';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAYA,uCAA4E;AAAnE,yGAAA,aAAa,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAAE,yGAAA,aAAa,OAAA;AAEvD,mCAQkB;AAPhB,sGAAA,YAAY,OAAA;AACZ,2GAAA,iBAAiB,OAAA;AACjB,6GAAA,mBAAmB,OAAA;AACnB,2GAAA,iBAAiB,OAAA;AACjB,kHAAA,wBAAwB,OAAA;AACxB,2GAAA,iBAAiB,OAAA;AACjB,0GAAA,gBAAgB,OAAA","sourcesContent":["export type {\n  SkillCatalogEntry,\n  SkillManifest,\n  SkillReferenceEntry,\n  SkillTarget,\n  SkillCategory,\n  SkillBundle,\n  SkillDestination,\n  SkillMergeStrategy,\n  SkillInstallConfig,\n} from './manifest';\n\nexport { VALID_TARGETS, VALID_CATEGORIES, VALID_BUNDLES } from './manifest';\n\nexport {\n  loadManifest,\n  getSkillsByTarget,\n  getSkillsByCategory,\n  getSkillsByBundle,\n  getInstructionOnlySkills,\n  getResourceSkills,\n  resolveSkillPath,\n} from './loader';\n"]}

package/src/loader.js

@@ -25,7 +25,6 @@ const path = tslib_1.__importStar(require("node:path"));
 function loadManifest(catalogDir) {
     const dir = catalogDir ?? path.resolve(__dirname, '..', 'catalog');
     const manifestPath = path.join(dir, 'skills-manifest.json');
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
     return require(manifestPath);
 }
 /**

package/src/loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/loader.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAWH,oCAKC;AAMD,8CAIC;AAKD,kDAEC;AAKD,8CAIC;AAMD,4DAEC;AAMD,8CAEC;AASD,4CAGC;;AApED,wDAAkC;AAGlC;;;;;GAKG;AACH,SAAgB,YAAY,CAAC,UAAmB;IAC9C,MAAM,GAAG,GAAG,UAAU,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IACnE,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,sBAAsB,CAAC,CAAC;IAC5D,iEAAiE;IACjE,OAAO,OAAO,CAAC,YAAY,CAAkB,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,MAA2B,EAAE,MAAc;IAC3E,OAAO,MAAM,CAAC,MAAM,CAClB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,MAA8C,CAAC,CACvG,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,mBAAmB,CAAC,MAA2B,EAAE,QAAgB;IAC/E,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;AACvD,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAAC,MAA2B,EAAE,MAAc;IAC3E,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CACzB,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAiF,CAAC,CACtG,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,wBAAwB,CAAC,MAA2B;IAClE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,MAA2B;IAC3D,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAAC,KAAwB,EAAE,UAAmB;IAC5E,MAAM,GAAG,GAAG,UAAU,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IACnE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;AACvC,CAAC","sourcesContent":["/**\n * Skills catalog loader and filtering helpers.\n *\n * Provides functions to query the catalog manifest by target, category, and bundle.\n *\n * @module skills/loader\n */\n\nimport * as path from 'node:path';\nimport type { SkillCatalogEntry, SkillManifest } from './manifest';\n\n/**\n * Load the skills manifest from the catalog directory.\n *\n * @param catalogDir - Absolute path to the catalog directory. Defaults to the bundled catalog.\n * @returns The parsed skills manifest\n */\nexport function loadManifest(catalogDir?: string): SkillManifest {\n  const dir = catalogDir ?? path.resolve(__dirname, '..', 'catalog');\n  const manifestPath = path.join(dir, 'skills-manifest.json');\n  // eslint-disable-next-line @typescript-eslint/no-require-imports\n  return require(manifestPath) as SkillManifest;\n}\n\n/**\n * Filter skills by deployment target.\n * Returns skills that include the given target or 'all'.\n */\nexport function getSkillsByTarget(skills: SkillCatalogEntry[], target: string): SkillCatalogEntry[] {\n  return skills.filter(\n    (s) => s.targets.includes('all') || s.targets.includes(target as SkillCatalogEntry['targets'][number]),\n  );\n}\n\n/**\n * Filter skills by category.\n */\nexport function getSkillsByCategory(skills: SkillCatalogEntry[], category: string): SkillCatalogEntry[] {\n  return skills.filter((s) => s.category === category);\n}\n\n/**\n * Filter skills by bundle membership.\n */\nexport function getSkillsByBundle(skills: SkillCatalogEntry[], bundle: string): SkillCatalogEntry[] {\n  return skills.filter((s) =>\n    s.bundle?.includes(bundle as SkillCatalogEntry['bundle'] extends (infer U)[] | undefined ? U : never),\n  );\n}\n\n/**\n * Get only instruction-only skills (no scripts/, references/, or assets/ directories).\n * These are safe to use with `instructions: { file: ... }` wrappers.\n */\nexport function getInstructionOnlySkills(skills: SkillCatalogEntry[]): SkillCatalogEntry[] {\n  return skills.filter((s) => !s.hasResources);\n}\n\n/**\n * Get only resource-carrying skills (have scripts/, references/, or assets/).\n * These need full directory loading via `skillDir()`.\n */\nexport function getResourceSkills(skills: SkillCatalogEntry[]): SkillCatalogEntry[] {\n  return skills.filter((s) => s.hasResources);\n}\n\n/**\n * Resolve the absolute path to a skill directory.\n *\n * @param entry - The catalog entry\n * @param catalogDir - Absolute path to the catalog directory\n * @returns Absolute path to the skill directory\n */\nexport function resolveSkillPath(entry: SkillCatalogEntry, catalogDir?: string): string {\n  const dir = catalogDir ?? path.resolve(__dirname, '..', 'catalog');\n  return path.resolve(dir, entry.path);\n}\n"]}
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/loader.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAWH,oCAIC;AAMD,8CAIC;AAKD,kDAEC;AAKD,8CAIC;AAMD,4DAEC;AAMD,8CAEC;AASD,4CAGC;;AAnED,wDAAkC;AAGlC;;;;;GAKG;AACH,SAAgB,YAAY,CAAC,UAAmB;IAC9C,MAAM,GAAG,GAAG,UAAU,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IACnE,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,sBAAsB,CAAC,CAAC;IAC5D,OAAO,OAAO,CAAC,YAAY,CAAkB,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,MAA2B,EAAE,MAAc;IAC3E,OAAO,MAAM,CAAC,MAAM,CAClB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,MAA8C,CAAC,CACvG,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,mBAAmB,CAAC,MAA2B,EAAE,QAAgB;IAC/E,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;AACvD,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAAC,MAA2B,EAAE,MAAc;IAC3E,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CACzB,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAiF,CAAC,CACtG,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,wBAAwB,CAAC,MAA2B;IAClE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,MAA2B;IAC3D,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAAC,KAAwB,EAAE,UAAmB;IAC5E,MAAM,GAAG,GAAG,UAAU,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IACnE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;AACvC,CAAC","sourcesContent":["/**\n * Skills catalog loader and filtering helpers.\n *\n * Provides functions to query the catalog manifest by target, category, and bundle.\n *\n * @module skills/loader\n */\n\nimport * as path from 'node:path';\nimport type { SkillCatalogEntry, SkillManifest } from './manifest';\n\n/**\n * Load the skills manifest from the catalog directory.\n *\n * @param catalogDir - Absolute path to the catalog directory. Defaults to the bundled catalog.\n * @returns The parsed skills manifest\n */\nexport function loadManifest(catalogDir?: string): SkillManifest {\n  const dir = catalogDir ?? path.resolve(__dirname, '..', 'catalog');\n  const manifestPath = path.join(dir, 'skills-manifest.json');\n  return require(manifestPath) as SkillManifest;\n}\n\n/**\n * Filter skills by deployment target.\n * Returns skills that include the given target or 'all'.\n */\nexport function getSkillsByTarget(skills: SkillCatalogEntry[], target: string): SkillCatalogEntry[] {\n  return skills.filter(\n    (s) => s.targets.includes('all') || s.targets.includes(target as SkillCatalogEntry['targets'][number]),\n  );\n}\n\n/**\n * Filter skills by category.\n */\nexport function getSkillsByCategory(skills: SkillCatalogEntry[], category: string): SkillCatalogEntry[] {\n  return skills.filter((s) => s.category === category);\n}\n\n/**\n * Filter skills by bundle membership.\n */\nexport function getSkillsByBundle(skills: SkillCatalogEntry[], bundle: string): SkillCatalogEntry[] {\n  return skills.filter((s) =>\n    s.bundle?.includes(bundle as SkillCatalogEntry['bundle'] extends (infer U)[] | undefined ? U : never),\n  );\n}\n\n/**\n * Get only instruction-only skills (no scripts/, references/, or assets/ directories).\n * These are safe to use with `instructions: { file: ... }` wrappers.\n */\nexport function getInstructionOnlySkills(skills: SkillCatalogEntry[]): SkillCatalogEntry[] {\n  return skills.filter((s) => !s.hasResources);\n}\n\n/**\n * Get only resource-carrying skills (have scripts/, references/, or assets/).\n * These need full directory loading via `skillDir()`.\n */\nexport function getResourceSkills(skills: SkillCatalogEntry[]): SkillCatalogEntry[] {\n  return skills.filter((s) => s.hasResources);\n}\n\n/**\n * Resolve the absolute path to a skill directory.\n *\n * @param entry - The catalog entry\n * @param catalogDir - Absolute path to the catalog directory\n * @returns Absolute path to the skill directory\n */\nexport function resolveSkillPath(entry: SkillCatalogEntry, catalogDir?: string): string {\n  const dir = catalogDir ?? path.resolve(__dirname, '..', 'catalog');\n  return path.resolve(dir, entry.path);\n}\n"]}

package/src/manifest.d.ts

@@ -12,7 +12,7 @@ export type SkillTarget = 'node' | 'vercel' | 'lambda' | 'cloudflare' | 'all';
 /**
  * Skill categories for organizing the catalog.
  */
-export type SkillCategory = 'setup' | 'deployment' | 'development' | 'config' | 'auth' | 'plugins' | 'adapters' | 'testing';
+export type SkillCategory = 'setup' | 'deployment' | 'development' | 'config' | 'testing' | 'guides' | 'production' | 'extensibility';
 /**
  * Bundle membership for curated scaffold presets.
  */
@@ -36,6 +36,16 @@ export interface SkillInstallConfig {
     /** Other skills this depends on (by name) */
     dependencies?: string[];
 }
+/**
+ * Metadata for a single reference file within a skill's references/ directory.
+ * Extracted from YAML frontmatter or inferred from the markdown heading.
+ */
+export interface SkillReferenceEntry {
+    /** Reference name — matches filename without extension */
+    name: string;
+    /** Short description from frontmatter or first paragraph */
+    description: string;
+}
 /**
  * A single entry in the skills catalog manifest.
  *
@@ -55,14 +65,16 @@ export interface SkillCatalogEntry {
     targets: SkillTarget[];
     /** Whether the skill has scripts/, references/, or assets/ directories */
     hasResources: boolean;
+    /** Resolved reference metadata from references/ directory */
+    references?: SkillReferenceEntry[];
     /** Target-specific storage defaults (e.g., { node: 'redis-docker', vercel: 'vercel-kv' }) */
     storageDefault?: Record<string, string>;
     /** Tags for secondary filtering and search */
     tags: string[];
     /** Bundle membership for scaffold presets */
     bundle?: SkillBundle[];
-    /** Install configuration for future distribution */
-    install: SkillInstallConfig;
+    /** Install configuration for future distribution (optional — not yet used by CLI) */
+    install?: SkillInstallConfig;
 }
 /**
  * The skills catalog manifest — single source of truth for scaffold and install tooling.

package/src/manifest.js

@@ -16,10 +16,10 @@ exports.VALID_CATEGORIES = [
     'deployment',
     'development',
     'config',
-    'auth',
-    'plugins',
-    'adapters',
     'testing',
+    'guides',
+    'production',
+    'extensibility',
 ];
 /** Valid bundles for manifest validation */
 exports.VALID_BUNDLES = ['recommended', 'minimal', 'full'];

package/src/manifest.js.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/manifest.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAsFH,uDAAuD;AAC1C,QAAA,aAAa,GAA2B,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;AAEvG,+CAA+C;AAClC,QAAA,gBAAgB,GAA6B;IACxD,OAAO;IACP,YAAY;IACZ,aAAa;IACb,QAAQ;IACR,MAAM;IACN,SAAS;IACT,UAAU;IACV,SAAS;CACV,CAAC;AAEF,4CAA4C;AAC/B,QAAA,aAAa,GAA2B,CAAC,aAAa,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC","sourcesContent":["/**\n * Skills catalog manifest types.\n *\n * Defines the contract between the catalog, scaffold tooling, and future installer.\n *\n * @module skills/manifest\n */\n\n/**\n * Supported deployment targets for skill filtering.\n */\nexport type SkillTarget = 'node' | 'vercel' | 'lambda' | 'cloudflare' | 'all';\n\n/**\n * Skill categories for organizing the catalog.\n */\nexport type SkillCategory =\n  | 'setup'\n  | 'deployment'\n  | 'development'\n  | 'config'\n  | 'auth'\n  | 'plugins'\n  | 'adapters'\n  | 'testing';\n\n/**\n * Bundle membership for curated scaffold presets.\n */\nexport type SkillBundle = 'recommended' | 'minimal' | 'full';\n\n/**\n * Install destination types for future provider wiring.\n */\nexport type SkillDestination = 'project-local' | '.claude/skills' | 'codex' | 'gemini';\n\n/**\n * Merge strategy when installing a skill that already exists at the destination.\n */\nexport type SkillMergeStrategy = 'overwrite' | 'skip-existing';\n\n/**\n * Install configuration for a catalog skill.\n */\nexport interface SkillInstallConfig {\n  /** Where this skill can be installed */\n  destinations: SkillDestination[];\n  /** How to handle existing skills at the destination */\n  mergeStrategy: SkillMergeStrategy;\n  /** Other skills this depends on (by name) */\n  dependencies?: string[];\n}\n\n/**\n * A single entry in the skills catalog manifest.\n *\n * This is the core contract connecting SKILL.md files to scaffolding,\n * future installation, and provider-specific destinations.\n */\nexport interface SkillCatalogEntry {\n  /** Unique skill name — matches SKILL.md frontmatter `name` */\n  name: string;\n  /** Skill category for organization */\n  category: SkillCategory;\n  /** Short description */\n  description: string;\n  /** Path to the skill directory, relative to catalog/ */\n  path: string;\n  /** Deployment targets this skill applies to */\n  targets: SkillTarget[];\n  /** Whether the skill has scripts/, references/, or assets/ directories */\n  hasResources: boolean;\n  /** Target-specific storage defaults (e.g., { node: 'redis-docker', vercel: 'vercel-kv' }) */\n  storageDefault?: Record<string, string>;\n  /** Tags for secondary filtering and search */\n  tags: string[];\n  /** Bundle membership for scaffold presets */\n  bundle?: SkillBundle[];\n  /** Install configuration for future distribution */\n  install: SkillInstallConfig;\n}\n\n/**\n * The skills catalog manifest — single source of truth for scaffold and install tooling.\n */\nexport interface SkillManifest {\n  /** Manifest schema version */\n  version: 1;\n  /** All catalog skills */\n  skills: SkillCatalogEntry[];\n}\n\n/** Valid deployment targets for manifest validation */\nexport const VALID_TARGETS: readonly SkillTarget[] = ['node', 'vercel', 'lambda', 'cloudflare', 'all'];\n\n/** Valid categories for manifest validation */\nexport const VALID_CATEGORIES: readonly SkillCategory[] = [\n  'setup',\n  'deployment',\n  'development',\n  'config',\n  'auth',\n  'plugins',\n  'adapters',\n  'testing',\n];\n\n/** Valid bundles for manifest validation */\nexport const VALID_BUNDLES: readonly SkillBundle[] = ['recommended', 'minimal', 'full'];\n"]}
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/manifest.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAmGH,uDAAuD;AAC1C,QAAA,aAAa,GAA2B,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;AAEvG,+CAA+C;AAClC,QAAA,gBAAgB,GAA6B;IACxD,OAAO;IACP,YAAY;IACZ,aAAa;IACb,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,YAAY;IACZ,eAAe;CAChB,CAAC;AAEF,4CAA4C;AAC/B,QAAA,aAAa,GAA2B,CAAC,aAAa,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC","sourcesContent":["/**\n * Skills catalog manifest types.\n *\n * Defines the contract between the catalog, scaffold tooling, and future installer.\n *\n * @module skills/manifest\n */\n\n/**\n * Supported deployment targets for skill filtering.\n */\nexport type SkillTarget = 'node' | 'vercel' | 'lambda' | 'cloudflare' | 'all';\n\n/**\n * Skill categories for organizing the catalog.\n */\nexport type SkillCategory =\n  | 'setup'\n  | 'deployment'\n  | 'development'\n  | 'config'\n  | 'testing'\n  | 'guides'\n  | 'production'\n  | 'extensibility';\n\n/**\n * Bundle membership for curated scaffold presets.\n */\nexport type SkillBundle = 'recommended' | 'minimal' | 'full';\n\n/**\n * Install destination types for future provider wiring.\n */\nexport type SkillDestination = 'project-local' | '.claude/skills' | 'codex' | 'gemini';\n\n/**\n * Merge strategy when installing a skill that already exists at the destination.\n */\nexport type SkillMergeStrategy = 'overwrite' | 'skip-existing';\n\n/**\n * Install configuration for a catalog skill.\n */\nexport interface SkillInstallConfig {\n  /** Where this skill can be installed */\n  destinations: SkillDestination[];\n  /** How to handle existing skills at the destination */\n  mergeStrategy: SkillMergeStrategy;\n  /** Other skills this depends on (by name) */\n  dependencies?: string[];\n}\n\n/**\n * Metadata for a single reference file within a skill's references/ directory.\n * Extracted from YAML frontmatter or inferred from the markdown heading.\n */\nexport interface SkillReferenceEntry {\n  /** Reference name — matches filename without extension */\n  name: string;\n  /** Short description from frontmatter or first paragraph */\n  description: string;\n}\n\n/**\n * A single entry in the skills catalog manifest.\n *\n * This is the core contract connecting SKILL.md files to scaffolding,\n * future installation, and provider-specific destinations.\n */\nexport interface SkillCatalogEntry {\n  /** Unique skill name — matches SKILL.md frontmatter `name` */\n  name: string;\n  /** Skill category for organization */\n  category: SkillCategory;\n  /** Short description */\n  description: string;\n  /** Path to the skill directory, relative to catalog/ */\n  path: string;\n  /** Deployment targets this skill applies to */\n  targets: SkillTarget[];\n  /** Whether the skill has scripts/, references/, or assets/ directories */\n  hasResources: boolean;\n  /** Resolved reference metadata from references/ directory */\n  references?: SkillReferenceEntry[];\n  /** Target-specific storage defaults (e.g., { node: 'redis-docker', vercel: 'vercel-kv' }) */\n  storageDefault?: Record<string, string>;\n  /** Tags for secondary filtering and search */\n  tags: string[];\n  /** Bundle membership for scaffold presets */\n  bundle?: SkillBundle[];\n  /** Install configuration for future distribution (optional — not yet used by CLI) */\n  install?: SkillInstallConfig;\n}\n\n/**\n * The skills catalog manifest — single source of truth for scaffold and install tooling.\n */\nexport interface SkillManifest {\n  /** Manifest schema version */\n  version: 1;\n  /** All catalog skills */\n  skills: SkillCatalogEntry[];\n}\n\n/** Valid deployment targets for manifest validation */\nexport const VALID_TARGETS: readonly SkillTarget[] = ['node', 'vercel', 'lambda', 'cloudflare', 'all'];\n\n/** Valid categories for manifest validation */\nexport const VALID_CATEGORIES: readonly SkillCategory[] = [\n  'setup',\n  'deployment',\n  'development',\n  'config',\n  'testing',\n  'guides',\n  'production',\n  'extensibility',\n];\n\n/** Valid bundles for manifest validation */\nexport const VALID_BUNDLES: readonly SkillBundle[] = ['recommended', 'minimal', 'full'];\n"]}

package/catalog/adapters/create-adapter/SKILL.md

@@ -1,127 +0,0 @@
----
-name: create-adapter
-description: Create custom adapters that convert external definitions into MCP tools, resources, and prompts. Use when building integrations beyond OpenAPI, connecting to proprietary APIs, or generating tools from custom schemas.
-tags: [adapter, custom, dynamic-adapter, integration, codegen]
-priority: 6
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/adapters/overview
----
-
-# Creating Custom Adapters
-
-Build adapters that automatically generate MCP tools, resources, and prompts from external sources — databases, GraphQL schemas, proprietary APIs, or any definition format.
-
-## When to Use
-
-Create a custom adapter when:
-
-- The built-in OpenAPI adapter doesn't cover your integration (GraphQL, gRPC, custom protocols)
-- You want to auto-generate tools from a database schema or config file
-- You need to dynamically create tools at runtime based on external state
-
-## Step 1: Extend DynamicAdapter
-
-```typescript
-import { DynamicAdapter, type FrontMcpAdapterResponse } from '@frontmcp/sdk';
-
-interface MyAdapterOptions {
-  endpoint: string;
-  apiKey: string;
-}
-
-class MyApiAdapter extends DynamicAdapter<MyAdapterOptions> {
-  declare __options_brand: MyAdapterOptions;
-
-  async fetch(): Promise<FrontMcpAdapterResponse> {
-    // Fetch definitions from external source
-    const res = await globalThis.fetch(this.options.endpoint, {
-      headers: { Authorization: `Bearer ${this.options.apiKey}` },
-    });
-    const schema = await res.json();
-
-    // Convert to MCP tool definitions
-    return {
-      tools: schema.operations.map((op: { name: string; description: string; params: Record<string, unknown> }) => ({
-        name: op.name,
-        description: op.description,
-        inputSchema: this.convertParams(op.params),
-        execute: async (input: Record<string, unknown>) => {
-          return this.callApi(op.name, input);
-        },
-      })),
-      resources: [],
-      prompts: [],
-    };
-  }
-
-  private convertParams(params: Record<string, unknown>) {
-    // Convert external param definitions to Zod schemas
-    // ...
-  }
-
-  private async callApi(operation: string, input: Record<string, unknown>) {
-    // Call the external API
-    // ...
-  }
-}
-```
-
-## Step 2: Register
-
-```typescript
-@App({
-  name: 'MyApp',
-  adapters: [
-    MyApiAdapter.init({
-      name: 'my-api',
-      endpoint: 'https://api.example.com/schema',
-      apiKey: process.env.API_KEY!,
-    }),
-  ],
-})
-class MyApp {}
-```
-
-## FrontMcpAdapterResponse
-
-The `fetch()` method returns tools, resources, and prompts to register:
-
-```typescript
-interface FrontMcpAdapterResponse {
-  tools?: AdapterToolDefinition[];
-  resources?: AdapterResourceDefinition[];
-  prompts?: AdapterPromptDefinition[];
-}
-```
-
-## Static init()
-
-`DynamicAdapter` provides a static `init()` method inherited by all subclasses:
-
-```typescript
-// Usage — no manual instantiation needed
-const adapter = MyApiAdapter.init({
-  name: 'my-api',        // Required: adapter name (used for tool namespacing)
-  endpoint: '...',
-  apiKey: '...',
-});
-
-// Register in @App
-@App({ adapters: [adapter] })
-```
-
-## Nx Generator
-
-```bash
-nx generate @frontmcp/nx:adapter my-adapter --project=my-app
-```
-
-Creates a `DynamicAdapter` subclass in `src/adapters/my-adapter.adapter.ts`.
-
-## Reference
-
-- Adapter docs: [docs.agentfront.dev/frontmcp/adapters/overview](https://docs.agentfront.dev/frontmcp/adapters/overview)
-- `DynamicAdapter` base: import from `@frontmcp/sdk` — [source](https://github.com/agentfront/frontmcp/tree/main/libs/sdk/src/common/dynamic/dynamic.adapter.ts)
-- `FrontMcpAdapterResponse`: import from `@frontmcp/sdk` — [source](https://github.com/agentfront/frontmcp/tree/main/libs/sdk/src/common/interfaces/adapter.interface.ts)

package/catalog/adapters/official-adapters/SKILL.md

@@ -1,136 +0,0 @@
----
-name: official-adapters
-description: Use the OpenAPI adapter to convert REST APIs into MCP tools automatically. Use when integrating external APIs, OpenAPI specs, or converting Swagger docs to MCP tools.
-tags: [adapters, openapi, rest-api, swagger, integration]
-priority: 7
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/adapters/overview
----
-
-# Official Adapters
-
-Adapters convert external definitions (OpenAPI specs, Lambda functions, etc.) into MCP tools, resources, and prompts automatically.
-
-## OpenAPI Adapter
-
-The primary official adapter. Converts OpenAPI/Swagger specifications into MCP tools — one tool per operation.
-
-### Installation
-
-```typescript
-import { OpenApiAdapter } from '@frontmcp/adapters';
-
-@App({
-  name: 'MyApp',
-  adapters: [
-    OpenApiAdapter.init({
-      name: 'petstore',
-      specUrl: 'https://petstore3.swagger.io/api/v3/openapi.json',
-    }),
-  ],
-})
-class MyApp {}
-```
-
-Each OpenAPI operation becomes an MCP tool named `petstore:operationId`.
-
-### With Authentication
-
-```typescript
-// API Key auth
-OpenApiAdapter.init({
-  name: 'my-api',
-  specUrl: 'https://api.example.com/openapi.json',
-  auth: {
-    type: 'apiKey',
-    headerName: 'X-API-Key',
-    apiKey: process.env.API_KEY!,
-  },
-});
-
-// Bearer token auth
-OpenApiAdapter.init({
-  name: 'my-api',
-  specUrl: 'https://api.example.com/openapi.json',
-  auth: {
-    type: 'bearer',
-    token: process.env.API_TOKEN!,
-  },
-});
-
-// OAuth auth
-OpenApiAdapter.init({
-  name: 'my-api',
-  specUrl: 'https://api.example.com/openapi.json',
-  auth: {
-    type: 'oauth',
-    tokenUrl: 'https://auth.example.com/token',
-    clientId: process.env.CLIENT_ID!,
-    clientSecret: process.env.CLIENT_SECRET!,
-    scopes: ['read', 'write'],
-  },
-});
-```
-
-### Spec Polling
-
-Automatically refresh the OpenAPI spec at intervals:
-
-```typescript
-OpenApiAdapter.init({
-  name: 'evolving-api',
-  specUrl: 'https://api.example.com/openapi.json',
-  polling: {
-    intervalMs: 300000, // Re-fetch every 5 minutes
-  },
-});
-```
-
-### Inline Spec
-
-Provide the OpenAPI spec directly instead of fetching from URL:
-
-```typescript
-OpenApiAdapter.init({
-  name: 'my-api',
-  spec: {
-    openapi: '3.0.0',
-    info: { title: 'My API', version: '1.0.0' },
-    paths: { ... },
-  },
-})
-```
-
-### Multiple Adapters
-
-Register adapters from different APIs in the same app:
-
-```typescript
-@App({
-  name: 'IntegrationHub',
-  adapters: [
-    OpenApiAdapter.init({ name: 'github', specUrl: 'https://api.github.com/openapi.json' }),
-    OpenApiAdapter.init({ name: 'jira', specUrl: 'https://jira.example.com/openapi.json' }),
-    OpenApiAdapter.init({ name: 'slack', specUrl: 'https://slack.com/openapi.json' }),
-  ],
-})
-class IntegrationHub {}
-// Tools: github:createIssue, jira:createTicket, slack:postMessage, etc.
-```
-
-## Adapter vs Plugin
-
-| Aspect      | Adapter                              | Plugin                              |
-| ----------- | ------------------------------------ | ----------------------------------- |
-| Purpose     | Generate tools from external sources | Add cross-cutting behavior          |
-| Output      | Tools, resources, prompts            | Lifecycle hooks, context extensions |
-| Examples    | OpenAPI → MCP tools                  | Caching, auth, logging              |
-| When to use | Integrating APIs                     | Adding middleware                   |
-
-## Reference
-
-- Adapter docs: [docs.agentfront.dev/frontmcp/adapters/overview](https://docs.agentfront.dev/frontmcp/adapters/overview)
-- OpenAPI adapter: [`@frontmcp/adapters`](https://docs.agentfront.dev/frontmcp/adapters/openapi-adapter)
-- Spec polling: [docs.agentfront.dev/frontmcp/adapters/openapi-polling](https://docs.agentfront.dev/frontmcp/adapters/openapi-polling)

package/catalog/auth/configure-auth/SKILL.md

@@ -1,250 +0,0 @@
----
-name: configure-auth
-description: Set up authentication with public, transparent, local, or remote auth modes. Use when adding auth, OAuth, login, session security, or protecting tools and resources.
-tags:
-  - auth
-  - oauth
-  - security
-bundle:
-  - recommended
-  - full
-visibility: both
-priority: 10
-parameters:
-  - name: mode
-    description: Authentication mode (public, transparent, local, remote)
-    type: string
-    required: false
-    default: public
-  - name: provider
-    description: OAuth provider URL for transparent or remote modes
-    type: string
-    required: false
-examples:
-  - scenario: Public mode with anonymous scopes
-    parameters:
-      mode: public
-    expected-outcome: Server accepts all connections with anonymous scopes and session TTL
-  - scenario: Transparent mode validating external JWTs
-    parameters:
-      mode: transparent
-      provider: https://auth.example.com
-    expected-outcome: Server validates JWTs from the configured provider against the expected audience
-  - scenario: Local mode with server-signed tokens
-    parameters:
-      mode: local
-    expected-outcome: Server signs its own JWT tokens for client authentication
-  - scenario: Remote mode with full OAuth flow
-    parameters:
-      mode: remote
-      provider: https://auth.example.com
-    expected-outcome: Server redirects clients through a remote OAuth authorization flow
-license: Apache-2.0
-compatibility: Requires Node.js 18+ and @frontmcp/auth package
-metadata:
-  category: auth
-  difficulty: intermediate
-  docs: https://docs.agentfront.dev/frontmcp/authentication/overview
----
-
-# Configure Authentication for FrontMCP
-
-This skill covers setting up authentication in a FrontMCP server. FrontMCP supports four auth modes, each suited to different deployment scenarios. All authentication logic lives in the `@frontmcp/auth` library.
-
-## Auth Modes Overview
-
-| Mode          | Use Case                                   | Token Issuer        |
-| ------------- | ------------------------------------------ | ------------------- |
-| `public`      | Open access with optional scoping          | None                |
-| `transparent` | Validate externally-issued JWTs            | External provider   |
-| `local`       | Server signs its own tokens                | The FrontMCP server |
-| `remote`      | Full OAuth 2.1 flow with external provider | External provider   |
-
-## Mode 1: Public
-
-Public mode allows all connections without authentication. Use this for development or open APIs where access control is handled elsewhere.
-
-```typescript
-@App({
-  auth: {
-    mode: 'public',
-    sessionTtl: 3600,
-    anonymousScopes: ['read'],
-  },
-})
-class MyApp {}
-```
-
-- `sessionTtl` -- session lifetime in seconds.
-- `anonymousScopes` -- scopes granted to all unauthenticated clients.
-
-## Mode 2: Transparent
-
-Transparent mode validates JWTs issued by an external provider without initiating an OAuth flow. The server fetches the provider's JWKS to verify token signatures.
-
-```typescript
-@App({
-  auth: {
-    mode: 'transparent',
-    provider: 'https://auth.example.com',
-    expectedAudience: 'my-api',
-  },
-})
-class MyApp {}
-```
-
-- `provider` -- the authorization server URL. FrontMCP fetches JWKS from `{provider}/.well-known/jwks.json`.
-- `expectedAudience` -- the `aud` claim value that tokens must contain.
-
-Use transparent mode when clients already have tokens from your identity provider and the server only needs to verify them.
-
-## Mode 3: Local
-
-Local mode lets the FrontMCP server sign its own JWT tokens. This is useful for internal services or environments where an external identity provider is not available.
-
-```typescript
-@App({
-  auth: {
-    mode: 'local',
-    local: {
-      issuer: 'my-server',
-      audience: 'my-api',
-    },
-  },
-})
-class MyApp {}
-```
-
-- `local.issuer` -- the `iss` claim set in generated tokens.
-- `local.audience` -- the `aud` claim set in generated tokens.
-
-The server generates a signing key pair on startup (or loads one from the configured key store). Clients obtain tokens through a server-provided endpoint.
-
-## Mode 4: Remote
-
-Remote mode performs a full OAuth 2.1 authorization flow with an external provider. Clients are redirected to the provider for authentication and return with an authorization code.
-
-```typescript
-@App({
-  auth: {
-    mode: 'remote',
-    provider: 'https://auth.example.com',
-    clientId: 'xxx',
-  },
-})
-class MyApp {}
-```
-
-- `provider` -- the OAuth 2.1 authorization server URL.
-- `clientId` -- the OAuth client identifier registered with the provider.
-
-## OAuth Local Dev Flow
-
-For local development with `remote` or `transparent` mode, you can skip the full OAuth flow by setting the environment to development:
-
-```typescript
-@App({
-  auth: {
-    mode: 'remote',
-    provider: 'https://auth.example.com',
-    clientId: 'dev-client-id',
-  },
-})
-class MyApp {}
-```
-
-When `NODE_ENV=development`, FrontMCP relaxes token validation to support local identity provider instances (e.g., a local Keycloak or mock OAuth server). Tokens are still validated, but HTTPS requirements and strict issuer checks are loosened.
-
-## Multi-App Auth
-
-Each `@App` in a FrontMCP server can have a different auth configuration. This is useful when a single server hosts multiple logical applications with different security requirements:
-
-```typescript
-@App({
-  name: 'public-api',
-  auth: {
-    mode: 'public',
-    sessionTtl: 3600,
-    anonymousScopes: ['read'],
-  },
-  tools: [PublicSearchTool, PublicInfoTool],
-})
-class PublicApi {}
-
-@App({
-  name: 'admin-api',
-  auth: {
-    mode: 'remote',
-    provider: 'https://auth.example.com',
-    clientId: 'admin-client',
-  },
-  tools: [AdminTool, ConfigTool],
-})
-class AdminApi {}
-```
-
-## Credential Vault
-
-The credential vault stores downstream API tokens obtained during the OAuth flow. Use it when your MCP tools need to call external APIs on behalf of the authenticated user:
-
-```typescript
-@App({
-  auth: {
-    mode: 'remote',
-    provider: 'https://auth.example.com',
-    clientId: 'mcp-client-id',
-  },
-  vault: {
-    encryption: {
-      secret: process.env['VAULT_SECRET'],
-    },
-    providers: [
-      {
-        name: 'github',
-        type: 'oauth2',
-        scopes: ['repo', 'read:user'],
-      },
-      {
-        name: 'slack',
-        type: 'oauth2',
-        scopes: ['chat:write', 'channels:read'],
-      },
-    ],
-  },
-})
-class MyApp {}
-```
-
-Tools access downstream credentials via the `this.authProviders` context extension:
-
-```typescript
-@Tool({ name: 'create_github_issue' })
-class CreateGithubIssueTool extends ToolContext {
-  async execute(input: { title: string; body: string }) {
-    // Access downstream credentials via the authProviders context extension
-    const github = await this.authProviders.get('github');
-    const headers = await this.authProviders.headers('github');
-    // Use headers to call GitHub API
-  }
-}
-```
-
-The `authProviders` accessor (from `@frontmcp/auth`) provides:
-
-- `get(provider)` -- get the credential/token for a provider.
-- `headers(provider)` -- get pre-formatted auth headers for HTTP requests.
-- `has(provider)` -- check if a provider is configured.
-- `refresh(provider)` -- force refresh the credential.
-
-## Common Mistakes
-
-- **Using memory session store in production** -- sessions are lost on restart. Use Redis or Vercel KV.
-- **Hardcoding secrets** -- use environment variables for `clientId`, vault secrets, and Redis passwords.
-- **Missing audience validation** -- always set the audience field. Without it, tokens from any audience would be accepted.
-
-## Reference
-
-- Auth docs: [docs.agentfront.dev/frontmcp/authentication/overview](https://docs.agentfront.dev/frontmcp/authentication/overview)
-- Auth package: `@frontmcp/auth` — [source](https://github.com/agentfront/frontmcp/tree/main/libs/auth)
-- Auth options interface: import `AuthOptionsInput` from `@frontmcp/auth` — [source](https://github.com/agentfront/frontmcp/tree/main/libs/auth/src/options)
-- Credential vault: import from `@frontmcp/auth` — [source](https://github.com/agentfront/frontmcp/tree/main/libs/auth/src/vault)