skills-package-manager 0.4.0 → 0.6.0

package/README.md

@@ -72,6 +72,7 @@ Default `skills.json` written by `spm init --yes`:
 {
   "installDir": ".agents/skills",
   "linkTargets": [],
+  "selfSkill": false,
   "skills": {}
 }
 ```
@@ -85,6 +86,7 @@ spm install
 ```
 
 This resolves each skill from its specifier, materializes it into `installDir` (default `.agents/skills/`), and creates symlinks for each `linkTarget`.
+When `selfSkill` is `true`, `spm install` also installs the bundled `skills-package-manager-cli` skill so users get guidance for `skills.json`, `skills-lock.yaml`, and the `spm` workflow. This helper skill is not written to `skills-lock.yaml`.
 
 ### `spm update`
 
@@ -99,7 +101,7 @@ Behavior:
 
 - Uses `skills.json` as the source of truth
 - Re-resolves git refs and npm package targets
-- Skips `link:` skills
+- Skips `link:` skills, including the bundled self skill
 - Fails immediately for unknown skill names
 - Writes `skills-lock.yaml` only after fetch and link succeed
 

package/dist/index.js

@@ -3,16 +3,18 @@ import picocolors from "picocolors";
 import { access, cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rm, stat as promises_stat, symlink, writeFile } from "node:fs/promises";
 import node_path, { basename, join } from "node:path";
 import yaml from "yaml";
+import { z } from "zod";
 import { execFile } from "node:child_process";
 import { homedir, tmpdir } from "node:os";
 import { promisify } from "node:util";
 import { createHash } from "node:crypto";
 import semver from "semver";
