thomas-agentkit 0.8.0 → 0.9.0-alpha.0

package/README.md

@@ -6,14 +6,81 @@ It installs reusable agent instructions, workflow guides, quality checklists, de
 
 AgentKit is not an AI agent. It is a small scaffolding tool for making repositories easier and safer to work on with AI-assisted development.
 
+## Bootstrap paths
+
+AgentKit supports two first-time setup paths. Pick one — they are not interchangeable.
+
+| | Template path | Skill path |
+| --- | --- | --- |
+| **CLI command** | `agentkit init` | `agentkit skill install` |
+| **When to use** | Immediate offline setup; you want files now | Agent-guided setup; guidance created from your repo in a later session |
+| **What you get** | Bundled `.md` templates copied into the project | Bundled `agentkit` Agent Skill installed; no guidance `.md` files yet |
+| **Ongoing maintenance** | CLI `agentkit update` (managed-block merge) | Skill routes in your agent: `/agentkit update`, `/agentkit doctor`, `/agentkit repair`, `/agentkit learn` |
+| **Config** | `installMode: template` | `installMode: skill` |
+
+```text
+FIRST-TIME SETUP (terminal)
+├── agentkit init              → copies templates, installMode: template
+└── agentkit skill install     → copies skill to .agents/skills/agentkit/, installMode: skill
+
+ONGOING WORK (agent + skill path only)
+├── /agentkit init   → agent creates AGENTS.md and companion files from repo context
+├── /agentkit update → agent syncs guidance after code changes
+├── /agentkit doctor → agent audits guidance quality
+├── /agentkit repair → agent repairs guidance structure when explicitly requested
+└── /agentkit learn  → agent teaches what changed after implementation
+```
+
+Interactive `agentkit init` asks whether to copy templates or install the AgentKit skill, then runs the chosen path in the same session.
+
 ## Usage
 
+### Template path
+
 Install templates into the current directory:
 
 ```bash
 npx thomas-agentkit init
 ```
 
