@constructive-io/graphql-codegen 4.7.3 → 4.8.0

package/core/generate.js

@@ -66,6 +66,18 @@ const target_docs_generator_1 = require("./codegen/target-docs-generator");
 const introspect_1 = require("./introspect");
 const output_1 = require("./output");
 const pipeline_1 = require("./pipeline");
+const workspace_1 = require("./workspace");
+function resolveSkillsOutputDir(config, outputRoot) {
+    const workspaceRoot = (0, workspace_1.findWorkspaceRoot)(node_path_1.default.resolve(outputRoot)) ??
+        (0, workspace_1.findWorkspaceRoot)(process.cwd()) ??
+        process.cwd();
+    if (config.skillsPath) {
+        return node_path_1.default.isAbsolute(config.skillsPath)
+            ? config.skillsPath
+            : node_path_1.default.resolve(workspaceRoot, config.skillsPath);
+    }
+    return node_path_1.default.resolve(workspaceRoot, 'skills');
+}
 async function generate(options = {}, internalOptions) {
     // Apply defaults to get resolved config
     const config = (0, config_1.getConfigOptions)(options);
@@ -261,6 +273,8 @@ async function generate(options = {}, internalOptions) {
         ...(customOperations.mutations ?? []),
     ];
     const allMcpTools = [];
+    const targetName = internalOptions?.targetName ?? 'default';
+    const skillsToWrite = [];
     if (runOrm) {
         if (docsConfig.readme) {
             const readme = (0, docs_generator_2.generateOrmReadme)(tables, allCustomOps);
@@ -274,8 +288,8 @@ async function generate(options = {}, internalOptions) {
             allMcpTools.push(...(0, docs_generator_2.getOrmMcpTools)(tables, allCustomOps));
         }
         if (docsConfig.skills) {
-            for (const skill of (0, docs_generator_2.generateOrmSkills)(tables, allCustomOps)) {
-                filesToWrite.push({ path: node_path_1.default.posix.join('orm', skill.fileName), content: skill.content });
+            for (const skill of (0, docs_generator_2.generateOrmSkills)(tables, allCustomOps, targetName)) {
+                skillsToWrite.push({ path: skill.fileName, content: skill.content });
             }
         }
     }
@@ -292,8 +306,8 @@ async function generate(options = {}, internalOptions) {
             allMcpTools.push(...(0, hooks_docs_generator_1.getHooksMcpTools)(tables, allCustomOps));
         }
         if (docsConfig.skills) {
-            for (const skill of (0, hooks_docs_generator_1.generateHooksSkills)(tables, allCustomOps)) {
-                filesToWrite.push({ path: node_path_1.default.posix.join('hooks', skill.fileName), content: skill.content });
+            for (const skill of (0, hooks_docs_generator_1.generateHooksSkills)(tables, allCustomOps, targetName)) {
+                skillsToWrite.push({ path: skill.fileName, content: skill.content });
             }
         }
     }
@@ -313,8 +327,8 @@ async function generate(options = {}, internalOptions) {
             allMcpTools.push(...(0, docs_generator_1.getCliMcpTools)(tables, allCustomOps, toolName));
         }
         if (docsConfig.skills) {
-            for (const skill of (0, docs_generator_1.generateSkills)(tables, allCustomOps, toolName)) {
-                filesToWrite.push({ path: node_path_1.default.posix.join('cli', skill.fileName), content: skill.content });
+            for (const skill of (0, docs_generator_1.generateSkills)(tables, allCustomOps, toolName, targetName)) {
+                skillsToWrite.push({ path: skill.fileName, content: skill.content });
             }
         }
     }
@@ -352,6 +366,21 @@ async function generate(options = {}, internalOptions) {
             };
         }
         allFilesWritten.push(...(writeResult.filesWritten ?? []));
+        if (skillsToWrite.length > 0) {
+            const skillsOutputDir = resolveSkillsOutputDir(config, outputRoot);
+            const skillsWriteResult = await (0, output_1.writeGeneratedFiles)(skillsToWrite, skillsOutputDir, [], {
+                pruneStaleFiles: false,
+            });
+            if (!skillsWriteResult.success) {
+                return {
+                    success: false,
+                    message: `Failed to write generated skill files: ${skillsWriteResult.errors?.join(', ')}`,
+                    output: skillsOutputDir,
+                    errors: skillsWriteResult.errors,
+                };
+            }
+            allFilesWritten.push(...(skillsWriteResult.filesWritten ?? []));
+        }
     }
     const generators = [
         runReactQuery && 'React Query',
@@ -530,7 +559,7 @@ async function generateMulti(options) {
                 dryRun,
                 schemaOnly,
                 schemaOnlyFilename: schemaOnly ? `${name}.graphql` : undefined,
-            }, useUnifiedCli ? { skipCli: true } : undefined);
+            }, useUnifiedCli ? { skipCli: true, targetName: name } : { targetName: name });
             results.push({ name, result });
             if (!result.success) {
                 hasError = true;
@@ -613,17 +642,24 @@ async function generateMulti(options) {
             if (docsConfig.mcp) {
                 allMcpTools.push(...(0, docs_generator_1.getMultiTargetCliMcpTools)(docsInput));
             }
-            if (docsConfig.skills) {
-                for (const skill of (0, docs_generator_1.generateMultiTargetSkills)(docsInput)) {
-                    cliFilesToWrite.push({ path: node_path_1.default.posix.join('cli', skill.fileName), content: skill.content });
-                }
-            }
             if (docsConfig.mcp && allMcpTools.length > 0) {
                 const mcpFile = (0, target_docs_generator_1.generateCombinedMcpConfig)(allMcpTools, toolName);
                 cliFilesToWrite.push({ path: node_path_1.default.posix.join('cli', mcpFile.fileName), content: mcpFile.content });
             }
             const { writeGeneratedFiles: writeFiles } = await Promise.resolve().then(() => __importStar(require('./output')));
             await writeFiles(cliFilesToWrite, '.', [], { pruneStaleFiles: false });
+            if (docsConfig.skills) {
+                const cliSkillsToWrite = (0, docs_generator_1.generateMultiTargetSkills)(docsInput).map((skill) => ({
+                    path: skill.fileName,
+                    content: skill.content,
+                }));
+                const firstTargetResolved = (0, config_1.getConfigOptions)({
+                    ...(firstTargetConfig ?? {}),
+                    ...(cliOverrides ?? {}),
+                });
+                const skillsOutputDir = resolveSkillsOutputDir(firstTargetResolved, firstTargetResolved.output);
+                await writeFiles(cliSkillsToWrite, skillsOutputDir, [], { pruneStaleFiles: false });
+            }
         }
         // Generate root-root README if multi-target
         if (names.length > 1 && targetInfos.length > 0 && !dryRun) {

package/core/workspace.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Find the workspace root directory.
+ *
+ * Search order:
+ * 1. pnpm-workspace.yaml (pnpm workspaces)
+ * 2. lerna.json (lerna workspaces)
+ * 3. package.json with "workspaces" field (npm/yarn workspaces)
+ * 4. Nearest package.json (fallback for non-workspace projects)
+ *
+ * @param cwd - Starting directory to search from (defaults to process.cwd())
+ * @returns The workspace root path, or null if nothing found
+ */
+export declare function findWorkspaceRoot(cwd?: string): string | null;

package/core/workspace.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findWorkspaceRoot = findWorkspaceRoot;
+/**
+ * Workspace detection utilities
+ *
+ * Finds the root of a workspace by walking up directories looking for
+ * workspace markers (pnpm-workspace.yaml, lerna.json, package.json with workspaces).
+ * Falls back to the nearest package.json directory.
+ *
+ * Inspired by @pgpmjs/env walkUp / resolvePnpmWorkspace patterns.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * Walk up directories from startDir looking for a file.
+ * Returns the directory containing the file, or null if not found.
+ */
+function walkUp(startDir, filename) {
+    let currentDir = (0, node_path_1.resolve)(startDir);
+    while (currentDir) {
+        const targetPath = (0, node_path_1.resolve)(currentDir, filename);
+        if ((0, node_fs_1.existsSync)(targetPath)) {
+            return currentDir;
+        }
+        const parentDir = (0, node_path_1.dirname)(currentDir);
+        if (parentDir === currentDir) {
+            break;
+        }
+        currentDir = parentDir;
+    }
+    return null;
+}
+/**
+ * Find the first pnpm workspace root by looking for pnpm-workspace.yaml
+ */
+function findPnpmWorkspace(cwd) {
+    return walkUp(cwd, 'pnpm-workspace.yaml');
+}
+/**
+ * Find the first lerna workspace root by looking for lerna.json
+ */
+function findLernaWorkspace(cwd) {
+    return walkUp(cwd, 'lerna.json');
+}
+/**
+ * Find the first npm/yarn workspace root by looking for package.json with workspaces field
+ */
+function findNpmWorkspace(cwd) {
+    let currentDir = (0, node_path_1.resolve)(cwd);
+    const root = (0, node_path_1.parse)(currentDir).root;
+    while (currentDir !== root) {
+        const packageJsonPath = (0, node_path_1.resolve)(currentDir, 'package.json');
+        if ((0, node_fs_1.existsSync)(packageJsonPath)) {
+            try {
+                const packageJson = JSON.parse((0, node_fs_1.readFileSync)(packageJsonPath, 'utf8'));
+                if (packageJson.workspaces) {
+                    return currentDir;
+                }
+            }
+            catch {
+                // Ignore JSON parse errors
+            }
+        }
+        currentDir = (0, node_path_1.dirname)(currentDir);
+    }
+    return null;
+}
+/**
+ * Find the nearest package.json directory (fallback)
+ */
+function findPackageRoot(cwd) {
+    return walkUp(cwd, 'package.json');
+}
+/**
+ * Find the workspace root directory.
+ *
+ * Search order:
+ * 1. pnpm-workspace.yaml (pnpm workspaces)
+ * 2. lerna.json (lerna workspaces)
+ * 3. package.json with "workspaces" field (npm/yarn workspaces)
+ * 4. Nearest package.json (fallback for non-workspace projects)
+ *
+ * @param cwd - Starting directory to search from (defaults to process.cwd())
+ * @returns The workspace root path, or null if nothing found
+ */
+function findWorkspaceRoot(cwd = process.cwd()) {
+    return (findPnpmWorkspace(cwd) ??
+        findLernaWorkspace(cwd) ??
+        findNpmWorkspace(cwd) ??
+        findPackageRoot(cwd));
+}

package/esm/core/codegen/cli/docs-generator.d.ts

@@ -5,7 +5,7 @@ export type { GeneratedDocFile, McpTool } from '../docs-utils';
 export declare function generateReadme(tables: CleanTable[], customOperations: CleanOperation[], toolName: string): GeneratedDocFile;
 export declare function generateAgentsDocs(tables: CleanTable[], customOperations: CleanOperation[], toolName: string): GeneratedDocFile;
 export declare function getCliMcpTools(tables: CleanTable[], customOperations: CleanOperation[], toolName: string): McpTool[];
-export declare function generateSkills(tables: CleanTable[], customOperations: CleanOperation[], toolName: string): GeneratedDocFile[];
+export declare function generateSkills(tables: CleanTable[], customOperations: CleanOperation[], toolName: string, targetName: string): GeneratedDocFile[];
 export interface MultiTargetDocsInput {
     toolName: string;
     builtinNames: {

package/esm/core/codegen/cli/docs-generator.js

@@ -1,5 +1,5 @@
 import { toKebabCase } from 'komoji';
-import { formatArgType, getEditableFields, getReadmeHeader, getReadmeFooter, gqlTypeToJsonSchemaType, buildSkillFile, } from '../docs-utils';
+import { formatArgType, getEditableFields, getReadmeHeader, getReadmeFooter, gqlTypeToJsonSchemaType, buildSkillFile, buildSkillReference, } from '../docs-utils';
 import { getScalarFields, getTableNames, getPrimaryKeyInfo, } from '../utils';
 export { resolveDocsConfig } from '../docs-utils';
 export function generateReadme(tables, customOperations, toolName) {
@@ -513,12 +513,16 @@ export function getCliMcpTools(tables, customOperations, toolName) {
     }
     return tools;
 }
-export function generateSkills(tables, customOperations, toolName) {
+export function generateSkills(tables, customOperations, toolName, targetName) {
     const files = [];
+    const skillName = `cli-${targetName}`;
+    const referenceNames = [];
+    // Context reference
+    referenceNames.push('context');
     files.push({
-        fileName: 'skills/context.md',
-        content: buildSkillFile({
-            name: `${toolName}-context`,
+        fileName: `${skillName}/references/context.md`,
+        content: buildSkillReference({
+            title: 'Context Management',
             description: `Manage API endpoint contexts for ${toolName}`,
             usage: [
                 `${toolName} context create <name> --endpoint <url>`,
@@ -542,10 +546,12 @@ export function generateSkills(tables, customOperations, toolName) {
             ],
         }),
     });
+    // Auth reference
+    referenceNames.push('auth');
     files.push({
-        fileName: 'skills/auth.md',
-        content: buildSkillFile({
-            name: `${toolName}-auth`,
+        fileName: `${skillName}/references/auth.md`,
+        content: buildSkillReference({
+            title: 'Authentication',
             description: `Manage authentication tokens for ${toolName}`,
             usage: [
                 `${toolName} auth set-token <token>`,
@@ -564,15 +570,17 @@ export function generateSkills(tables, customOperations, toolName) {
             ],
         }),
     });
+    // Table references
     for (const table of tables) {
         const { singularName } = getTableNames(table);
         const kebab = toKebabCase(singularName);
         const pk = getPrimaryKeyInfo(table)[0];
         const editableFields = getEditableFields(table);
+        referenceNames.push(kebab);
         files.push({
-            fileName: `skills/${kebab}.md`,
-            content: buildSkillFile({
-                name: `${toolName}-${kebab}`,
+            fileName: `${skillName}/references/${kebab}.md`,
+            content: buildSkillReference({
+                title: singularName,
                 description: `CRUD operations for ${table.name} records via ${toolName} CLI`,
                 usage: [
                     `${toolName} ${kebab} list`,
@@ -596,29 +604,21 @@ export function generateSkills(tables, customOperations, toolName) {
                         description: `Get a ${singularName} by ${pk.name}`,
                         code: [`${toolName} ${kebab} get --${pk.name} <value>`],
                     },
-                    {
-                        description: `Update a ${singularName}`,
-                        code: [
-                            `${toolName} ${kebab} update --${pk.name} <value> --${editableFields[0]?.name || 'field'} "new-value"`,
-                        ],
-                    },
-                    {
-                        description: `Delete a ${singularName}`,
-                        code: [`${toolName} ${kebab} delete --${pk.name} <value>`],
-                    },
                 ],
             }),
         });
     }
+    // Custom operation references
     for (const op of customOperations) {
         const kebab = toKebabCase(op.name);
         const usage = op.args.length > 0
             ? `${toolName} ${kebab} ${op.args.map((a) => `--${a.name} <value>`).join(' ')}`
             : `${toolName} ${kebab}`;
+        referenceNames.push(kebab);
         files.push({
-            fileName: `skills/${kebab}.md`,
-            content: buildSkillFile({
-                name: `${toolName}-${kebab}`,
+            fileName: `${skillName}/references/${kebab}.md`,
+            content: buildSkillReference({
+                title: op.name,
                 description: op.description || `Execute the ${op.name} ${op.kind}`,
                 usage: [usage],
                 examples: [
@@ -630,6 +630,39 @@ export function generateSkills(tables, customOperations, toolName) {
             }),
         });
     }
+    // Overview SKILL.md
+    const tableKebabs = tables.slice(0, 5).map((t) => toKebabCase(getTableNames(t).singularName));
+    files.push({
+        fileName: `${skillName}/SKILL.md`,
+        content: buildSkillFile({
+            name: skillName,
+            description: `CLI tool (${toolName}) for the ${targetName} API — provides CRUD commands for ${tables.length} tables and ${customOperations.length} custom operations`,
+            usage: [
+                `# Context management`,
+                `${toolName} context create <name> --endpoint <url>`,
+                `${toolName} context use <name>`,
+                '',
+                `# Authentication`,
+                `${toolName} auth set-token <token>`,
+                '',
+                `# CRUD for any table (e.g. ${tableKebabs[0] || 'model'})`,
+                `${toolName} ${tableKebabs[0] || 'model'} list`,
+                `${toolName} ${tableKebabs[0] || 'model'} get --id <value>`,
+                `${toolName} ${tableKebabs[0] || 'model'} create --<field> <value>`,
+            ],
+            examples: [
+                {
+                    description: 'Set up and query',
+                    code: [
+                        `${toolName} context create local --endpoint http://localhost:5000/graphql`,
+                        `${toolName} context use local`,
+                        `${toolName} auth set-token <token>`,
+                        `${toolName} ${tableKebabs[0] || 'model'} list`,
+                    ],
+                },
+            ],
+        }, referenceNames),
+    });
     return files;
 }
 export function generateMultiTargetReadme(input) {
@@ -1256,22 +1289,26 @@ export function getMultiTargetCliMcpTools(input) {
 export function generateMultiTargetSkills(input) {
     const { toolName, builtinNames, targets } = input;
     const files = [];
-    const contextUsage = [
-        `${toolName} ${builtinNames.context} create <name>`,
-        `${toolName} ${builtinNames.context} list`,
-        `${toolName} ${builtinNames.context} use <name>`,
-        `${toolName} ${builtinNames.context} current`,
-        `${toolName} ${builtinNames.context} delete <name>`,
-    ];
+    // Generate one skill per target, plus a shared cli-common skill for context/auth
+    const commonSkillName = 'cli-common';
+    const commonReferenceNames = [];
     const contextCreateFlags = targets
         .map((t) => `--${t.name}-endpoint <url>`)
         .join(' ');
+    // Context reference
+    commonReferenceNames.push('context');
     files.push({
-        fileName: `skills/${builtinNames.context}.md`,
-        content: buildSkillFile({
-            name: `${toolName}-${builtinNames.context}`,
+        fileName: `${commonSkillName}/references/context.md`,
+        content: buildSkillReference({
+            title: 'Context Management',
             description: `Manage API endpoint contexts for ${toolName} (multi-target: ${targets.map((t) => t.name).join(', ')})`,
-            usage: contextUsage,
+            usage: [
+                `${toolName} ${builtinNames.context} create <name>`,
+                `${toolName} ${builtinNames.context} list`,
+                `${toolName} ${builtinNames.context} use <name>`,
+                `${toolName} ${builtinNames.context} current`,
+                `${toolName} ${builtinNames.context} delete <name>`,
+            ],
             examples: [
                 {
                     description: 'Create a context for local development (accept all defaults)',
@@ -1287,20 +1324,15 @@ export function generateMultiTargetSkills(input) {
                         `${toolName} ${builtinNames.context} use production`,
                     ],
                 },
-                {
-                    description: 'List and switch contexts',
-                    code: [
-                        `${toolName} ${builtinNames.context} list`,
-                        `${toolName} ${builtinNames.context} use staging`,
-                    ],
-                },
             ],
         }),
     });
+    // Auth reference
+    commonReferenceNames.push('auth');
     files.push({
-        fileName: `skills/${builtinNames.auth}.md`,
-        content: buildSkillFile({
-            name: `${toolName}-${builtinNames.auth}`,
+        fileName: `${commonSkillName}/references/auth.md`,
+        content: buildSkillReference({
+            title: 'Authentication',
             description: `Manage authentication tokens for ${toolName} (shared across all targets)`,
             usage: [
                 `${toolName} ${builtinNames.auth} set-token <token>`,
@@ -1319,17 +1351,48 @@ export function generateMultiTargetSkills(input) {
             ],
         }),
     });
+    // Common SKILL.md
+    files.push({
+        fileName: `${commonSkillName}/SKILL.md`,
+        content: buildSkillFile({
+            name: commonSkillName,
+            description: `Shared CLI utilities for ${toolName} — context management and authentication across targets: ${targets.map((t) => t.name).join(', ')}`,
+            usage: [
+                `# Context management`,
+                `${toolName} ${builtinNames.context} create <name>`,
+                `${toolName} ${builtinNames.context} use <name>`,
+                '',
+                `# Authentication`,
+                `${toolName} ${builtinNames.auth} set-token <token>`,
+                `${toolName} ${builtinNames.auth} status`,
+            ],
+            examples: [
+                {
+                    description: 'Set up and authenticate',
+                    code: [
+                        `${toolName} ${builtinNames.context} create local`,
+                        `${toolName} ${builtinNames.context} use local`,
+                        `${toolName} ${builtinNames.auth} set-token <token>`,
+                    ],
+                },
+            ],
+        }, commonReferenceNames),
+    });
+    // Generate one skill per target with table/op references
     for (const tgt of targets) {
+        const tgtSkillName = `cli-${tgt.name}`;
+        const tgtReferenceNames = [];
         for (const table of tgt.tables) {
             const { singularName } = getTableNames(table);
             const kebab = toKebabCase(singularName);
             const pk = getPrimaryKeyInfo(table)[0];
             const editableFields = getEditableFields(table);
             const cmd = `${tgt.name}:${kebab}`;
+            tgtReferenceNames.push(kebab);
             files.push({
-                fileName: `skills/${tgt.name}-${kebab}.md`,
-                content: buildSkillFile({
-                    name: `${toolName}-${cmd}`,
+                fileName: `${tgtSkillName}/references/${kebab}.md`,
+                content: buildSkillReference({
+                    title: singularName,
                     description: `CRUD operations for ${table.name} records via ${toolName} CLI (${tgt.name} target)`,
                     usage: [
                         `${toolName} ${cmd} list`,
@@ -1349,10 +1412,6 @@ export function generateMultiTargetSkills(input) {
                                 `${toolName} ${cmd} create ${editableFields.map((f) => `--${f.name} "value"`).join(' ')}`,
                             ],
                         },
-                        {
-                            description: `Get a ${singularName} by ${pk.name}`,
-                            code: [`${toolName} ${cmd} get --${pk.name} <value>`],
-                        },
                     ],
                 }),
             });
@@ -1367,10 +1426,11 @@ export function generateMultiTargetSkills(input) {
             if (tgt.isAuthTarget && op.kind === 'mutation') {
                 usageLines.push(`${baseUsage} --save-token`);
             }
+            tgtReferenceNames.push(kebab);
             files.push({
-                fileName: `skills/${tgt.name}-${kebab}.md`,
-                content: buildSkillFile({
-                    name: `${toolName}-${cmd}`,
+                fileName: `${tgtSkillName}/references/${kebab}.md`,
+                content: buildSkillReference({
+                    title: op.name,
                     description: `${op.description || `Execute the ${op.name} ${op.kind}`} (${tgt.name} target)`,
                     usage: usageLines,
                     examples: [
@@ -1382,6 +1442,29 @@ export function generateMultiTargetSkills(input) {
                 }),
             });
         }
+        // Target SKILL.md
+        const firstKebab = tgt.tables.length > 0
+            ? toKebabCase(getTableNames(tgt.tables[0]).singularName)
+            : 'model';
+        files.push({
+            fileName: `${tgtSkillName}/SKILL.md`,
+            content: buildSkillFile({
+                name: tgtSkillName,
+                description: `CLI commands for the ${tgt.name} API target — ${tgt.tables.length} tables and ${tgt.customOperations.length} custom operations via ${toolName}`,
+                usage: [
+                    `# CRUD for ${tgt.name} tables (e.g. ${firstKebab})`,
+                    `${toolName} ${tgt.name}:${firstKebab} list`,
+                    `${toolName} ${tgt.name}:${firstKebab} get --id <value>`,
+                    `${toolName} ${tgt.name}:${firstKebab} create --<field> <value>`,
+                ],
+                examples: [
+                    {
+                        description: `Query ${tgt.name} records`,
+                        code: [`${toolName} ${tgt.name}:${firstKebab} list`],
+                    },
+                ],
+            }, tgtReferenceNames),
+        });
     }
     return files;
 }

package/esm/core/codegen/docs-utils.d.ts

@@ -20,6 +20,16 @@ export interface SkillDefinition {
     }[];
     language?: string;
 }
+export interface SkillReferenceDefinition {
+    title: string;
+    description: string;
+    usage: string[];
+    examples: {
+        description: string;
+        code: string[];
+    }[];
+    language?: string;
+}
 export declare function getReadmeHeader(title: string): string[];
 export declare function getReadmeFooter(): string[];
 export declare function resolveDocsConfig(docs: DocsConfig | boolean | undefined): DocsConfig;
@@ -27,4 +37,5 @@ export declare function formatArgType(arg: CleanOperation['args'][number]): stri
 export declare function formatTypeRef(t: CleanOperation['args'][number]['type']): string;
 export declare function getEditableFields(table: CleanTable): CleanField[];
 export declare function gqlTypeToJsonSchemaType(gqlType: string): string;
-export declare function buildSkillFile(skill: SkillDefinition): string;
+export declare function buildSkillFile(skill: SkillDefinition, referenceNames?: string[]): string;
+export declare function buildSkillReference(ref: SkillReferenceDefinition): string;

package/esm/core/codegen/docs-utils.js

@@ -79,9 +79,15 @@ export function gqlTypeToJsonSchemaType(gqlType) {
             return 'string';
     }
 }
-export function buildSkillFile(skill) {
+export function buildSkillFile(skill, referenceNames) {
     const lang = skill.language ?? 'bash';
     const lines = [];
+    // YAML frontmatter (Agent Skills format)
+    lines.push('---');
+    lines.push(`name: ${skill.name}`);
+    lines.push(`description: ${skill.description}`);
+    lines.push('---');
+    lines.push('');
     lines.push(`# ${skill.name}`);
     lines.push('');
     lines.push('<!-- @constructive-io/graphql-codegen - DO NOT EDIT -->');
@@ -108,5 +114,46 @@ export function buildSkillFile(skill) {
         lines.push('```');
         lines.push('');
     }
+    if (referenceNames && referenceNames.length > 0) {
+        lines.push('## References');
+        lines.push('');
+        lines.push('See the `references/` directory for detailed per-entity API documentation:');
+        lines.push('');
+        for (const name of referenceNames) {
+            lines.push(`- [${name}](references/${name}.md)`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export function buildSkillReference(ref) {
+    const lang = ref.language ?? 'bash';
+    const lines = [];
+    lines.push(`# ${ref.title}`);
+    lines.push('');
+    lines.push('<!-- @constructive-io/graphql-codegen - DO NOT EDIT -->');
+    lines.push('');
+    lines.push(ref.description);
+    lines.push('');
+    lines.push('## Usage');
+    lines.push('');
+    lines.push(`\`\`\`${lang}`);
+    for (const u of ref.usage) {
+        lines.push(u);
+    }
+    lines.push('```');
+    lines.push('');
+    lines.push('## Examples');
+    lines.push('');
+    for (const ex of ref.examples) {
+        lines.push(`### ${ex.description}`);
+        lines.push('');
+        lines.push(`\`\`\`${lang}`);
+        for (const cmd of ex.code) {
+            lines.push(cmd);
+        }
+        lines.push('```');
+        lines.push('');
+    }
     return lines.join('\n');
 }

package/esm/core/codegen/hooks-docs-generator.d.ts

@@ -3,4 +3,4 @@ import type { GeneratedDocFile, McpTool } from './docs-utils';
 export declare function generateHooksReadme(tables: CleanTable[], customOperations: CleanOperation[]): GeneratedDocFile;
 export declare function generateHooksAgentsDocs(tables: CleanTable[], customOperations: CleanOperation[]): GeneratedDocFile;
 export declare function getHooksMcpTools(tables: CleanTable[], customOperations: CleanOperation[]): McpTool[];
-export declare function generateHooksSkills(tables: CleanTable[], customOperations: CleanOperation[]): GeneratedDocFile[];
+export declare function generateHooksSkills(tables: CleanTable[], customOperations: CleanOperation[], targetName: string): GeneratedDocFile[];