@constructive-io/graphql-codegen 4.7.2 → 4.8.0

package/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/core/codegen/cli/docs-generator.js

@@ -525,12 +525,16 @@ function getCliMcpTools(tables, customOperations, toolName) {
     }
     return tools;
 }
-function generateSkills(tables, customOperations, toolName) {
+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: (0, docs_utils_1.buildSkillFile)({
-            name: `${toolName}-context`,
+        fileName: `${skillName}/references/context.md`,
+        content: (0, docs_utils_1.buildSkillReference)({
+            title: 'Context Management',
             description: `Manage API endpoint contexts for ${toolName}`,
             usage: [
                 `${toolName} context create <name> --endpoint <url>`,
@@ -554,10 +558,12 @@ function generateSkills(tables, customOperations, toolName) {
             ],
         }),
     });
+    // Auth reference
+    referenceNames.push('auth');
     files.push({
-        fileName: 'skills/auth.md',
-        content: (0, docs_utils_1.buildSkillFile)({
-            name: `${toolName}-auth`,
+        fileName: `${skillName}/references/auth.md`,
+        content: (0, docs_utils_1.buildSkillReference)({
+            title: 'Authentication',
             description: `Manage authentication tokens for ${toolName}`,
             usage: [
                 `${toolName} auth set-token <token>`,
@@ -576,15 +582,17 @@ function generateSkills(tables, customOperations, toolName) {
             ],
         }),
     });
+    // Table references
     for (const table of tables) {
         const { singularName } = (0, utils_1.getTableNames)(table);
         const kebab = (0, komoji_1.toKebabCase)(singularName);
         const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
         const editableFields = (0, docs_utils_1.getEditableFields)(table);
+        referenceNames.push(kebab);
         files.push({
-            fileName: `skills/${kebab}.md`,
-            content: (0, docs_utils_1.buildSkillFile)({
-                name: `${toolName}-${kebab}`,
+            fileName: `${skillName}/references/${kebab}.md`,
+            content: (0, docs_utils_1.buildSkillReference)({
+                title: singularName,
                 description: `CRUD operations for ${table.name} records via ${toolName} CLI`,
                 usage: [
                     `${toolName} ${kebab} list`,
@@ -608,29 +616,21 @@ 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 = (0, komoji_1.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: (0, docs_utils_1.buildSkillFile)({
-                name: `${toolName}-${kebab}`,
+            fileName: `${skillName}/references/${kebab}.md`,
+            content: (0, docs_utils_1.buildSkillReference)({
+                title: op.name,
                 description: op.description || `Execute the ${op.name} ${op.kind}`,
                 usage: [usage],
                 examples: [
@@ -642,6 +642,39 @@ function generateSkills(tables, customOperations, toolName) {
             }),
         });
     }
+    // Overview SKILL.md
+    const tableKebabs = tables.slice(0, 5).map((t) => (0, komoji_1.toKebabCase)((0, utils_1.getTableNames)(t).singularName));
+    files.push({
+        fileName: `${skillName}/SKILL.md`,
+        content: (0, docs_utils_1.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;
 }
 function generateMultiTargetReadme(input) {
@@ -1268,22 +1301,26 @@ function getMultiTargetCliMcpTools(input) {
 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: (0, docs_utils_1.buildSkillFile)({
-            name: `${toolName}-${builtinNames.context}`,
+        fileName: `${commonSkillName}/references/context.md`,
+        content: (0, docs_utils_1.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)',
@@ -1299,20 +1336,15 @@ 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: (0, docs_utils_1.buildSkillFile)({
-            name: `${toolName}-${builtinNames.auth}`,
+        fileName: `${commonSkillName}/references/auth.md`,
+        content: (0, docs_utils_1.buildSkillReference)({
+            title: 'Authentication',
             description: `Manage authentication tokens for ${toolName} (shared across all targets)`,
             usage: [
                 `${toolName} ${builtinNames.auth} set-token <token>`,
@@ -1331,17 +1363,48 @@ function generateMultiTargetSkills(input) {
             ],
         }),
     });
+    // Common SKILL.md
+    files.push({
+        fileName: `${commonSkillName}/SKILL.md`,
+        content: (0, docs_utils_1.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 } = (0, utils_1.getTableNames)(table);
             const kebab = (0, komoji_1.toKebabCase)(singularName);
             const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
             const editableFields = (0, docs_utils_1.getEditableFields)(table);
             const cmd = `${tgt.name}:${kebab}`;
+            tgtReferenceNames.push(kebab);
             files.push({
-                fileName: `skills/${tgt.name}-${kebab}.md`,
-                content: (0, docs_utils_1.buildSkillFile)({
-                    name: `${toolName}-${cmd}`,
+                fileName: `${tgtSkillName}/references/${kebab}.md`,
+                content: (0, docs_utils_1.buildSkillReference)({
+                    title: singularName,
                     description: `CRUD operations for ${table.name} records via ${toolName} CLI (${tgt.name} target)`,
                     usage: [
                         `${toolName} ${cmd} list`,
@@ -1361,10 +1424,6 @@ 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>`],
-                        },
                     ],
                 }),
             });
@@ -1379,10 +1438,11 @@ 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: (0, docs_utils_1.buildSkillFile)({
-                    name: `${toolName}-${cmd}`,
+                fileName: `${tgtSkillName}/references/${kebab}.md`,
+                content: (0, docs_utils_1.buildSkillReference)({
+                    title: op.name,
                     description: `${op.description || `Execute the ${op.name} ${op.kind}`} (${tgt.name} target)`,
                     usage: usageLines,
                     examples: [
@@ -1394,6 +1454,29 @@ function generateMultiTargetSkills(input) {
                 }),
             });
         }
+        // Target SKILL.md
+        const firstKebab = tgt.tables.length > 0
+            ? (0, komoji_1.toKebabCase)((0, utils_1.getTableNames)(tgt.tables[0]).singularName)
+            : 'model';
+        files.push({
+            fileName: `${tgtSkillName}/SKILL.md`,
+            content: (0, docs_utils_1.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/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/core/codegen/docs-utils.js

@@ -8,6 +8,7 @@ exports.formatTypeRef = formatTypeRef;
 exports.getEditableFields = getEditableFields;
 exports.gqlTypeToJsonSchemaType = gqlTypeToJsonSchemaType;
 exports.buildSkillFile = buildSkillFile;
+exports.buildSkillReference = buildSkillReference;
 const utils_1 = require("./utils");
 const CONSTRUCTIVE_LOGO_URL = 'https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg';
 const CONSTRUCTIVE_REPO = 'https://github.com/constructive-io/constructive';
@@ -89,9 +90,15 @@ function gqlTypeToJsonSchemaType(gqlType) {
             return 'string';
     }
 }
-function buildSkillFile(skill) {
+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 -->');
@@ -118,5 +125,46 @@ 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');
+}
+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/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[];

package/core/codegen/hooks-docs-generator.js

@@ -4,6 +4,7 @@ exports.generateHooksReadme = generateHooksReadme;
 exports.generateHooksAgentsDocs = generateHooksAgentsDocs;
 exports.getHooksMcpTools = getHooksMcpTools;
 exports.generateHooksSkills = generateHooksSkills;
+const komoji_1 = require("komoji");
 const docs_utils_1 = require("./docs-utils");
 const utils_1 = require("./utils");
 function getCustomHookName(op) {
@@ -377,8 +378,11 @@ function getHooksMcpTools(tables, customOperations) {
     }
     return tools;
 }
-function generateHooksSkills(tables, customOperations) {
+function generateHooksSkills(tables, customOperations, targetName) {
     const files = [];
+    const skillName = `hooks-${targetName}`;
+    const referenceNames = [];
+    // Generate reference files for each table
     for (const table of tables) {
         const { singularName, pluralName } = (0, utils_1.getTableNames)(table);
         const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
@@ -386,10 +390,12 @@ function generateHooksSkills(tables, customOperations) {
         const selectFields = scalarFields
             .map((f) => `${f.name}: true`)
             .join(', ');
+        const refName = (0, komoji_1.toKebabCase)(singularName);
+        referenceNames.push(refName);
         files.push({
-            fileName: `skills/${(0, utils_1.lcFirst)(singularName)}.md`,
-            content: (0, docs_utils_1.buildSkillFile)({
-                name: `hooks-${(0, utils_1.lcFirst)(singularName)}`,
+            fileName: `${skillName}/references/${refName}.md`,
+            content: (0, docs_utils_1.buildSkillReference)({
+                title: singularName,
                 description: table.description || `React Query hooks for ${table.name} data operations`,
                 language: 'typescript',
                 usage: [
@@ -429,15 +435,18 @@ function generateHooksSkills(tables, customOperations) {
             }),
         });
     }
+    // Generate reference files for custom operations
     for (const op of customOperations) {
         const hookName = getCustomHookName(op);
         const callArgs = op.args.length > 0
             ? `{ ${op.args.map((a) => `${a.name}: '<value>'`).join(', ')} }`
             : '';
+        const refName = (0, komoji_1.toKebabCase)(op.name);
+        referenceNames.push(refName);
         files.push({
-            fileName: `skills/${op.name}.md`,
-            content: (0, docs_utils_1.buildSkillFile)({
-                name: `hooks-${op.name}`,
+            fileName: `${skillName}/references/${refName}.md`,
+            content: (0, docs_utils_1.buildSkillReference)({
+                title: op.name,
                 description: op.description ||
                     `React Query ${op.kind} hook for ${op.name}`,
                 language: 'typescript',
@@ -464,5 +473,36 @@ function generateHooksSkills(tables, customOperations) {
             }),
         });
     }
+    // Generate the overview SKILL.md
+    const hookExamples = tables.slice(0, 3).map((t) => (0, utils_1.getListQueryHookName)(t));
+    files.push({
+        fileName: `${skillName}/SKILL.md`,
+        content: (0, docs_utils_1.buildSkillFile)({
+            name: skillName,
+            description: `React Query hooks for the ${targetName} API — provides typed query and mutation hooks for ${tables.length} tables and ${customOperations.length} custom operations`,
+            language: 'typescript',
+            usage: [
+                `// Import hooks`,
+                `import { ${hookExamples[0] || 'useModelQuery'} } from './hooks';`,
+                '',
+                `// Query hooks: use<Model>Query, use<Model>sQuery`,
+                `// Mutation hooks: useCreate<Model>Mutation, useUpdate<Model>Mutation, useDelete<Model>Mutation`,
+                '',
+                `const { data, isLoading } = ${hookExamples[0] || 'useModelQuery'}({`,
+                `  selection: { fields: { id: true } },`,
+                `});`,
+            ],
+            examples: [
+                {
+                    description: 'Query records',
+                    code: [
+                        `const { data, isLoading } = ${hookExamples[0] || 'useModelQuery'}({`,
+                        '  selection: { fields: { id: true } },',
+                        '});',
+                    ],
+                },
+            ],
+        }, referenceNames),
+    });
     return files;
 }

package/core/codegen/orm/docs-generator.d.ts

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

package/core/codegen/orm/docs-generator.js

@@ -4,6 +4,7 @@ exports.generateOrmReadme = generateOrmReadme;
 exports.generateOrmAgentsDocs = generateOrmAgentsDocs;
 exports.getOrmMcpTools = getOrmMcpTools;
 exports.generateOrmSkills = generateOrmSkills;
+const komoji_1 = require("komoji");
 const docs_utils_1 = require("../docs-utils");
 const utils_1 = require("../utils");
 function generateOrmReadme(tables, customOperations) {
@@ -346,30 +347,36 @@ function getOrmMcpTools(tables, customOperations) {
     }
     return tools;
 }
-function generateOrmSkills(tables, customOperations) {
+function generateOrmSkills(tables, customOperations, targetName) {
     const files = [];
+    const skillName = `orm-${targetName}`;
+    const referenceNames = [];
+    // Generate reference files for each table
     for (const table of tables) {
         const { singularName } = (0, utils_1.getTableNames)(table);
         const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
         const editableFields = (0, docs_utils_1.getEditableFields)(table);
+        const modelName = (0, utils_1.lcFirst)(singularName);
+        const refName = (0, komoji_1.toKebabCase)(singularName);
+        referenceNames.push(refName);
         files.push({
-            fileName: `skills/${(0, utils_1.lcFirst)(singularName)}.md`,
-            content: (0, docs_utils_1.buildSkillFile)({
-                name: `orm-${(0, utils_1.lcFirst)(singularName)}`,
+            fileName: `${skillName}/references/${refName}.md`,
+            content: (0, docs_utils_1.buildSkillReference)({
+                title: singularName,
                 description: table.description || `ORM operations for ${table.name} records`,
                 language: 'typescript',
                 usage: [
-                    `db.${(0, utils_1.lcFirst)(singularName)}.findMany({ select: { id: true } }).execute()`,
-                    `db.${(0, utils_1.lcFirst)(singularName)}.findOne({ ${pk.name}: '<value>', select: { id: true } }).execute()`,
-                    `db.${(0, utils_1.lcFirst)(singularName)}.create({ data: { ${editableFields.map((f) => `${f.name}: '<value>'`).join(', ')} }, select: { id: true } }).execute()`,
-                    `db.${(0, utils_1.lcFirst)(singularName)}.update({ where: { ${pk.name}: '<value>' }, data: { ${editableFields[0]?.name || 'field'}: '<new>' }, select: { id: true } }).execute()`,
-                    `db.${(0, utils_1.lcFirst)(singularName)}.delete({ where: { ${pk.name}: '<value>' } }).execute()`,
+                    `db.${modelName}.findMany({ select: { id: true } }).execute()`,
+                    `db.${modelName}.findOne({ ${pk.name}: '<value>', select: { id: true } }).execute()`,
+                    `db.${modelName}.create({ data: { ${editableFields.map((f) => `${f.name}: '<value>'`).join(', ')} }, select: { id: true } }).execute()`,
+                    `db.${modelName}.update({ where: { ${pk.name}: '<value>' }, data: { ${editableFields[0]?.name || 'field'}: '<new>' }, select: { id: true } }).execute()`,
+                    `db.${modelName}.delete({ where: { ${pk.name}: '<value>' } }).execute()`,
                 ],
                 examples: [
                     {
                         description: `List all ${singularName} records`,
                         code: [
-                            `const items = await db.${(0, utils_1.lcFirst)(singularName)}.findMany({`,
+                            `const items = await db.${modelName}.findMany({`,
                             `  select: { ${pk.name}: true, ${editableFields[0]?.name || 'name'}: true }`,
                             '}).execute();',
                         ],
@@ -377,7 +384,7 @@ function generateOrmSkills(tables, customOperations) {
                     {
                         description: `Create a ${singularName}`,
                         code: [
-                            `const item = await db.${(0, utils_1.lcFirst)(singularName)}.create({`,
+                            `const item = await db.${modelName}.create({`,
                             `  data: { ${editableFields.map((f) => `${f.name}: 'value'`).join(', ')} },`,
                             `  select: { ${pk.name}: true }`,
                             '}).execute();',
@@ -387,30 +394,60 @@ function generateOrmSkills(tables, customOperations) {
             }),
         });
     }
+    // Generate reference files for custom operations
     for (const op of customOperations) {
         const accessor = op.kind === 'query' ? 'query' : 'mutation';
         const callArgs = op.args.length > 0
             ? `{ ${op.args.map((a) => `${a.name}: '<value>'`).join(', ')} }`
             : '';
+        const refName = (0, komoji_1.toKebabCase)(op.name);
+        referenceNames.push(refName);
         files.push({
-            fileName: `skills/${op.name}.md`,
-            content: (0, docs_utils_1.buildSkillFile)({
-                name: `orm-${op.name}`,
+            fileName: `${skillName}/references/${refName}.md`,
+            content: (0, docs_utils_1.buildSkillReference)({
+                title: op.name,
                 description: op.description || `Execute the ${op.name} ${op.kind}`,
                 language: 'typescript',
-                usage: [
-                    `db.${accessor}.${op.name}(${callArgs}).execute()`,
-                ],
+                usage: [`db.${accessor}.${op.name}(${callArgs}).execute()`],
                 examples: [
                     {
                         description: `Run ${op.name}`,
-                        code: [
-                            `const result = await db.${accessor}.${op.name}(${callArgs}).execute();`,
-                        ],
+                        code: [`const result = await db.${accessor}.${op.name}(${callArgs}).execute();`],
                     },
                 ],
             }),
         });
     }
+    // Generate the overview SKILL.md
+    const tableNames = tables.map((t) => (0, utils_1.lcFirst)((0, utils_1.getTableNames)(t).singularName));
+    files.push({
+        fileName: `${skillName}/SKILL.md`,
+        content: (0, docs_utils_1.buildSkillFile)({
+            name: skillName,
+            description: `ORM client for the ${targetName} API — provides typed CRUD operations for ${tables.length} tables and ${customOperations.length} custom operations`,
+            language: 'typescript',
+            usage: [
+                `// Import the ORM client`,
+                `import { db } from './orm';`,
+                '',
+                `// Available models: ${tableNames.slice(0, 8).join(', ')}${tableNames.length > 8 ? ', ...' : ''}`,
+                `db.<model>.findMany({ select: { id: true } }).execute()`,
+                `db.<model>.findOne({ id: '<value>', select: { id: true } }).execute()`,
+                `db.<model>.create({ data: { ... }, select: { id: true } }).execute()`,
+                `db.<model>.update({ where: { id: '<value>' }, data: { ... }, select: { id: true } }).execute()`,
+                `db.<model>.delete({ where: { id: '<value>' } }).execute()`,
+            ],
+            examples: [
+                {
+                    description: 'Query records',
+                    code: [
+                        `const items = await db.${tableNames[0] || 'model'}.findMany({`,
+                        '  select: { id: true }',
+                        '}).execute();',
+                    ],
+                },
+            ],
+        }, referenceNames),
+    });
     return files;
 }

package/core/generate.d.ts

@@ -33,6 +33,11 @@ export interface GenerateResult {
  */
 export interface GenerateInternalOptions {
     skipCli?: boolean;
+    /**
+     * Internal-only name for the target when generating skills.
+     * Used by generateMulti() so skill names are stable and composable.
+     */
+    targetName?: string;
 }
 export declare function generate(options?: GenerateOptions, internalOptions?: GenerateInternalOptions): Promise<GenerateResult>;
 export declare function expandApiNamesToMultiTarget(config: GraphQLSDKConfigTarget): Record<string, GraphQLSDKConfigTarget> | null;