@standardagents/skill 0.17.0-next.a4b7340 → 0.17.0

package/dist/index.d.ts

@@ -17,9 +17,10 @@ declare function listSkills(): SkillDefinition[];
 declare function getSkill(name: SkillName): SkillDefinition;
 declare function resolveSkillDir(name: SkillName): string;
 declare function resolveSkillFile(name: SkillName, ...segments: string[]): string;
+declare function skillPackageVersion(): Promise<string>;
 declare function readSkillFile(name: SkillName, ...segments: string[]): Promise<string>;
 declare function copySkill(name: SkillName, destinationRoot: string, options?: CopySkillOptions): Promise<string>;
 declare const skillPackageRoot: string;
 declare const skillsRoot: string;
 
-export { type CopySkillOptions, type SkillDefinition, type SkillName, copySkill, getSkill, listSkills, readSkillFile, resolveSkillDir, resolveSkillFile, skillPackageRoot, skillsRoot };
+export { type CopySkillOptions, type SkillDefinition, type SkillName, copySkill, getSkill, listSkills, readSkillFile, resolveSkillDir, resolveSkillFile, skillPackageRoot, skillPackageVersion, skillsRoot };

package/dist/index.js

@@ -1,9 +1,10 @@
 // src/index.ts
-import { cp, mkdir, readFile } from "fs/promises";
+import { cp, mkdir, readFile, writeFile } from "fs/promises";
 import { fileURLToPath } from "url";
 import { isAbsolute, relative, resolve } from "path";
 var PACKAGE_ROOT = fileURLToPath(new URL("../", import.meta.url));
 var SKILLS_ROOT = resolve(PACKAGE_ROOT, "skills");
