thomas-agentkit 0.8.0 → 0.9.0-alpha.1

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:
 
@@ -119,7 +190,7 @@ List available presets:
 npx thomas-agentkit --list-presets
 ```
 
-List bundled design systems (source variants for `DESIGN-SYSTEM.md`):
+List bundled design baselines (source variants for `DESIGN.md`):
 
 ```bash
 npx thomas-agentkit --list-design-systems
@@ -133,7 +204,7 @@ AgentKit can copy these bundled files into the target project:
 - `CHANGE-EXPLANATION.md`
 - `CLAUDE.md`
 - `CODE-QUALITY.md`
-- `DESIGN-SYSTEM.md`
+- `DESIGN.md`
 - `IMPLEMENTATION-BRIEF-TEMPLATE.md`
 - `PRD-TEMPLATE.md`
 - `SECURITY-CHECKLIST.md`
@@ -145,7 +216,7 @@ AgentKit can copy these bundled files into the target project:
 
 When a preset is selected, AgentKit also installs `STACK.md` and adds a note in `AGENTS.md` telling agents to read it before changing stack-specific code.
 
-Bundled design system guidance is stored under `templates/design-systems/` in this repository (for example `linear.md`, `apple.md`). The CLI installs the chosen variant into `DESIGN-SYSTEM.md` in the target project; variant paths are not separate install targets.
+Bundled design baselines are stored under `templates/design-systems/` in this repository (`linear`, `apple`, `cursor`, `framer`, `notion`, `warp`). The CLI installs the chosen variant into `DESIGN.md` in the target project; variant paths are not separate install targets. The bundled AgentKit skill also ships copies under `references/design-baselines/` for `/agentkit design`.
 
 Existing files are skipped by default so local edits are preserved. Use `--force` when you intentionally want to refresh files from the bundled package version.
 
@@ -161,12 +232,12 @@ Generated content
 
 Interactive personalization only applies during `agentkit init` when files are created or overwritten. It does not write a config file unless `--write-config` is passed, and `agentkit update` does not reapply personalized values.
 
-`agentkit.config.json` can set `preset`, `templateSet`, `designSystem`, `aiTools`, and `personalization` defaults. `templateSet` may be `minimal`, `standard`, or `full`; `designSystem` selects which bundled design-system variant fills `DESIGN-SYSTEM.md` (`linear` or `apple`); `aiTools` may include `codex`, `cursor`, `claude`, and `copilot`. `agentkit update` uses config `preset` and `designSystem` and continues to update all managed bundled templates.
+`agentkit.config.json` can set `preset`, `templateSet`, `designSystem`, `aiTools`, and `personalization` defaults. `templateSet` may be `minimal`, `standard`, or `full`; `designSystem` selects which bundled baseline fills `DESIGN.md` (`linear`, `apple`, `cursor`, `framer`, `notion`, or `warp`); `aiTools` may include `codex`, `cursor`, `claude`, and `copilot`. `agentkit update` uses config `preset` and `designSystem` and continues to update all managed bundled templates.
 
 Template set mappings:
 
 - `minimal`: `AGENTS.md`
-- `standard`: `AGENTS.md`, `CHANGE-EXPLANATION.md`, `CODE-QUALITY.md`, `DESIGN-SYSTEM.md`, `.github/pull_request_template.md`
+- `standard`: `AGENTS.md`, `CHANGE-EXPLANATION.md`, `CODE-QUALITY.md`, `DESIGN.md`, `.github/pull_request_template.md`
 - `full`: all bundled templates, including AI tool adapters and planning/testing/security guides
 
 AI tool mappings:
@@ -188,10 +259,31 @@ 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 |
+| `agentkit design` | Agent | Create or refresh `DESIGN.md` from a bundled baseline |
+
+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,16 +298,16 @@ 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`)
+- `--design-system <name>`: design baseline for `DESIGN.md` (`linear`, `apple`, `cursor`, `framer`, `notion`, `warp`)
 - `--list`: list bundled template files
 - `--list-presets`: list available presets
 - `--list-design-systems`: list available design systems
 - `-h, --help`: show help
 - `-v, --version`: show package version
 
-For `agentkit update`, `--preset <name>` refreshes preset-specific managed content, including `STACK.md`. `--design-system <name>` refreshes the managed `DESIGN-SYSTEM.md` body from the matching bundled variant.
+For `agentkit update`, `--preset <name>` refreshes preset-specific managed content, including `STACK.md`. `--design-system <name>` refreshes the managed `DESIGN.md` body from the matching bundled baseline.
 
 ## Local Development
 

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, "..");
@@ -14,13 +15,33 @@ const validPresets = ["next", "sveltekit", "express", "convex", "fullstack"];
 const validProjectTypes = ["generic", ...validPresets];
 const validAiTools = ["codex", "cursor", "claude", "copilot"];
 const validTemplateSets = ["minimal", "standard", "full"];
-const validDesignSystems = ["linear", "apple"];
+const validDesignSystems = [
+    "linear",
+    "apple",
+    "cursor",
+    "framer",
+    "notion",
+    "warp",
+];
 const designSystemLabels = {
-    linear: "Linear-inspired",
-    apple: "Apple-inspired",
+    linear: "Linear",
+    apple: "Apple",
+    cursor: "Cursor",
+    framer: "Framer",
+    notion: "Notion",
+    warp: "Warp",
 };
 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",
@@ -51,7 +72,7 @@ const templateSetFiles = {
         "AGENTS.md",
         "CHANGE-EXPLANATION.md",
         "CODE-QUALITY.md",
-        "DESIGN-SYSTEM.md",
+        "DESIGN.md",
         ".github/pull_request_template.md",
     ],
     full: [],
@@ -128,7 +149,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)));
@@ -143,10 +164,8 @@ async function collectInstallableTemplatePaths(dir, base) {
 }
 async function getTemplateFiles() {
     const discovered = await collectInstallableTemplatePaths(templatesDir, templatesDir);
-    const withDesignSystem = discovered.includes("DESIGN-SYSTEM.md")
-        ? discovered
-        : [...discovered, "DESIGN-SYSTEM.md"];
-    return withDesignSystem.sort();
+    const withDesign = discovered.includes("DESIGN.md") ? discovered : [...discovered, "DESIGN.md"];
+    return withDesign.sort();
 }
 function isPresetName(value) {
     return validPresets.includes(value);
@@ -257,13 +276,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 +431,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),
@@ -488,7 +527,7 @@ export function personalizeTemplateContent(file, content, values) {
         return content;
     }
     let personalized = content;
-    if (file === "AGENTS.md" || file === "DESIGN-SYSTEM.md") {
+    if (file === "AGENTS.md" || file === "DESIGN.md") {
         personalized = replaceIfProvided(personalized, "[Project Name]", values.projectName);
     }
     if (file === "AGENTS.md") {
@@ -573,7 +612,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 +622,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 () => {
@@ -619,7 +658,7 @@ async function buildTemplateContent(file, preset, designSystem) {
         }
         return getStackGuidance(preset);
     }
-    if (file === "DESIGN-SYSTEM.md") {
+    if (file === "DESIGN.md") {
         const source = path.join(templatesDir, "design-systems", `${designSystem}.md`);
         const content = await readFile(source, "utf8");
         return addStackReference(file, content, preset);
@@ -790,7 +829,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 +858,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 +935,7 @@ async function main() {
 
 Examples:
   agentkit init
+  agentkit skill install
   agentkit update
   agentkit init --preset next
   agentkit init ./my-project --yes --dry-run
@@ -871,22 +952,54 @@ Examples:
         .option("-y, --yes", "accept defaults for non-interactive runs")
         .option("--write-config", "write resolved install defaults to agentkit.config.json")
         .option("--preset <name>", `install stack-specific guidance (${formatPresetList()})`)
-        .option("--design-system <name>", `design system guidance for DESIGN-SYSTEM.md (${formatDesignSystemList()})`)
+        .option("--design-system <name>", `design baseline for DESIGN.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")
         .argument("[target]", "target project directory", ".")
         .option("--dry-run", "print planned changes without writing files")
         .option("--preset <name>", `update stack-specific guidance (${formatPresetList()})`)
-        .option("--design-system <name>", `design system guidance for DESIGN-SYSTEM.md (${formatDesignSystemList()})`)
+        .option("--design-system <name>", `design baseline for DESIGN.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.1",
   "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/.cursor/rules/agentkit.md

@@ -11,7 +11,7 @@ Use this rule as a repository guidance router for Cursor agents and composer wor
 ## When Relevant
 
 - **File edits (final message):** change-explanation format in `AGENTS.md` and `CHANGE-EXPLANATION.md`.
-- **UI / styling / layout:** `DESIGN-SYSTEM.md` or the project design-system path from `AGENTS.md`.
+- **UI / styling / layout:** `DESIGN.md` or the project design path from `AGENTS.md`.
 - **Review / refactor / dependencies:** `CODE-QUALITY.md`.
 - **Tests / QA strategy:** `TESTING.md` if present.
 - **Auth / secrets / PII:** `SECURITY-CHECKLIST.md` if present.