+### Skill path
+
+Install the bundled AgentKit skill (v0.9.x+). This does **not** create `AGENTS.md` or other guidance files — run `/agentkit init` in your agent afterward:
+
+```bash
+npx thomas-agentkit skill install
+```
+
+Preview skill install without writing files:
+
+```bash
+npx thomas-agentkit skill install --dry-run
+```
+
+Overwrite an existing skill install:
+
+```bash
+npx thomas-agentkit skill install --force
+```
+
+After install, the CLI prints:
+
+```text
+Installed AgentKit skill in .agents/skills/agentkit/
+Wrote agentkit.config.json (installMode: skill)
+
+Next step: In your agent, run agentkit init.
+The skill will create AGENTS.md and companion files from your repository.
+```
+
+After skill install, use the project-local skill from your agent:
+
+- `/agentkit init` creates missing guidance files from repository context.
+- `/agentkit update` syncs managed guidance with current repository context.
+- `/agentkit doctor` audits guidance quality without editing by default.
+- `/agentkit repair` repairs guidance structure, such as malformed managed blocks or thick AI adapters, after an explicit request.
+- `/agentkit learn` teaches recent codebase changes, design decisions, edge cases, validation, and impact without writing files by default.
+
 If the package is installed in a project, use the local `agentkit` binary:
 
 ```bash
@@ -77,6 +144,8 @@ Standardize install defaults with `agentkit.config.json`:
 
 ```json
 {
+  "installMode": "template",
+  "agentkitVersion": "0.9.0",
   "preset": "next",
   "templateSet": "standard",
   "designSystem": "linear",
@@ -105,7 +174,9 @@ npx thomas-agentkit init --write-config
 
 `--write-config` writes `agentkit.config.json` in the target directory. Existing config files are skipped by default; use `--force` to overwrite one intentionally.
 
-Config values are validated when loaded. Unknown config keys, invalid preset/template/design-system names, invalid AI tool names, and non-string personalization values exit with an error.
+`installMode` is `"template"` or `"skill"` and records how the project was bootstrapped. `agentkitVersion` records the package version at install time. Configs without `installMode` are treated as template-path installs.
+
+Config values are validated when loaded. Unknown config keys, invalid preset/template/design-system names, invalid AI tool names, invalid `installMode` values, and non-string personalization values exit with an error.
 
 List bundled templates:
 
@@ -188,10 +259,30 @@ Presets add stack-specific guidance without scaffolding framework app files.
 - `convex`
 - `fullstack` (`Next.js` + `Convex`)
 
+## CLI vs agent commands
+
+The same names mean different things in the terminal vs in an agent session:
+
+| Name | Where | What |
+| --- | --- | --- |
+| `agentkit init` | Terminal | Install **templates** |
+| `agentkit skill install` | Terminal | Install **bundled skill** + config |
+| `agentkit init` | Agent | Create **guidance files** (skill path) |
+| `agentkit update` | Terminal | Template-path managed-block merge only |
+| `agentkit update` | Agent | Sync guidance to repo changes |
+| `agentkit doctor` | Agent | Audit guidance quality |
+| `agentkit repair` | Agent | Repair guidance structure after explicit request |
+| `agentkit learn` | Agent | Teach recent codebase changes and check understanding |
+
+Never use CLI `agentkit init` for skill installation.
+
+On skill-path repos (`installMode: skill`), CLI `agentkit update` prints an informational message and does not modify guidance files. Use `/agentkit update` in your agent for skill-path guidance sync.
+
 ## CLI Reference
 
 ```text
 agentkit init [target] [--force] [--dry-run] [--interactive] [--yes] [--write-config] [--preset <name>] [--design-system <name>]
+agentkit skill install [target] [--force] [--dry-run] [--yes] [--preset <name>] [--design-system <name>]
 agentkit update [target] [--dry-run] [--preset <name>] [--design-system <name>]
 agentkit --list
 agentkit --list-presets
@@ -206,7 +297,7 @@ Options:
 - `--dry-run`: print planned changes without writing files
 - `-i, --interactive`: explicitly prompt for install options
 - `-y, --yes`: accept defaults without prompts
-- `--write-config`: write resolved install defaults to `agentkit.config.json`
+- `--write-config`: write resolved template install defaults to `agentkit.config.json`
 - `--preset <name>`: install stack-specific guidance (`next`, `sveltekit`, `express`, `convex`, `fullstack`)
 - `--design-system <name>`: design system variant for `DESIGN-SYSTEM.md` (`linear`, `apple`)
 - `--list`: list bundled template files

package/dist/cli.js

@@ -5,6 +5,7 @@ import { constants as fsConstants, realpathSync } from "node:fs";
 import { access, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { getSkillDestinationPaths, getSkillSourceDir, installSkill, listSkillFiles, printSkillInstallResult, } from "./skill-install.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const packageRoot = path.resolve(__dirname, "..");
@@ -20,7 +21,16 @@ const designSystemLabels = {
     apple: "Apple-inspired",
 };
 const configFileName = "agentkit.config.json";
-const configKeys = ["preset", "templateSet", "aiTools", "designSystem", "personalization"];
+const configKeys = [
+    "installMode",
+    "agentkitVersion",
+    "preset",
+    "templateSet",
+    "aiTools",
+    "designSystem",
+    "personalization",
+];
+const validInstallModes = ["template", "skill"];
 const personalizationKeys = [
     "projectName",
     "projectDescription",
@@ -128,7 +138,7 @@ async function collectInstallableTemplatePaths(dir, base) {
     for (const entry of entries) {
         const absolutePath = path.join(dir, entry.name);
         if (entry.isDirectory()) {
-            if (dir === templatesDir && entry.name === "design-systems") {
+            if (dir === templatesDir && (entry.name === "design-systems" || entry.name === "skills")) {
                 continue;
             }
             discovered.push(...(await collectInstallableTemplatePaths(absolutePath, base)));
@@ -257,13 +267,31 @@ function readConfigPersonalization(value) {
     }
     return personalization;
 }
+function resolveInstallMode(installMode) {
+    const normalizedInstallMode = installMode.toLowerCase();
+    if (!validInstallModes.includes(normalizedInstallMode)) {
+        throw new Error(`Unknown install mode "${installMode}". Valid install modes: ${validInstallModes.join(", ")}.`);
+    }
+    return normalizedInstallMode;
+}
+export function getInstallMode(config) {
+    return config?.installMode ?? "template";
+}
 function parseConfig(rawConfig, configPath) {
     assertPlainObject(rawConfig, configFileName);
     assertKnownKeys(rawConfig, configKeys, configFileName);
     const preset = optionalConfigString(rawConfig, "preset");
     const templateSet = optionalConfigString(rawConfig, "templateSet");
     const designSystem = optionalConfigString(rawConfig, "designSystem");
+    const installMode = optionalConfigString(rawConfig, "installMode");
+    const agentkitVersion = optionalConfigString(rawConfig, "agentkitVersion");
     const config = {};
+    if (installMode !== undefined) {
+        config.installMode = resolveInstallMode(installMode);
+    }
+    if (agentkitVersion !== undefined) {
+        config.agentkitVersion = agentkitVersion;
+    }
     if (preset !== undefined) {
         config.preset = resolvePreset(preset);
     }
@@ -394,8 +422,10 @@ function cleanPersonalizationValue(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed : undefined;
 }
-function getResolvedConfig(options) {
+function getResolvedConfig(options, installMode, agentkitVersion) {
     const config = {
+        installMode,
+        agentkitVersion,
         templateSet: options.templateSet ?? "standard",
         aiTools: options.aiTools ?? [],
         designSystem: effectiveDesignSystem(options.designSystem),
@@ -573,7 +603,7 @@ async function resolveInitTemplateFiles(options) {
     }
     return getSelectedTemplateFiles(options.templateSet ?? "standard", options.aiTools ?? [], allTemplateFiles);
 }
-async function installTemplates(targetArg, options) {
+async function installTemplates(targetArg, options, agentkitVersion) {
     const targetDir = path.resolve(process.cwd(), targetArg || ".");
     const files = await resolveInitTemplateFiles(options);
     const preset = resolvePreset(options.preset);
@@ -583,7 +613,7 @@ async function installTemplates(targetArg, options) {
         await mkdir(targetDir, { recursive: true });
     }
     if (options.writeConfig) {
-        await installFileIfAllowed(targetDir, configFileName, options, result, () => serializeConfig(getResolvedConfig(options)));
+        await installFileIfAllowed(targetDir, configFileName, options, result, () => serializeConfig(getResolvedConfig(options, "template", agentkitVersion)));
     }
     for (const file of files) {
         await installFileIfAllowed(targetDir, file, options, result, async () => {
@@ -790,7 +820,23 @@ async function promptForConflictStrategy(existingFiles) {
         ],
     }));
 }
-async function applyInteractiveSelections(resolvedTarget, providedPreset, options) {
+async function promptForBootstrapPath() {
+    return resolvePrompt(await select({
+        message: "How do you want to set up AgentKit?",
+        initialValue: "template",
+        options: [
+            {
+                label: "Copy templates now (install AGENTS.md and companion files)",
+                value: "template",
+            },
+            {
+                label: "Install AgentKit skill (create guidance files later in your agent)",
+                value: "skill",
+            },
+        ],
+    }));
+}
+async function collectInstallOptions(resolvedTarget, providedPreset, options) {
     if (!providedPreset) {
         options.preset = await promptForProjectPreset();
     }
@@ -803,25 +849,50 @@ async function applyInteractiveSelections(resolvedTarget, providedPreset, option
     if (templateSet === "standard" || templateSet === "full") {
         options.designSystem = await promptForDesignSystem(options.designSystem);
     }
-    if (!options.force) {
+}
+async function resolveConflictForInstall(resolvedTarget, options, bootstrapPath) {
+    if (options.force) {
+        return;
+    }
+    let installFiles;
+    if (bootstrapPath === "skill") {
+        const skillFiles = await listSkillFiles(getSkillSourceDir(packageRoot));
+        installFiles = [...getSkillDestinationPaths(skillFiles), configFileName];
+    }
+    else {
         const preset = resolvePreset(options.preset);
-        const installFiles = preset ? [...options.files, "STACK.md"] : options.files;
-        const existingFiles = await findExistingInstallFiles(resolvedTarget, installFiles);
-        if (existingFiles.length > 0) {
-            options.force = (await promptForConflictStrategy(existingFiles)) === "overwrite";
-        }
+        installFiles = preset ? [...(options.files ?? []), "STACK.md"] : (options.files ?? []);
+    }
+    const existingFiles = await findExistingInstallFiles(resolvedTarget, installFiles);
+    if (existingFiles.length > 0) {
+        options.force = (await promptForConflictStrategy(existingFiles)) === "overwrite";
     }
 }
-async function resolveInteractiveTarget(target, options) {
+async function runInteractiveInstall(target, options, agentkitVersion) {
+    intro("Welcome to AgentKit");
+    const bootstrapPath = await promptForBootstrapPath();
     const providedPreset = resolvePreset(options.preset);
-    if (!shouldPromptForInit(options, process)) {
-        return target;
+    const resolvedTarget = await promptForTarget(target);
+    await collectInstallOptions(resolvedTarget, providedPreset, options);
+    options.personalization = await promptForPersonalization(options.personalization);
+    await resolveConflictForInstall(resolvedTarget, options, bootstrapPath);
+    if (bootstrapPath === "skill") {
+        const result = await installSkill(resolvedTarget, options, packageRoot, agentkitVersion);
+        printSkillInstallResult(result, Boolean(options.dryRun));
+        return;
     }
+    const result = await installTemplates(resolvedTarget, options, agentkitVersion);
+    printInstallResult(result, Boolean(options.dryRun));
+}
+async function runSkillInstallInteractive(target, options, agentkitVersion) {
     intro("Welcome to AgentKit");
+    const providedPreset = resolvePreset(options.preset);
     const resolvedTarget = await promptForTarget(target);
-    await applyInteractiveSelections(resolvedTarget, providedPreset, options);
+    await collectInstallOptions(resolvedTarget, providedPreset, options);
     options.personalization = await promptForPersonalization(options.personalization);
-    return resolvedTarget;
+    await resolveConflictForInstall(resolvedTarget, options, "skill");
+    const result = await installSkill(resolvedTarget, options, packageRoot, agentkitVersion);
+    printSkillInstallResult(result, Boolean(options.dryRun));
 }
 async function main() {
     if (process.argv.slice(2).includes("--list")) {
@@ -855,6 +926,7 @@ async function main() {
 
 Examples:
   agentkit init
+  agentkit skill install
   agentkit update
   agentkit init --preset next
   agentkit init ./my-project --yes --dry-run
@@ -874,10 +946,35 @@ Examples:
         .option("--design-system <name>", `design system guidance for DESIGN-SYSTEM.md (${formatDesignSystemList()})`)
         .action(async (target, options) => {
         await applyInitConfig(options, await loadConfigForTarget(target));
-        const resolvedTarget = await resolveInteractiveTarget(target, options);
-        const result = await installTemplates(resolvedTarget, options);
+        const agentkitVersion = await readPackageVersion();
+        if (shouldPromptForInit(options, process)) {
+            await runInteractiveInstall(target, options, agentkitVersion);
+            return;
+        }
+        const result = await installTemplates(target, options, agentkitVersion);
         printInstallResult(result, Boolean(options.dryRun));
     });
+    const skill = program.command("skill").description("install the bundled AgentKit Agent Skill");
+    skill
+        .command("install")
+        .description("install the bundled agentkit skill and write agentkit.config.json")
+        .argument("[target]", "target project directory", ".")
+        .option("--force", "overwrite existing skill files and config")
+        .option("--dry-run", "print planned changes without writing files")
+        .option("-i, --interactive", "prompt for install options")
+        .option("-y, --yes", "accept defaults for non-interactive runs")
+        .option("--preset <name>", `store stack preset in config (${formatPresetList()})`)
+        .option("--design-system <name>", `store design system choice in config (${formatDesignSystemList()})`)
+        .action(async (target, options) => {
+        await applyInitConfig(options, await loadConfigForTarget(target));
+        const agentkitVersion = await readPackageVersion();
+        if (shouldPromptForInit(options, process)) {
+            await runSkillInstallInteractive(target, options, agentkitVersion);
+            return;
+        }
+        const result = await installSkill(target, options, packageRoot, agentkitVersion);
+        printSkillInstallResult(result, Boolean(options.dryRun));
+    });
     program
         .command("update")
         .description("update AgentKit managed template blocks in a project")
@@ -886,7 +983,14 @@ Examples:
         .option("--preset <name>", `update stack-specific guidance (${formatPresetList()})`)
         .option("--design-system <name>", `design system guidance for DESIGN-SYSTEM.md (${formatDesignSystemList()})`)
         .action(async (target, options) => {
-        applyUpdateConfig(options, await loadConfigForTarget(target));
+        const config = await loadConfigForTarget(target);
+        if (getInstallMode(config) === "skill") {
+            console.log("This project uses installMode: skill.");
+            console.log("Run agentkit update in your agent to sync guidance files.");
+            console.log("(CLI agentkit update applies to template-path installs.)");
+            return;
+        }
+        applyUpdateConfig(options, config);
         const result = await updateTemplates(target, options);
         printUpdateResult(result, Boolean(options.dryRun));
     });

package/dist/skill-install.js

@@ -0,0 +1,125 @@
+import { constants as fsConstants } from "node:fs";
+import { access, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+export const SKILL_DEST_DIR = ".agents/skills/agentkit";
+export const CONFIG_FILE_NAME = "agentkit.config.json";
+export function getSkillSourceDir(packageRoot) {
+    return path.join(packageRoot, "templates", "skills", "agentkit");
+}
+export async function listSkillFiles(sourceDir) {
+    const files = [];
+    async function walk(dir, prefix) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath, relative);
+            }
+            else if (entry.isFile()) {
+                files.push(relative);
+            }
+        }
+    }
+    await walk(sourceDir, "");
+    return files.sort();
+}
+export function buildSkillConfig(options, agentkitVersion) {
+    const config = {
+        installMode: "skill",
+        agentkitVersion,
+        templateSet: options.templateSet ?? "standard",
+        aiTools: options.aiTools ?? [],
+        designSystem: options.designSystem ?? "linear",
+    };
+    if (options.preset) {
+        config.preset = options.preset;
+    }
+    if (options.personalization) {
+        const personalization = {};
+        for (const [key, value] of Object.entries(options.personalization)) {
+            const trimmed = value?.trim();
+            if (trimmed) {
+                personalization[key] = trimmed;
+            }
+        }
+        if (Object.keys(personalization).length > 0) {
+            config.personalization = personalization;
+        }
+    }
+    return config;
+}
+export function getSkillDestinationPaths(skillFiles) {
+    return skillFiles.map((file) => path.posix.join(SKILL_DEST_DIR, file.replace(/\\/g, "/")));
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function installSkill(targetArg, options, packageRoot, agentkitVersion) {
+    const targetDir = path.resolve(process.cwd(), targetArg || ".");
+    const sourceDir = getSkillSourceDir(packageRoot);
+    const skillFiles = await listSkillFiles(sourceDir);
+    const result = { targetDir, created: [], skipped: [] };
+    if (!options.dryRun) {
+        await mkdir(targetDir, { recursive: true });
+    }
+    for (const file of skillFiles) {
+        const destination = path.join(targetDir, SKILL_DEST_DIR, file);
+        const destinationRelative = path.posix.join(SKILL_DEST_DIR, file.replace(/\\/g, "/"));
+        if ((await pathExists(destination)) && !options.force) {
+            result.skipped.push(destinationRelative);
+            continue;
+        }
+        result.created.push(destinationRelative);
+        if (!options.dryRun) {
+            await mkdir(path.dirname(destination), { recursive: true });
+            const content = await readFile(path.join(sourceDir, file), "utf8");
+            await writeFile(destination, content);
+        }
+    }
+    const configPath = path.join(targetDir, CONFIG_FILE_NAME);
+    const configRelative = CONFIG_FILE_NAME;
+    if ((await pathExists(configPath)) && !options.force) {
+        if (!result.skipped.includes(configRelative)) {
+            result.skipped.push(configRelative);
+        }
+    }
+    else {
+        if (!result.created.includes(configRelative)) {
+            result.created.push(configRelative);
+        }
+        if (!options.dryRun) {
+            const configContent = `${JSON.stringify(buildSkillConfig(options, agentkitVersion), null, 2)}\n`;
+            await writeFile(configPath, configContent);
+        }
+    }
+    return result;
+}
+export function printSkillInstallResult(result, dryRun = false) {
+    if (dryRun) {
+        console.log(`Would install AgentKit skill in ${SKILL_DEST_DIR}/`);
+        if (result.created.length > 0) {
+            console.log(`Would create: ${result.created.join(", ")}`);
+        }
+        if (result.skipped.length > 0) {
+            console.log(`Would skip existing: ${result.skipped.join(", ")}`);
+            console.log("Use --force to overwrite existing files.");
+        }
+        return;
+    }
+    console.log(`Installed AgentKit skill in ${SKILL_DEST_DIR}/`);
+    console.log(`Wrote ${CONFIG_FILE_NAME} (installMode: skill)`);
+    console.log("");
+    console.log("Next step: In your agent, run agentkit init.");
+    console.log("The skill will create AGENTS.md and companion files from your repository.");
+    if (result.skipped.length > 0) {
+        console.log(`Skipped existing: ${result.skipped.join(", ")}`);
+        console.log("Use --force to overwrite existing files.");
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thomas-agentkit",
-  "version": "0.8.0",
+  "version": "0.9.0-alpha.0",
   "description": "Install AI-agent-ready development templates into a project.",
   "license": "MIT",
   "repository": {
@@ -33,6 +33,7 @@
     "build": "tsc",
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
+    "validate:skill": "skills-ref validate ./templates/skills/agentkit",
     "prepack": "npm run build"
   },
   "dependencies": {
@@ -40,6 +41,7 @@
     "commander": "^12.1.0"
   },
   "devDependencies": {
+    "skills-ref": "^0.1.5",
     "@types/node": "^22.10.2",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",

package/templates/skills/agentkit/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: agentkit
+description: Use when creating, syncing, auditing, repairing, or learning AgentKit-managed repository guidance and codebase changes in an agent session, especially after `agentkit skill install`, when `/agentkit init`, `/agentkit update`, `/agentkit doctor`, `/agentkit repair`, or `/agentkit learn` is requested, or when AGENTS.md, STACK.md, companion guides, managed blocks, commands, placeholders, AI tool adapters, recent diffs, or completed changes need context-aware maintenance or explanation.
+compatibility: Requires agentkit CLI and agentkit.config.json with installMode skill, or existing AgentKit-managed files with block markers.
+metadata:
+  author: thomas-agentkit
+  version: "1.0"
+---
+
+# AgentKit Skill
+
+Create, sync, audit, repair, and teach AgentKit-managed repository guidance and codebase changes using live repository context.
+
+## When to use
+
+- User ran `agentkit skill install`
+- User asks `/agentkit init`, `/agentkit update`, `/agentkit doctor`, `/agentkit repair`, or `/agentkit learn`
+- `AGENTS.md`, `STACK.md`, companion guides, or AI adapters are missing
+- Guidance has stale commands, stack details, project paths, placeholders, or broken references
+- Managed blocks need context-aware update, audit, or repair
+- User wants to understand recent codebase changes, a completed implementation, a diff, a bug fix, or the session
+
+## When not to use
+
+- User wants terminal template install -> direct them to CLI `agentkit init`
+- User wants terminal template update -> direct them to CLI `agentkit update` unless config says `installMode: skill`
+- Generic documentation requests unrelated to AgentKit guidance
+- Code review findings, debugging, or feature implementation requests
+- Short summaries that do not require a guided teaching workflow
+
+## Route
+
+Always read `references/file-contract.md` before editing or auditing AgentKit-managed files. Do not act from `SKILL.md` alone.
+
+1. User asks to **initialize** missing guidance files from repo context
+   → `references/init.md`
+
+2. User asks to **update** or **sync** existing guidance with current repo context
+   → `references/update.md`
+
+3. User asks to **doctor**, **audit**, **review**, **diagnose**, or **health check** guidance quality
+   → `references/doctor.md`
+
+4. User asks to **repair**, **fix malformed blocks**, **convert unmanaged guidance**, or **fix adapters**
+   → `references/repair.md`
+
+5. User asks to **learn**, **understand recent changes**, **explain the session**, **teach me what changed**, **ELI5**, **ELI14**, **explain like an intern**, or **check my understanding**
+   → `references/learn.md`
+
+6. Unsure which workflow applies
+   → If no guidance files exist: `references/init.md`
+   → If guidance exists but commands, stack, files, placeholders, adapters, or references are stale: `references/update.md`
+   → If user wants audit, doctor, health check, diagnosis, or review: `references/doctor.md`
+   → If managed blocks are malformed or unmanaged files need conversion: `references/repair.md`
+   → If user wants to understand completed changes or a session: `references/learn.md`
+
+## Non-negotiables
+
+- `AGENTS.md` is the source of truth; AI tool adapters stay thin pointers
+- Read the route reference and `references/file-contract.md` before file edits
+- Preserve user content **outside** AgentKit managed blocks
+- Skip unmanaged existing files unless conversion is explicitly requested
+- Defer malformed managed blocks to `references/repair.md`
+- Commands in guidance must come from `package.json` scripts or `agentkit.config.json` personalization — never invent scripts
+- Prefer repo facts over config personalization
+- Do not modify app source, lockfiles, package manifests, or CI config during AgentKit workflows
+- `/agentkit learn` is read-only by default and keeps learning checklists in the conversation unless the user explicitly asks for notes
+- CLI `agentkit init` installs **templates**; this skill's `agentkit init` **creates guidance files** — never confuse them
+
+## Gotchas
+
+| Gotcha | Reality |
+| --- | --- |
+| `installMode: skill` but no `.md` files yet | Expected after `agentkit skill install`; run `/agentkit init` |
+| `templateSet: minimal` | `AGENTS.md` only, plus selected adapters if explicitly configured |
+| `templateSet: standard` | Core companions only; not testing/security/workflow docs |
+| `templateSet: full` | Full guidance docs; adapters still follow `aiTools` |
+| AI tool adapters | Thin pointers to `AGENTS.md`; never duplicate full guidance |
+| `STACK.md` | Create/update when preset is configured, user asks, or stack is confidently inferred |
+| Existing unmanaged files | Skip unless user asks to convert |
+| Malformed managed blocks | Use `/agentkit repair` before update/refresh |
+| Learning workflow | `/agentkit learn` teaches from diffs and code; it does not create notes or files by default |
+| Docs-only guidance workflow | Does not require running project tests/builds |
+
+## Quick reference
+
+| User says | Load |
+| --- | --- |
+| "/agentkit init" / "set up AGENTS.md" | `references/init.md` |
+| "/agentkit update" / "sync guidance" | `references/update.md` |
+| "/agentkit doctor" / "audit AgentKit guidance" | `references/doctor.md` |
+| "/agentkit repair" / "fix managed blocks" | `references/repair.md` |
+| "/agentkit learn" / "teach me what changed" | `references/learn.md` |
+| Before any file edit | `references/file-contract.md` |

package/templates/skills/agentkit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AgentKit"
+  short_description: "Create, maintain, and learn repo guidance"
+  default_prompt: "Use $agentkit to initialize, sync, audit, repair, or learn repository guidance and changes."