-import { createReadStream } from "node:fs";
+import { accessSync, createReadStream } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { x } from "tar";
 import * as __rspack_external__clack_prompts_3cae1695 from "@clack/prompts";
 var package_namespaceObject = {
-    rE: "0.4.0"
+    rE: "0.6.0"
 };
 const UNIVERSAL_AGENT_NAMES = [
     'Amp',
@@ -133,6 +135,7 @@ var codes_ErrorCode = /*#__PURE__*/ function(ErrorCode) {
     ErrorCode["LOCKFILE_NOT_FOUND"] = "ELOCKFILE";
     ErrorCode["LOCKFILE_OUTDATED"] = "ELOCKOUTDATED";
     ErrorCode["MANIFEST_EXISTS"] = "EMANIFESTEXISTS";
+    ErrorCode["MANIFEST_VALIDATION_ERROR"] = "EMANIFESTVAL";
     ErrorCode["NETWORK_ERROR"] = "ENETWORK";
     ErrorCode["REPO_NOT_FOUND"] = "EREPONOTFOUND";
     ErrorCode["UNKNOWN_ERROR"] = "EUNKNOWN";
@@ -239,7 +242,8 @@ class ManifestError extends SpmError {
             [codes_ErrorCode.MANIFEST_NOT_FOUND]: `Manifest not found: ${options.filePath}`,
             [codes_ErrorCode.LOCKFILE_NOT_FOUND]: `Lockfile not found: ${options.filePath}`,
             [codes_ErrorCode.LOCKFILE_OUTDATED]: `Lockfile is out of date: ${options.filePath}`,
-            [codes_ErrorCode.MANIFEST_EXISTS]: `Manifest already exists: ${options.filePath}`
+            [codes_ErrorCode.MANIFEST_EXISTS]: `Manifest already exists: ${options.filePath}`,
+            [codes_ErrorCode.MANIFEST_VALIDATION_ERROR]: `Invalid skills.json: ${options.filePath}`
         };
         const message = options.message ?? defaultMessages[options.code] ?? `Manifest error: ${options.filePath}`;
         super({
@@ -379,6 +383,9 @@ function formatErrorForDisplay(error) {
             if (error.code === codes_ErrorCode.LOCKFILE_OUTDATED) {
                 output += `\n\nThe lockfile is out of sync with skills.json.`;
                 output += `\nRun "spm install" to update the lockfile.`;
+            } else if (error.code === codes_ErrorCode.MANIFEST_VALIDATION_ERROR) {
+                output += `\n\nPlease fix the validation errors in "${error.filePath}".`;
+                output += `\nRefer to the JSON Schema at: https://unpkg.com/skills-package-manager@latest/skills.schema.json`;
             }
         }
         if (error.cause && !(error instanceof GitError || error instanceof FileSystemError)) output += `\n\nCaused by: ${error.cause.message}`;
@@ -425,17 +432,23 @@ async function readSkillsLock(rootDir) {
         });
     }
 }
+const skillsManifestSchema = z.object({
+    $schema: z.string().optional().describe('JSON Schema URL for editor autocompletion'),
+    installDir: z.string().default('.agents/skills').describe('Directory where skills will be installed'),
+    linkTargets: z.array(z.string()).default([]).describe('Directories where skill symlinks will be created'),
+    selfSkill: z.boolean().optional().describe('Whether this project is itself a skill'),
+    pnpmPlugin: z.object({
+        removePnpmfileChecksum: z.boolean().optional().describe('Temporarily remove pnpmfileChecksum from pnpm lockfiles in pnpm-plugin-skills afterAllResolved')
+    }).optional().describe('pnpm-plugin-skills specific compatibility settings'),
+    skills: z.record(z.string(), z.string()).default({}).describe('Map of skill names to their specifiers')
+}).strict();
 async function readSkillsManifest(rootDir) {
     const filePath = node_path.join(rootDir, 'skills.json');
     try {
         const raw = await readFile(filePath, 'utf8');
+        let parsedJson;
         try {
-            const json = JSON.parse(raw);
-            return {
-                installDir: json.installDir ?? '.agents/skills',
-                linkTargets: json.linkTargets ?? [],
-                skills: json.skills ?? {}
-            };
+            parsedJson = JSON.parse(raw);
         } catch (parseError) {
             throw new ParseError({
                 code: codes_ErrorCode.JSON_PARSE_ERROR,
@@ -445,9 +458,22 @@ async function readSkillsManifest(rootDir) {
                 cause: parseError
             });
         }
+        const result = skillsManifestSchema.safeParse(parsedJson);
+        if (!result.success) {
+            const issues = result.error.issues.map((issue)=>{
+                const pathStr = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+                return `${pathStr}: ${issue.message}`;
+            }).join('\n  - ');
+            throw new ManifestError({
+                code: codes_ErrorCode.MANIFEST_VALIDATION_ERROR,
+                filePath,
+                message: `Invalid skills.json:\n  - ${issues}`
+            });
+        }
+        return result.data;
     } catch (error) {
         if ('ENOENT' === error.code) return null;
-        if (error instanceof ParseError) throw error;
+        if (error instanceof ParseError || error instanceof ManifestError) throw error;
         throw convertNodeError(error, {
             operation: 'read',
             path: filePath
@@ -969,13 +995,17 @@ async function writeSkillsLock(rootDir, lockfile) {
         });
     }
 }
+const DEFAULT_SCHEMA_URL = `https://unpkg.com/skills-package-manager@${package_namespaceObject.rE}/skills.schema.json`;
 async function writeSkillsManifest(rootDir, manifest) {
     const filePath = node_path.join(rootDir, 'skills.json');
     const nextManifest = {
+        $schema: manifest.$schema ?? DEFAULT_SCHEMA_URL,
         installDir: manifest.installDir ?? '.agents/skills',
         linkTargets: manifest.linkTargets ?? [],
         skills: manifest.skills
     };
+    if (void 0 !== manifest.selfSkill) nextManifest.selfSkill = manifest.selfSkill;
+    if (void 0 !== manifest.pnpmPlugin) nextManifest.pnpmPlugin = manifest.pnpmPlugin;
     try {
         await writeFile(filePath, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
     } catch (error) {
@@ -1050,6 +1080,23 @@ async function scanForSkills(baseDir, subDir) {
     } catch  {}
     return skills;
 }
+async function discoverSkillsInDirs(baseDir, commonDirs, options) {
+    if (options?.includeRoot ?? true) {
+        const rootSkills = await scanForSkills(baseDir, '');
+        if (rootSkills.length > 0) {
+            rootSkills.sort((a, b)=>a.name.localeCompare(b.name));
+            return rootSkills;
+        }
+    }
+    for (const dir of commonDirs){
+        const skills = await scanForSkills(baseDir, dir);
+        if (skills.length > 0) {
+            skills.sort((a, b)=>a.name.localeCompare(b.name));
+            return skills;
+        }
+    }
+    return [];
+}
 async function cloneAndDiscover(gitUrl, ref) {
     const tempDir = await mkdtemp(join(tmpdir(), 'skills-pm-discover-'));
     try {
@@ -1094,25 +1141,12 @@ async function cloneAndDiscover(gitUrl, ref) {
     }
 }
 async function discoverSkillsInDir(baseDir) {
-    const rootSkills = await scanForSkills(baseDir, '');
-    if (rootSkills.length > 0) {
-        rootSkills.sort((a, b)=>a.name.localeCompare(b.name));
-        return rootSkills;
-    }
-    const commonDirs = [
+    return discoverSkillsInDirs(baseDir, [
         'skills',
         '.agents/skills',
         '.claude/skills',
         '.github/skills'
-    ];
-    for (const dir of commonDirs){
-        const skills = await scanForSkills(baseDir, dir);
-        if (skills.length > 0) {
-            skills.sort((a, b)=>a.name.localeCompare(b.name));
-            return skills;
-        }
-    }
-    return [];
+    ]);
 }
 async function listRepoSkills(owner, repo, ref) {
     const gitUrl = `https://github.com/${owner}/${repo}.git`;
@@ -1177,6 +1211,61 @@ function isLockInSync(manifest, lock) {
     }
     return true;
 }
+const SELF_SKILL_NAME = 'skills-package-manager-cli';
+const SELF_SKILL_CANDIDATE_PATHS = [
+    '../skills/skills-package-manager-cli',
+    '../../skills/skills-package-manager-cli'
+];
+const MODULE_DIR = node_path.dirname(fileURLToPath(import.meta.url));
+function resolveBundledSelfSkillDir() {
+    for (const relativePath of SELF_SKILL_CANDIDATE_PATHS){
+        const candidate = node_path.resolve(MODULE_DIR, relativePath);
+        try {
+            accessSync(node_path.join(candidate, 'SKILL.md'));
+            return candidate;
+        } catch  {}
+    }
+    throw new Error('Unable to locate bundled skills-package-manager-cli skill');
+}
+function getBundledSelfSkillSpecifier() {
+    return normalizeLinkSource(`link:${resolveBundledSelfSkillDir()}`);
+}
+function shouldInjectBundledSelfSkill(manifest) {
+    return true === normalizeSkillsManifest(manifest).selfSkill;
+}
+function hasEquivalentSkillSpecifier(manifest, specifier) {
+    const normalizedTarget = normalizeSpecifier(specifier).normalized;
+    return Object.values(manifest.skills).some((existingSpecifier)=>{
+        try {
+            return normalizeSpecifier(existingSpecifier).normalized === normalizedTarget;
+        } catch  {
+            return false;
+        }
+    });
+}
+function normalizeSkillsManifest(manifest) {
+    return {
+        $schema: manifest.$schema,
+        installDir: manifest.installDir ?? '.agents/skills',
+        linkTargets: manifest.linkTargets ?? [],
+        selfSkill: manifest.selfSkill ?? false,
+        pnpmPlugin: manifest.pnpmPlugin,
+        skills: manifest.skills ?? {}
+    };
+}
+async function expandSkillsManifest(_rootDir, manifest) {
+    const normalized = normalizeSkillsManifest(manifest);
+    if (!normalized.selfSkill) return normalized;
+    const selfSpecifier = getBundledSelfSkillSpecifier();
+    if (SELF_SKILL_NAME in normalized.skills || hasEquivalentSkillSpecifier(normalized, selfSpecifier)) return normalized;
+    return {
+        ...normalized,
+        skills: {
+            ...normalized.skills,
+            [SELF_SKILL_NAME]: selfSpecifier
+        }
+    };
+}
 async function ensureDir(dirPath) {
     await mkdir(dirPath, {
         recursive: true
@@ -1411,6 +1500,17 @@ async function areManagedSkillsInstalled(rootDir, installDir, skillNames) {
     }
     return true;
 }
+async function withBundledSelfSkillLock(rootDir, manifest, lockfile) {
+    if (!shouldInjectBundledSelfSkill(manifest) || lockfile.skills[SELF_SKILL_NAME]) return lockfile;
+    const { entry } = await resolveLockEntry(rootDir, getBundledSelfSkillSpecifier(), SELF_SKILL_NAME);
+    return {
+        ...lockfile,
+        skills: {
+            ...lockfile.skills,
+            [SELF_SKILL_NAME]: entry
+        }
+    };
+}
 async function fetchSkillsFromLock(rootDir, manifest, lockfile, options) {
     await installStageHooks.beforeFetch(rootDir, manifest, lockfile);
     const installDir = manifest.installDir ?? '.agents/skills';
@@ -1519,16 +1619,17 @@ async function installSkills(rootDir, options) {
     } else lockfile = await syncSkillsLock(rootDir, manifest, currentLock, {
         onProgress: options?.onProgress
     });
-    await fetchSkillsFromLock(rootDir, manifest, lockfile, {
+    const runtimeLock = await withBundledSelfSkillLock(rootDir, manifest, lockfile);
+    await fetchSkillsFromLock(rootDir, manifest, runtimeLock, {
         onProgress: options?.onProgress
     });
-    await linkSkillsFromLock(rootDir, manifest, lockfile, {
+    await linkSkillsFromLock(rootDir, manifest, runtimeLock, {
         onProgress: options?.onProgress
     });
     if (!options?.frozenLockfile) await writeSkillsLock(rootDir, lockfile);
     return {
         status: 'installed',
-        installed: Object.keys(lockfile.skills)
+        installed: Object.keys(runtimeLock.skills)
     };
 }
 function buildGitHubSpecifier(owner, repo, skillPath) {
@@ -1625,6 +1726,7 @@ async function addCommand(options) {
     spinner.stop('Installed skills');
     return result;
 }
+const init_DEFAULT_SCHEMA_URL = `https://unpkg.com/skills-package-manager@${package_namespaceObject.rE}/skills.schema.json`;
 async function assertManifestMissing(cwd) {
     const filePath = node_path.join(cwd, 'skills.json');
     try {
@@ -1648,19 +1750,23 @@ async function assertManifestMissing(cwd) {
 }
 function createDefaultManifest() {
     return {
+        $schema: init_DEFAULT_SCHEMA_URL,
         installDir: '.agents/skills',
         linkTargets: [],
+        selfSkill: false,
         skills: {}
     };
 }
 async function initCommand(options, promptInit = promptInitManifestOptions) {
     await assertManifestMissing(options.cwd);
-    const manifest = options.yes ? createDefaultManifest() : {
+    const baseManifest = options.yes ? createDefaultManifest() : {
+        $schema: init_DEFAULT_SCHEMA_URL,
         ...await promptInit(),
+        selfSkill: false,
         skills: {}
     };
-    await writeSkillsManifest(options.cwd, manifest);
-    return manifest;
+    await writeSkillsManifest(options.cwd, baseManifest);
+    return baseManifest;
 }
 const phaseLabelMap = {
     resolving: 'Resolving',
@@ -1781,11 +1887,11 @@ async function installCommand(options) {
         message: 'No skills.json found in the current directory. Run "spm init" to create one.'
     });
     const currentLock = await readSkillsLock(options.cwd);
-    const totalSkills = Object.keys(manifest.skills).length;
     const reporter = createInstallProgressReporter();
     const onProgress = (event)=>reporter.onProgress(event);
     let started = false;
     try {
+        let lockfile;
         if (options.frozenLockfile) {
             if (!currentLock) throw new ManifestError({
                 code: codes_ErrorCode.LOCKFILE_NOT_FOUND,
@@ -1797,46 +1903,31 @@ async function installCommand(options) {
                 filePath: `${options.cwd}/skills-lock.yaml`,
                 message: 'Lockfile is out of sync with manifest. Run install without --frozen-lockfile to update.'
             });
-            reporter.start(totalSkills);
-            started = true;
-            for (const skillName of Object.keys(currentLock.skills))onProgress({
-                type: 'resolved',
-                skillName
-            });
-            reporter.setPhase('fetching');
-            await fetchSkillsFromLock(options.cwd, manifest, currentLock, {
-                onProgress
-            });
-            reporter.setPhase('linking');
-            await linkSkillsFromLock(options.cwd, manifest, currentLock, {
-                onProgress
-            });
-            reporter.setPhase('finalizing');
-            reporter.complete();
-            return {
-                status: 'installed',
-                installed: Object.keys(currentLock.skills)
-            };
-        }
-        reporter.start(totalSkills);
-        started = true;
-        const lockfile = await syncSkillsLock(options.cwd, manifest, currentLock, {
+            lockfile = currentLock;
+        } else lockfile = await syncSkillsLock(options.cwd, manifest, currentLock, {
             onProgress
         });
+        const runtimeLock = await withBundledSelfSkillLock(options.cwd, manifest, lockfile);
+        reporter.start(Object.keys(runtimeLock.skills).length);
+        started = true;
+        for (const skillName of Object.keys(lockfile.skills))onProgress({
+            type: 'resolved',
+            skillName
+        });
         reporter.setPhase('fetching');
-        await fetchSkillsFromLock(options.cwd, manifest, lockfile, {
+        await fetchSkillsFromLock(options.cwd, manifest, runtimeLock, {
             onProgress
         });
         reporter.setPhase('linking');
-        await linkSkillsFromLock(options.cwd, manifest, lockfile, {
+        await linkSkillsFromLock(options.cwd, manifest, runtimeLock, {
             onProgress
         });
         reporter.setPhase('finalizing');
-        await writeSkillsLock(options.cwd, lockfile);
+        if (!options.frozenLockfile) await writeSkillsLock(options.cwd, lockfile);
         reporter.complete();
         return {
             status: 'installed',
-            installed: Object.keys(lockfile.skills)
+            installed: Object.keys(runtimeLock.skills)
         };
     } catch (error) {
         if (started) reporter.fail();
@@ -1922,8 +2013,9 @@ async function updateCommand(options) {
         result.status = 'failed';
         return result;
     }
-    await fetchSkillsFromLock(options.cwd, manifest, candidateLock);
-    await linkSkillsFromLock(options.cwd, manifest, candidateLock);
+    const runtimeLock = await withBundledSelfSkillLock(options.cwd, manifest, candidateLock);
+    await fetchSkillsFromLock(options.cwd, manifest, runtimeLock);
+    await linkSkillsFromLock(options.cwd, manifest, runtimeLock);
     await writeSkillsLock(options.cwd, candidateLock);
     result.status = result.updated.length > 0 ? 'updated' : 'skipped';
     return result;
@@ -1996,4 +2088,4 @@ async function runCli(argv, context = {}) {
         throw error;
     }
 }
-export { FileSystemError, GitError, ManifestError, NetworkError, ParseError, SkillError, SpmError, addCommand, cloneAndDiscover, codes_ErrorCode as ErrorCode, convertNodeError, createInstallProgressReporter, discoverSkillsInDir, fetchSkillsFromLock, formatErrorForDisplay, getExitCode, initCommand, installCommand, installSkills, installStageHooks, isLockInSync, isSpmError, linkSkillsFromLock, listRepoSkills, normalizeSpecifier, parseGitHubUrl, parseOwnerRepo, parseSpecifier, readSkillsLock, readSkillsManifest, resolveLockEntry, runCli, updateCommand, writeSkillsLock, writeSkillsManifest };
+export { FileSystemError, GitError, ManifestError, NetworkError, ParseError, SkillError, SpmError, addCommand, cloneAndDiscover, codes_ErrorCode as ErrorCode, convertNodeError, createInstallProgressReporter, discoverSkillsInDir, expandSkillsManifest, fetchSkillsFromLock, formatErrorForDisplay, getExitCode, initCommand, installCommand, installSkills, installStageHooks, isLockInSync, isSpmError, linkSkillsFromLock, listRepoSkills, normalizeSkillsManifest, normalizeSpecifier, parseGitHubUrl, parseOwnerRepo, parseSpecifier, readSkillsLock, readSkillsManifest, resolveLockEntry, runCli, updateCommand, writeSkillsLock, writeSkillsManifest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-package-manager",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -15,7 +15,9 @@
   },
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "skills",
+    "skills.schema.json"
   ],
   "dependencies": {
     "@clack/prompts": "^1.1.0",
@@ -23,7 +25,8 @@
     "picocolors": "^1.1.1",
     "semver": "^7.7.2",
     "tar": "^7.4.3",
-    "yaml": "^2.8.1"
+    "yaml": "^2.8.1",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@rslib/core": "^0.20.0",

package/skills/skills-package-manager-cli/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: skills-package-manager-cli
+description: Help users work in repositories that use skills-package-manager. Use when requests mention `skills.json`, `skills-lock.yaml`, `selfSkill`, `npx skills-package-manager init`,  `add`, `install`, `update`, skill specifiers, install directories like `.agents/skills`, or linked skill directories like `.claude/skills`
+---
+
+# skills-package-manager
+
+Use this skill for repositories that already use `skills-package-manager`, or when a user needs help understanding and editing its manifest, lockfile, and CLI workflow.
+
+## Core Model
+
+- `skills.json` is the source of truth.
+  It declares which skills a repo wants, where to materialize them, where to link them, and whether to include the bundled helper skill.
+- `skills-lock.yaml` is resolved state.
+  It pins commits, versions, paths, and digests so installs are reproducible.
+- Installed directories such as `.agents/skills` and linked directories such as `.claude/skills` are outputs.
+  They are produced from the manifest and lockfile; they are not the canonical config.
+
+## What `selfSkill` Means
+
+- `selfSkill: true` adds the bundled `skills-package-manager-cli` skill during install.
+- It is meant to help users who see `skills.json`, `skills-lock.yaml`, and `spm` commands but do not yet know how they fit together.
+- The bundled skill is injected automatically. It should not be added manually under `skills` unless there is a very specific reason.
+
+## Command Guide
+
+1. `npx skills-package-manager init`
+   - Creates `skills.json`.
+   - `npx skills-package-manager init --yes` writes the default manifest immediately.
+
+2. `npx skills-package-manager add <specifier> [--skill <name>]`
+   - Adds a skill to `skills.json`.
+   - Resolves it into `skills-lock.yaml`.
+   - Installs it into `installDir` and links it into each `linkTarget`.
+
+3. `npx skills-package-manager install`
+   - Reconciles the manifest, lockfile, and installed output.
+   - Without `--frozen-lockfile`, it updates `skills-lock.yaml` when needed.
+   - With `--frozen-lockfile`, it requires the lockfile to already match the manifest.
+
+4. `npx skills-package-manager update [skill...]`
+   - Refreshes resolvable entries in `skills-lock.yaml`.
+   - Skips `link:` skills, including the bundled `skills-package-manager-cli` self skill.
+
+## How To Triage User Questions
+
+1. If the user wants to change which skills a repo uses:
+   Edit `skills.json`, then run `npx skills-package-manager install`.
+
+2. If the user wants to understand pinned versions or why a change happened:
+   Inspect `skills-lock.yaml`.
+
+3. If the user says a skill is missing in their agent:
+   Check `installDir`, `linkTargets`, generated skill directories, and symlinks.
+
+4. If the user is confused about `selfSkill`:
+   Explain that it enables the bundled `skills-package-manager-cli` helper skill, not an arbitrary repo-local skill.
+
+## Specifier Reminders
+
+- `link:./path/to/skill-dir` points to a local skill directory.
+- `file:./pkg.tgz#path:/skills/name` points to a packaged tarball plus skill path.
+- `npm:@scope/pkg#path:/skills/name` resolves a package from the configured registry.
+- GitHub shorthand or Git URLs resolve remote repositories and may need `--skill` when multiple skills are available.
+
+## Validation Checklist
+
+- Keep `manifest`, `lockfile`, `installDir`, `linkTargets`, `skills`, and `specifier` terminology exact.
+- Treat `skills-lock.yaml` as generated state unless the task is specifically about lockfile internals or checked-in examples.
+- If you change this bundled skill inside the `skills-package-manager` repo, revalidate the skill folder and update any checked-in lockfile digest that refers to it.

package/skills.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "description": "JSON Schema URL for editor autocompletion",
+      "type": "string"
+    },
+    "installDir": {
+      "default": ".agents/skills",
+      "description": "Directory where skills will be installed",
+      "type": "string"
+    },
+    "linkTargets": {
+      "default": [],
+      "description": "Directories where skill symlinks will be created",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "selfSkill": {
+      "description": "Whether this project is itself a skill",
+      "type": "boolean"
+    },
+    "pnpmPlugin": {
+      "description": "pnpm-plugin-skills specific compatibility settings",
+      "type": "object",
+      "properties": {
+        "removePnpmfileChecksum": {
+          "description": "Temporarily remove pnpmfileChecksum from pnpm lockfiles in pnpm-plugin-skills afterAllResolved",
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "skills": {
+      "default": {},
+      "description": "Map of skill names to their specifiers",
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "type": "string"
+      }
+    }
+  },
+  "required": [
+    "installDir",
+    "linkTargets",
+    "skills"
+  ],
+  "additionalProperties": false
+}