+var VERSION_STAMP_PATTERN = /<!--\s*installed-skill-version:\s*__SKILL_VERSION__\s*-->/g;
 var SKILL_CATALOG = {
   agentbuilder: {
     description: "Compose Standard Agents from models, prompts, tools, hooks, APIs, and subagents using markdown-authored guidance."
@@ -44,9 +45,26 @@ function resolveSkillDir(name) {
 function resolveSkillFile(name, ...segments) {
   return resolveInside(resolveSkillDir(name), segments);
 }
+var cachedVersion = null;
+function skillPackageVersion() {
+  cachedVersion ??= readFile(resolve(PACKAGE_ROOT, "package.json"), "utf8").then(
+    (manifest) => JSON.parse(manifest).version
+  );
+  return cachedVersion;
+}
+async function stampSkillVersion(content) {
+  if (!content.includes("__SKILL_VERSION__")) {
+    return content;
+  }
+  const version = await skillPackageVersion();
+  return content.replace(
+    VERSION_STAMP_PATTERN,
+    `<!-- installed-skill-version: ${version} -->`
+  );
+}
 async function readSkillFile(name, ...segments) {
   const target = segments.length === 0 ? resolveSkillFile(name, "SKILL.md") : resolveSkillFile(name, ...segments);
-  return readFile(target, "utf8");
+  return stampSkillVersion(await readFile(target, "utf8"));
 }
 async function copySkill(name, destinationRoot, options = {}) {
   const sourceDir = resolveSkillDir(name);
@@ -58,6 +76,9 @@ async function copySkill(name, destinationRoot, options = {}) {
     force: options.overwrite ?? false,
     errorOnExist: !(options.overwrite ?? false)
   });
+  const entryFile = resolve(targetDir, "SKILL.md");
+  const entryContent = await readFile(entryFile, "utf8");
+  await writeFile(entryFile, await stampSkillVersion(entryContent), "utf8");
   return targetDir;
 }
 var skillPackageRoot = PACKAGE_ROOT;
@@ -70,6 +91,7 @@ export {
   resolveSkillDir,
   resolveSkillFile,
   skillPackageRoot,
+  skillPackageVersion,
   skillsRoot
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { cp, mkdir, readFile } from 'node:fs/promises'\nimport { fileURLToPath } from 'node:url'\nimport { isAbsolute, relative, resolve } from 'node:path'\n\nconst PACKAGE_ROOT = fileURLToPath(new URL('../', import.meta.url))\nconst SKILLS_ROOT = resolve(PACKAGE_ROOT, 'skills')\n\nconst SKILL_CATALOG = {\n  agentbuilder: {\n    description:\n      'Compose Standard Agents from models, prompts, tools, hooks, APIs, and subagents using markdown-authored guidance.',\n  },\n} as const\n\nexport type SkillName = keyof typeof SKILL_CATALOG\n\nexport interface SkillDefinition {\n  name: SkillName\n  description: string\n  directory: string\n  entryFile: string\n}\n\nexport interface CopySkillOptions {\n  overwrite?: boolean\n}\n\nfunction assertSkillName(name: string): asserts name is SkillName {\n  if (!(name in SKILL_CATALOG)) {\n    throw new Error(\n      `Unknown Standard Agents skill \"${name}\". Expected one of: ${Object.keys(SKILL_CATALOG).join(', ')}.`\n    )\n  }\n}\n\nfunction resolveInside(baseDir: string, segments: readonly string[]): string {\n  const candidate = resolve(baseDir, ...segments)\n  const relativePath = relative(baseDir, candidate)\n\n  if (relativePath.startsWith('..') || isAbsolute(relativePath)) {\n    throw new Error('Skill paths must stay within the skill directory.')\n  }\n\n  return candidate\n}\n\nexport function listSkills(): SkillDefinition[] {\n  return (Object.keys(SKILL_CATALOG) as SkillName[]).map((name) => getSkill(name))\n}\n\nexport function getSkill(name: SkillName): SkillDefinition {\n  const definition = SKILL_CATALOG[name]\n  const directory = resolveSkillDir(name)\n\n  return {\n    name,\n    description: definition.description,\n    directory,\n    entryFile: resolveSkillFile(name, 'SKILL.md'),\n  }\n}\n\nexport function resolveSkillDir(name: SkillName): string {\n  assertSkillName(name)\n  return resolve(SKILLS_ROOT, name)\n}\n\nexport function resolveSkillFile(name: SkillName, ...segments: string[]): string {\n  return resolveInside(resolveSkillDir(name), segments)\n}\n\nexport async function readSkillFile(\n  name: SkillName,\n  ...segments: string[]\n): Promise<string> {\n  const target = segments.length === 0\n    ? resolveSkillFile(name, 'SKILL.md')\n    : resolveSkillFile(name, ...segments)\n\n  return readFile(target, 'utf8')\n}\n\nexport async function copySkill(\n  name: SkillName,\n  destinationRoot: string,\n  options: CopySkillOptions = {}\n): Promise<string> {\n  const sourceDir = resolveSkillDir(name)\n  const targetRoot = resolve(destinationRoot)\n  const targetDir = resolve(targetRoot, name)\n\n  await mkdir(targetRoot, { recursive: true })\n  await cp(sourceDir, targetDir, {\n    recursive: true,\n    force: options.overwrite ?? false,\n    errorOnExist: !(options.overwrite ?? false),\n  })\n\n  return targetDir\n}\n\nexport const skillPackageRoot = PACKAGE_ROOT\nexport const skillsRoot = SKILLS_ROOT\n"],"mappings":";AAAA,SAAS,IAAI,OAAO,gBAAgB;AACpC,SAAS,qBAAqB;AAC9B,SAAS,YAAY,UAAU,eAAe;AAE9C,IAAM,eAAe,cAAc,IAAI,IAAI,OAAO,YAAY,GAAG,CAAC;AAClE,IAAM,cAAc,QAAQ,cAAc,QAAQ;AAElD,IAAM,gBAAgB;AAAA,EACpB,cAAc;AAAA,IACZ,aACE;AAAA,EACJ;AACF;AAeA,SAAS,gBAAgB,MAAyC;AAChE,MAAI,EAAE,QAAQ,gBAAgB;AAC5B,UAAM,IAAI;AAAA,MACR,kCAAkC,IAAI,uBAAuB,OAAO,KAAK,aAAa,EAAE,KAAK,IAAI,CAAC;AAAA,IACpG;AAAA,EACF;AACF;AAEA,SAAS,cAAc,SAAiB,UAAqC;AAC3E,QAAM,YAAY,QAAQ,SAAS,GAAG,QAAQ;AAC9C,QAAM,eAAe,SAAS,SAAS,SAAS;AAEhD,MAAI,aAAa,WAAW,IAAI,KAAK,WAAW,YAAY,GAAG;AAC7D,UAAM,IAAI,MAAM,mDAAmD;AAAA,EACrE;AAEA,SAAO;AACT;AAEO,SAAS,aAAgC;AAC9C,SAAQ,OAAO,KAAK,aAAa,EAAkB,IAAI,CAAC,SAAS,SAAS,IAAI,CAAC;AACjF;AAEO,SAAS,SAAS,MAAkC;AACzD,QAAM,aAAa,cAAc,IAAI;AACrC,QAAM,YAAY,gBAAgB,IAAI;AAEtC,SAAO;AAAA,IACL;AAAA,IACA,aAAa,WAAW;AAAA,IACxB;AAAA,IACA,WAAW,iBAAiB,MAAM,UAAU;AAAA,EAC9C;AACF;AAEO,SAAS,gBAAgB,MAAyB;AACvD,kBAAgB,IAAI;AACpB,SAAO,QAAQ,aAAa,IAAI;AAClC;AAEO,SAAS,iBAAiB,SAAoB,UAA4B;AAC/E,SAAO,cAAc,gBAAgB,IAAI,GAAG,QAAQ;AACtD;AAEA,eAAsB,cACpB,SACG,UACc;AACjB,QAAM,SAAS,SAAS,WAAW,IAC/B,iBAAiB,MAAM,UAAU,IACjC,iBAAiB,MAAM,GAAG,QAAQ;AAEtC,SAAO,SAAS,QAAQ,MAAM;AAChC;AAEA,eAAsB,UACpB,MACA,iBACA,UAA4B,CAAC,GACZ;AACjB,QAAM,YAAY,gBAAgB,IAAI;AACtC,QAAM,aAAa,QAAQ,eAAe;AAC1C,QAAM,YAAY,QAAQ,YAAY,IAAI;AAE1C,QAAM,MAAM,YAAY,EAAE,WAAW,KAAK,CAAC;AAC3C,QAAM,GAAG,WAAW,WAAW;AAAA,IAC7B,WAAW;AAAA,IACX,OAAO,QAAQ,aAAa;AAAA,IAC5B,cAAc,EAAE,QAAQ,aAAa;AAAA,EACvC,CAAC;AAED,SAAO;AACT;AAEO,IAAM,mBAAmB;AACzB,IAAM,aAAa;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { cp, mkdir, readFile, writeFile } from 'node:fs/promises'\nimport { fileURLToPath } from 'node:url'\nimport { isAbsolute, relative, resolve } from 'node:path'\n\nconst PACKAGE_ROOT = fileURLToPath(new URL('../', import.meta.url))\nconst SKILLS_ROOT = resolve(PACKAGE_ROOT, 'skills')\nconst VERSION_STAMP_PATTERN = /<!--\\s*installed-skill-version:\\s*__SKILL_VERSION__\\s*-->/g\n\nconst SKILL_CATALOG = {\n  agentbuilder: {\n    description:\n      'Compose Standard Agents from models, prompts, tools, hooks, APIs, and subagents using markdown-authored guidance.',\n  },\n} as const\n\nexport type SkillName = keyof typeof SKILL_CATALOG\n\nexport interface SkillDefinition {\n  name: SkillName\n  description: string\n  directory: string\n  entryFile: string\n}\n\nexport interface CopySkillOptions {\n  overwrite?: boolean\n}\n\nfunction assertSkillName(name: string): asserts name is SkillName {\n  if (!(name in SKILL_CATALOG)) {\n    throw new Error(\n      `Unknown Standard Agents skill \"${name}\". Expected one of: ${Object.keys(SKILL_CATALOG).join(', ')}.`\n    )\n  }\n}\n\nfunction resolveInside(baseDir: string, segments: readonly string[]): string {\n  const candidate = resolve(baseDir, ...segments)\n  const relativePath = relative(baseDir, candidate)\n\n  if (relativePath.startsWith('..') || isAbsolute(relativePath)) {\n    throw new Error('Skill paths must stay within the skill directory.')\n  }\n\n  return candidate\n}\n\nexport function listSkills(): SkillDefinition[] {\n  return (Object.keys(SKILL_CATALOG) as SkillName[]).map((name) => getSkill(name))\n}\n\nexport function getSkill(name: SkillName): SkillDefinition {\n  const definition = SKILL_CATALOG[name]\n  const directory = resolveSkillDir(name)\n\n  return {\n    name,\n    description: definition.description,\n    directory,\n    entryFile: resolveSkillFile(name, 'SKILL.md'),\n  }\n}\n\nexport function resolveSkillDir(name: SkillName): string {\n  assertSkillName(name)\n  return resolve(SKILLS_ROOT, name)\n}\n\nexport function resolveSkillFile(name: SkillName, ...segments: string[]): string {\n  return resolveInside(resolveSkillDir(name), segments)\n}\n\nlet cachedVersion: Promise<string> | null = null\n\nexport function skillPackageVersion(): Promise<string> {\n  cachedVersion ??= readFile(resolve(PACKAGE_ROOT, 'package.json'), 'utf8').then(\n    (manifest) => JSON.parse(manifest).version as string\n  )\n\n  return cachedVersion\n}\n\nasync function stampSkillVersion(content: string): Promise<string> {\n  if (!content.includes('__SKILL_VERSION__')) {\n    return content\n  }\n\n  const version = await skillPackageVersion()\n\n  return content.replace(\n    VERSION_STAMP_PATTERN,\n    `<!-- installed-skill-version: ${version} -->`\n  )\n}\n\nexport async function readSkillFile(\n  name: SkillName,\n  ...segments: string[]\n): Promise<string> {\n  const target = segments.length === 0\n    ? resolveSkillFile(name, 'SKILL.md')\n    : resolveSkillFile(name, ...segments)\n\n  return stampSkillVersion(await readFile(target, 'utf8'))\n}\n\nexport async function copySkill(\n  name: SkillName,\n  destinationRoot: string,\n  options: CopySkillOptions = {}\n): Promise<string> {\n  const sourceDir = resolveSkillDir(name)\n  const targetRoot = resolve(destinationRoot)\n  const targetDir = resolve(targetRoot, name)\n\n  await mkdir(targetRoot, { recursive: true })\n  await cp(sourceDir, targetDir, {\n    recursive: true,\n    force: options.overwrite ?? false,\n    errorOnExist: !(options.overwrite ?? false),\n  })\n\n  const entryFile = resolve(targetDir, 'SKILL.md')\n  const entryContent = await readFile(entryFile, 'utf8')\n  await writeFile(entryFile, await stampSkillVersion(entryContent), 'utf8')\n\n  return targetDir\n}\n\nexport const skillPackageRoot = PACKAGE_ROOT\nexport const skillsRoot = SKILLS_ROOT\n"],"mappings":";AAAA,SAAS,IAAI,OAAO,UAAU,iBAAiB;AAC/C,SAAS,qBAAqB;AAC9B,SAAS,YAAY,UAAU,eAAe;AAE9C,IAAM,eAAe,cAAc,IAAI,IAAI,OAAO,YAAY,GAAG,CAAC;AAClE,IAAM,cAAc,QAAQ,cAAc,QAAQ;AAClD,IAAM,wBAAwB;AAE9B,IAAM,gBAAgB;AAAA,EACpB,cAAc;AAAA,IACZ,aACE;AAAA,EACJ;AACF;AAeA,SAAS,gBAAgB,MAAyC;AAChE,MAAI,EAAE,QAAQ,gBAAgB;AAC5B,UAAM,IAAI;AAAA,MACR,kCAAkC,IAAI,uBAAuB,OAAO,KAAK,aAAa,EAAE,KAAK,IAAI,CAAC;AAAA,IACpG;AAAA,EACF;AACF;AAEA,SAAS,cAAc,SAAiB,UAAqC;AAC3E,QAAM,YAAY,QAAQ,SAAS,GAAG,QAAQ;AAC9C,QAAM,eAAe,SAAS,SAAS,SAAS;AAEhD,MAAI,aAAa,WAAW,IAAI,KAAK,WAAW,YAAY,GAAG;AAC7D,UAAM,IAAI,MAAM,mDAAmD;AAAA,EACrE;AAEA,SAAO;AACT;AAEO,SAAS,aAAgC;AAC9C,SAAQ,OAAO,KAAK,aAAa,EAAkB,IAAI,CAAC,SAAS,SAAS,IAAI,CAAC;AACjF;AAEO,SAAS,SAAS,MAAkC;AACzD,QAAM,aAAa,cAAc,IAAI;AACrC,QAAM,YAAY,gBAAgB,IAAI;AAEtC,SAAO;AAAA,IACL;AAAA,IACA,aAAa,WAAW;AAAA,IACxB;AAAA,IACA,WAAW,iBAAiB,MAAM,UAAU;AAAA,EAC9C;AACF;AAEO,SAAS,gBAAgB,MAAyB;AACvD,kBAAgB,IAAI;AACpB,SAAO,QAAQ,aAAa,IAAI;AAClC;AAEO,SAAS,iBAAiB,SAAoB,UAA4B;AAC/E,SAAO,cAAc,gBAAgB,IAAI,GAAG,QAAQ;AACtD;AAEA,IAAI,gBAAwC;AAErC,SAAS,sBAAuC;AACrD,oBAAkB,SAAS,QAAQ,cAAc,cAAc,GAAG,MAAM,EAAE;AAAA,IACxE,CAAC,aAAa,KAAK,MAAM,QAAQ,EAAE;AAAA,EACrC;AAEA,SAAO;AACT;AAEA,eAAe,kBAAkB,SAAkC;AACjE,MAAI,CAAC,QAAQ,SAAS,mBAAmB,GAAG;AAC1C,WAAO;AAAA,EACT;AAEA,QAAM,UAAU,MAAM,oBAAoB;AAE1C,SAAO,QAAQ;AAAA,IACb;AAAA,IACA,iCAAiC,OAAO;AAAA,EAC1C;AACF;AAEA,eAAsB,cACpB,SACG,UACc;AACjB,QAAM,SAAS,SAAS,WAAW,IAC/B,iBAAiB,MAAM,UAAU,IACjC,iBAAiB,MAAM,GAAG,QAAQ;AAEtC,SAAO,kBAAkB,MAAM,SAAS,QAAQ,MAAM,CAAC;AACzD;AAEA,eAAsB,UACpB,MACA,iBACA,UAA4B,CAAC,GACZ;AACjB,QAAM,YAAY,gBAAgB,IAAI;AACtC,QAAM,aAAa,QAAQ,eAAe;AAC1C,QAAM,YAAY,QAAQ,YAAY,IAAI;AAE1C,QAAM,MAAM,YAAY,EAAE,WAAW,KAAK,CAAC;AAC3C,QAAM,GAAG,WAAW,WAAW;AAAA,IAC7B,WAAW;AAAA,IACX,OAAO,QAAQ,aAAa;AAAA,IAC5B,cAAc,EAAE,QAAQ,aAAa;AAAA,EACvC,CAAC;AAED,QAAM,YAAY,QAAQ,WAAW,UAAU;AAC/C,QAAM,eAAe,MAAM,SAAS,WAAW,MAAM;AACrD,QAAM,UAAU,WAAW,MAAM,kBAAkB,YAAY,GAAG,MAAM;AAExE,SAAO;AACT;AAEO,IAAM,mBAAmB;AACzB,IAAM,aAAa;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/skill",
-  "version": "0.17.0-next.a4b7340",
+  "version": "0.17.0",
   "private": false,
   "publishConfig": {
     "access": "public",

package/skills/agentbuilder/SKILL.md

@@ -29,6 +29,21 @@ For deeper reference material that this skill links to, see:
 
 > If the `agents/*/AGENTS.md` files don't exist in your project yet, run `pnpm exec agents scaffold` to create them.
 
+## Keeping this skill up to date
+
+<!-- installed-skill-version: __SKILL_VERSION__ -->
+
+This skill ships as `@standardagents/skill` on npm, and the version installed here is stamped in the HTML comment above. The first time you use this skill in a conversation, verify it is current:
+
+1. If the stamp above still reads `__SKILL_VERSION__`, this is an unstamped development copy — skip this check.
+2. Run `npm view @standardagents/skill version`. If the command fails (offline, no npm, no shell access), skip silently. This check must never block, retry, or interrupt real work.
+3. If the published version is newer than the stamp, tell the user in one short line and offer to update. Updating overwrites this file — including any local edits — so get the user's OK before running:
+   - Codex install (file lives under `.codex/skills/`): `npx @standardagents/cli@latest skill --force --agent codex`
+   - Claude Code install (file lives under `.claude/agents/`): `npx @standardagents/cli@latest skill --force --agent claude`
+4. After updating, re-read the new file before continuing.
+
+Do this at most once per conversation, then move on to the task at hand.
+
 ---
 
 ## Before you write any code