skillshop 2.0.0 → 2.1.0

package/src/agents-instructions.js

@@ -0,0 +1,219 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { legacyAgentsContent } from './legacy-agents-content.js';
+
+export class AgentsInstructionsError extends Error {}
+
+const blockSuffix = '.block.md';
+const referencePattern = /\{\{\s*([^{}]+?)\s*\}\}/g;
+const namedReferencePattern = /^fragments\s*\[\s*(["'])([^"'\[\]]+)\1\s*\]$/;
+const aggregateExpression = 'blocks';
+const regionBeginPrefix = '<!-- skillshop agents: begin v';
+const regionBeginPattern = /^<!-- (?:skillshop|skillz) agents: begin v\S+ -->$/;
+const regionEndLine = '<!-- skillshop agents: end -->';
+const oldRegionEndLine = '<!-- skillz agents: end -->';
+const legacyMarkerPattern = /^<!-- skillz agents: AGENTS\.md@\S+ -->$/;
+const fragmentsBegin = '<!-- skillshop fragments: begin -->';
+const fragmentsEnd = '<!-- skillshop fragments: end -->';
+
+export function discoverBlocks(contentDirectory) {
+  if (!fs.existsSync(contentDirectory)) return [];
+  return fs
+    .readdirSync(contentDirectory, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(blockSuffix))
+    .map((entry) => entry.name)
+    .sort()
+    .map((name) => ({
+      name,
+      content: fs.readFileSync(path.join(contentDirectory, name), 'utf8').trim()
+    }));
+}
+
+function invalidReference(expression, line) {
+  return new AgentsInstructionsError(
+    `invalid fragment reference {{ ${expression} }} at line ${line} of the agents base template; ` +
+      'use {{ fragments["name.block.md"] }} or {{ blocks }}'
+  );
+}
+
+export function composeAgentsInstructions(contentDirectory) {
+  const basePath = path.join(contentDirectory, 'AGENTS.md');
+  if (!fs.existsSync(basePath)) {
+    throw new AgentsInstructionsError(`missing agents base template: ${basePath}`);
+  }
+
+  const base = fs.readFileSync(basePath, 'utf8');
+  const blocks = discoverBlocks(contentDirectory);
+  const blocksByName = new Map(blocks.map((block) => [block.name, block.content]));
+
+  const references = [];
+  for (const match of base.matchAll(referencePattern)) {
+    const expression = match[1];
+    const line = base.slice(0, match.index).split('\n').length;
+    if (expression === aggregateExpression) {
+      references.push({ kind: 'aggregate', start: match.index, end: match.index + match[0].length });
+      continue;
+    }
+    const named = expression.match(namedReferencePattern);
+    if (!named || named[2].includes('/') || named[2].includes('\\')) {
+      throw invalidReference(expression, line);
+    }
+    references.push({ kind: 'named', name: named[2], start: match.index, end: match.index + match[0].length });
+  }
+
+  for (const reference of references) {
+    if (reference.kind !== 'named' || blocksByName.has(reference.name)) continue;
+    if (fs.existsSync(path.join(contentDirectory, reference.name))) {
+      throw new AgentsInstructionsError(
+        `agents base template references ${reference.name}, which is not a *.block.md fragment`
+      );
+    }
+    throw new AgentsInstructionsError(`agents base template references missing fragment: ${reference.name}`);
+  }
+
+  const referencedNames = new Set(
+    references.filter((reference) => reference.kind === 'named').map((reference) => reference.name)
+  );
+  const aggregate = blocks
+    .filter((block) => !referencedNames.has(block.name))
+    .map((block) => block.content)
+    .join('\n\n');
+
+  let content = '';
+  let cursor = 0;
+  for (const reference of references) {
+    content += base.slice(cursor, reference.start);
+    content += reference.kind === 'aggregate' ? aggregate : blocksByName.get(reference.name);
+    cursor = reference.end;
+  }
+  content += base.slice(cursor);
+
+  return { content };
+}
+
+function regionText(version, composed) {
+  return `${regionBeginPrefix}${version} -->\n${composed}\n${regionEndLine}`;
+}
+
+function ambiguous(message) {
+  return new AgentsInstructionsError(
+    `refusing to update agents instructions: ${message}; fix or remove the affected block manually, then rerun skillshop agents`
+  );
+}
+
+function appendRegion(existing, region) {
+  if (existing === '') return `${region}\n`;
+  const separator = existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
+  return `${existing}${separator}${region}\n`;
+}
+
+function applyManagedRegion(lines, starts, ends, region, composed, version) {
+  const [start] = starts;
+  const [end] = ends;
+  const inner = lines.slice(start + 1, end).join('\n');
+  const installedVersion = lines[start].match(/<!-- (?:skillshop|skillz) agents: begin v(\S+) -->/)[1];
+  if (installedVersion === version && inner === composed && lines[start].startsWith(regionBeginPrefix) && lines[end] === regionEndLine) {
+    return { action: 'unchanged', text: lines.join('\n') };
+  }
+  const next = [...lines.slice(0, start), ...region.split('\n'), ...lines.slice(end + 1)];
+  return { action: 'refreshed', text: next.join('\n') };
+}
+
+function legacyChunks(lines, markerIndices) {
+  const legacyLines = legacyAgentsContent.split('\n');
+  const spans = [];
+  for (const markerIndex of markerIndices) {
+    const start = markerIndex - 1 - legacyLines.length;
+    const owned =
+      start >= 0 &&
+      lines.slice(start, start + legacyLines.length).join('\n') === legacyAgentsContent &&
+      lines[start + legacyLines.length] === '' &&
+      (start === 0 || lines[start - 1] === '');
+    if (!owned) {
+      throw new AgentsInstructionsError(
+        `refusing to update agents instructions: unrecognized legacy skillz agents marker at line ${markerIndex + 1} ` +
+          '(the installed guidance was edited or does not match the historical skillz content); ' +
+          'remove the installed legacy guidance manually, then rerun skillshop agents'
+      );
+    }
+    spans.push([start, markerIndex]);
+  }
+  spans.sort((a, b) => a[0] - b[0]);
+  return spans;
+}
+
+function migrateLegacy(lines, markerIndices, region, composed, version) {
+  const spans = legacyChunks(lines, markerIndices);
+  const insertPoint = '\u0000skillz-region-insert-point\u0000';
+  const remainder = [];
+  let cursor = 0;
+  for (const [start, end] of spans) {
+    remainder.push(...lines.slice(cursor, start));
+    if (end === spans[spans.length - 1][1]) remainder.push(insertPoint);
+    cursor = end + 1;
+  }
+  remainder.push(...lines.slice(cursor));
+
+  const collapsed = [];
+  for (const line of remainder) {
+    if (line === '' && line !== insertPoint && collapsed[collapsed.length - 1] === '') continue;
+    collapsed.push(line);
+  }
+
+  const insertAt = collapsed.indexOf(insertPoint);
+  const before = collapsed.slice(0, insertAt);
+  const after = collapsed.slice(insertAt + 1);
+  let text = before.join('\n');
+  if (text !== '' && !text.endsWith('\n\n')) text += text.endsWith('\n') ? '\n' : '\n\n';
+  text += `${region}\n`;
+  const afterText = after.join('\n');
+  if (afterText !== '') text += afterText.startsWith('\n') ? afterText : `\n\n${afterText}`;
+  return { action: 'installed', text: text.replace(/\n+$/, '\n') };
+}
+
+export function applyInstructions(existing, composed, version) {
+  const composedText = composed.trimEnd();
+  const region = regionText(version, composedText);
+  const lines = existing.split('\n');
+  const begins = [];
+  const ends = [];
+  const legacyMarkers = [];
+  lines.forEach((line, index) => {
+    if (regionBeginPattern.test(line)) begins.push(index);
+    else if (line === regionEndLine || line === oldRegionEndLine) ends.push(index);
+    else if (legacyMarkerPattern.test(line)) legacyMarkers.push(index);
+  });
+
+  if (begins.length !== ends.length || begins.length > 1) {
+    throw ambiguous(
+      'the managed agents block markers are malformed (each marker must appear exactly once on its own line)'
+    );
+  }
+  if (legacyMarkers.length && begins.length) {
+    throw ambiguous('the file contains both legacy skillz agents markers and a managed agents block');
+  }
+
+  if (begins.length) return applyManagedRegion(lines, begins, ends, region, composedText, version);
+  if (legacyMarkers.length) return migrateLegacy(lines, legacyMarkers, region, composedText, version);
+  return { action: 'installed', text: appendRegion(existing, region) };
+}
+
+export function applyLocalFragments(existing, contentDirectory) {
+  const blocks = discoverBlocks(contentDirectory);
+  const lines = existing.split('\n');
+  const begins = lines.flatMap((line, index) => line === fragmentsBegin ? [index] : []);
+  const ends = lines.flatMap((line, index) => line === fragmentsEnd ? [index] : []);
+  if (begins.length !== ends.length || begins.length > 1 || (begins.length && begins[0] >= ends[0])) {
+    throw new AgentsInstructionsError('local fragment markers are malformed');
+  }
+  if (!blocks.length && !begins.length) return { action: 'unchanged', text: existing };
+  const region = blocks.length
+    ? `${fragmentsBegin}\n${blocks.map((block) => block.content).join('\n\n')}\n${fragmentsEnd}`
+    : '';
+  if (!begins.length) return { action: 'installed', text: appendRegion(existing, region) };
+  const current = lines.slice(begins[0], ends[0] + 1).join('\n');
+  if (current === region) return { action: 'unchanged', text: existing };
+  const before = lines.slice(0, begins[0]);
+  const after = lines.slice(ends[0] + 1);
+  return { action: 'refreshed', text: [...before, ...(region ? region.split('\n') : []), ...after].join('\n') };
+}

package/src/cli.js

@@ -1,29 +1,32 @@
 #!/usr/bin/env node
 
-import fs from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
 import { buildSkillLibrary, initSkillLibrary, readSkillLibrary, validateSkillLibrary } from './library.js';
 import { exportSkill, reexportSkill, unexportSkill } from './export.js';
 import { importSkill, resolveSkill } from './import.js';
-
-const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+import { installDeclaredUserSkills } from './user-install.js';
+import { reconcileLegacyState, runLegacyCli } from './legacy-cli.js';
+import { parseLibrarySkillReference, skillName } from './specifier.js';
 
 function help() {
-  console.log(`skillshop v${VERSION} — build and consume portable skill libraries
+  console.log(`
+Library commands:
 
-Usage:
-  skillshop init
+  skillshop library init
+  skillshop library list
   skillshop export skill:<name> <directory>
   skillshop export skill:<name> --from <package> [--skill skill:<source-name>]
   skillshop unexport skill:<name>
-  skillshop list
   skillshop validate
   skillshop build
-  skillshop resolve <library> skill:<name>
-  skillshop import <library> skill:<name> --to <directory> [--force]
+  skillshop resolve <library>:<skill>
+  skillshop import <library>:<skill> [--global] [--to <directory>] [--force]
+  skillshop install-user [package-dir] [--if-global] [--to <skills-dir>]
 
-A library publishes skills by portable specifier, for example skill:clips.
-Consumers resolve the same specifier regardless of where the library stores SKILL.md.`);
+A library publishes skills by portable specifier, for example skill:review.
+Import uses the short <library>:<skill> form and copies to .agents/skills/<skill> by default.
+--global copies to ~/.agents/skills/<skill> and replaces an existing directory.`);
 }
 
 function flag(args, name) {
@@ -31,10 +34,29 @@ function flag(args, name) {
   return index === -1 ? null : args[index + 1];
 }
 
-async function main(argv) {
+function librarySelection(args, usage) {
+  if (args.length === 1) return { reference: args[0] };
+  if (args.length === 2 && args[1].startsWith('skill:')) {
+    return { library: args[0], specifier: args[1] };
+  }
+  throw new Error(usage);
+}
+
+const libraryCommands = new Set(['export', 'unexport', 'validate', 'build', 'resolve', 'import', 'install-user']);
+
+async function main(argv, { libraryNamespace = false } = {}) {
   const [command, ...args] = argv;
-  if (!command || command === '--help' || command === '-h' || command === 'help') return help();
-  if (command === '--version' || command === '-v') return console.log(`skillshop v${VERSION}`);
+  if (!libraryNamespace && command === 'library') {
+    if (args[0] === 'init' || args[0] === 'list') return main(args, { libraryNamespace: true });
+    if (!args.length || args[0] === '--help' || args[0] === '-h') return help();
+    throw new Error('Usage: skillshop library init | list');
+  }
+  if (!libraryNamespace && (!command || command === '--help' || command === '-h' || command === 'help')) {
+    await runLegacyCli(['--help']);
+    return help();
+  }
+  if (!libraryNamespace && (command === '--version' || command === '-v')) return runLegacyCli(argv);
+  if (!libraryNamespace && !libraryCommands.has(command)) return runLegacyCli(argv);
 
   if (command === 'init') {
     initSkillLibrary();
@@ -75,22 +97,64 @@ async function main(argv) {
     return;
   }
   if (command === 'resolve') {
-    if (args.length !== 2) throw new Error('Usage: skillshop resolve <library> skill:<name>');
-    console.log(JSON.stringify(await resolveSkill({ library: args[0], specifier: args[1] }), null, 2));
+    const selection = librarySelection(args, 'Usage: skillshop resolve <library>:<skill>');
+    console.log(JSON.stringify(await resolveSkill(selection), null, 2));
     return;
   }
   if (command === 'import') {
-    if (args.length < 2) throw new Error('Usage: skillshop import <library> skill:<name> --to <directory> [--force]');
-    const targetDir = flag(args, '--to');
-    if (!targetDir) throw new Error('--to <directory> is required');
-    const result = await importSkill({ library: args[0], specifier: args[1], targetDir, overwrite: args.includes('--force') });
+    const usage = 'Usage: skillshop import <library>:<skill> [--global] [--to <directory>] [--force]';
+    const positional = [];
+    let targetDir;
+    let globalInstall = false;
+    let force = false;
+    for (let index = 0; index < args.length; index += 1) {
+      const argument = args[index];
+      if (argument === '--to') {
+        targetDir = args[++index];
+        if (!targetDir || targetDir.startsWith('--')) throw new Error(usage);
+      } else if (argument === '--global' || argument === '-g') globalInstall = true;
+      else if (argument === '--force') force = true;
+      else if (argument.startsWith('-')) throw new Error(usage);
+      else positional.push(argument);
+    }
+    const selection = librarySelection(positional, usage);
+    if (globalInstall && targetDir) throw new Error('--global and --to cannot be combined');
+    const name = selection.reference
+      ? parseLibrarySkillReference(selection.reference).name
+      : skillName(selection.specifier);
+    const result = await importSkill({
+      ...selection,
+      targetDir: globalInstall ? path.join(os.homedir(), '.agents', 'skills', name) : targetDir,
+      overwrite: force || globalInstall,
+    });
     console.log(`${result.specifier} -> ${result.targetDir}`);
     return;
   }
-  throw new Error(`Unknown command: ${command}`);
+  if (command === 'install-user') {
+    if (args.includes('--if-global') && process.env.npm_config_global !== 'true') {
+      console.log('Skipped user skills: this is not a global npm install');
+      return;
+    }
+    const library = args[0] && !args[0].startsWith('--') ? args[0] : '.';
+    const userSkillsDir = flag(args, '--to') || undefined;
+    const results = await installDeclaredUserSkills({ library, userSkillsDir });
+    for (const result of results) console.log(`${result.specifier} -> ${result.targetDir}${result.updated ? ' (updated)' : ''}`);
+    return;
+  }
+  throw new Error(`Unknown library command: ${command}`);
 }
 
-main(process.argv.slice(2)).catch((error) => {
+const argv = process.argv.slice(2);
+const usingLibraryCommands = argv[0] === 'library' || libraryCommands.has(argv[0]);
+
+try {
+  if (usingLibraryCommands) reconcileLegacyState();
+  try {
+    await main(argv);
+  } finally {
+    if (usingLibraryCommands) reconcileLegacyState();
+  }
+} catch (error) {
   console.error(`skillshop: ${error.message}`);
   process.exitCode = 1;
-});
+}

package/src/import.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { pathToFileURL, fileURLToPath } from 'node:url';
-import { normalizeSkillSpecifier, parseSkillSpecifier } from './specifier.js';
+import { normalizeSkillSpecifier, parseSkillSpecifier, parseLibrarySkillReference } from './specifier.js';
 import { SKILLSHOP_MANIFEST_FILE, SKILLSHOP_SCHEMA_VERSION } from './library.js';
 
 async function importManifestFile(file) {
@@ -42,9 +42,13 @@ export async function loadSkillLibrary(library, { cwd = process.cwd() } = {}) {
   return validatePublishedManifest(await importManifestFile(resolved), value);
 }
 
-export async function resolveSkill({ library, specifier, cwd = process.cwd() }) {
-  const normalized = normalizeSkillSpecifier(specifier);
-  const manifest = await loadSkillLibrary(library, { cwd });
+export async function resolveSkill({ reference, library, specifier, cwd = process.cwd() }) {
+  if (reference && (library !== undefined || specifier !== undefined)) {
+    throw new Error('Use reference or library and specifier, not both');
+  }
+  const selected = reference ? parseLibrarySkillReference(reference) : { library, specifier: normalizeSkillSpecifier(specifier) };
+  const normalized = selected.specifier;
+  const manifest = await loadSkillLibrary(selected.library, { cwd });
   const href = manifest.skills[normalized];
   if (typeof href !== 'string' || !href) throw new Error(`${normalized} is not exported by ${manifest.packageName || 'the library'}`);
   const url = new URL(href);
@@ -84,6 +88,7 @@ function assertSafeMergeTarget(target, relativeFile) {
 }
 
 export async function importSkill({
+  reference,
   library,
   specifier,
   targetDir,
@@ -91,10 +96,10 @@ export async function importSkill({
   overwrite = false,
   merge = false,
 }) {
-  if (typeof targetDir !== 'string' || !targetDir.trim()) throw new Error('targetDir is required');
+  if (targetDir !== undefined && (typeof targetDir !== 'string' || !targetDir.trim())) throw new Error('targetDir must be a nonempty path');
   if (merge && overwrite) throw new Error('merge and overwrite cannot both be enabled');
-  const skill = await resolveSkill({ library, specifier, cwd });
-  const target = path.resolve(cwd, targetDir);
+  const skill = await resolveSkill({ reference, library, specifier, cwd });
+  const target = path.resolve(cwd, targetDir ?? path.join('.agents', 'skills', skill.name));
   const exists = fs.existsSync(target);
 
   if (exists && merge) {

package/src/index.js

@@ -2,3 +2,4 @@ export * from './specifier.js';
 export * from './library.js';
 export * from './export.js';
 export * from './import.js';
+export * from './user-install.js';

package/src/legacy-agents-content.js

@@ -0,0 +1,36 @@
+// Snapshot of agents-content/AGENTS.md as shipped through skillz 0.3.x.
+// Installations made before the managed-block format appended this content verbatim
+// followed by a "<!-- skillz agents: AGENTS.md@<version> -->" marker line.
+export const legacyAgentsContent = [
+  "### Baseline tone",
+  "",
+  "This applies to every text that you write.",
+  "",
+  "Adopt a skeptical, questioning approach. Don't default to praise, criticize my ideas, provide counterpoints, dig deeper. I need you to find the blind spots in my thinking and account for them, in a straight shooting and constructive way.",
+  "",
+  "Don't overuse adjectives, don't compliment or criticize my arguments in a personalized way, just attend to the facts and topics. Tell it like it is; don't sugar-coat responses. Also don't explicitly mention you're NOT praising me or actively say you're “getting to the point”. Don't comment on your tone at all.",
+  "",
+  "When explaining things, provide depth of concepts, be extensive, with context, clarity and explanation of concepts along the way.",
+  "",
+  "## Communication and writing",
+  "",
+  "- Write directly and concisely. Prefer short, distinct sentences over long compound ones.",
+  "- Do not overuse em dashes. There are periods, commas, semicolons, and exclamation marks. Use them.",
+  "- Remove hedges and filler that add no information. Keep technical terms when they add precision.",
+  "- Avoid exact counts unless the number matters. \"All the callers\" is usually better than \"all 4 callers.\"",
+  "- Short, natural reactions are fine. Use \"Good catch!\" rather than an inflated response.",
+  "- Avoid throat clearing, restating the question, routine process narration, and closing offers. Brief accountability or correction is fine when it helps the reader.",
+  "- Do not explain in prose what a table or diff already makes clear.",
+  "- State genuine uncertainty briefly. Do not add defensive caveats or pre-empt objections nobody raised.",
+  "- Brevity must not hide important behavior, risk, uncertainty, or evidence.",
+  "",
+  "### Approval for external actions",
+  "",
+  "All external actions require explicit approval before proceeding. Even on autopilot mode, do not post without explicit written authorizaton from the user.",
+  "",
+  "- Before posting or editing a PR comment, review reply, issue comment, Slack message, or other external message, show me the exact draft and get an explicit OK. This includes edits to existing messages.",
+  "- Before resolving review threads, requesting reviewers, or changing other visible review state, describe the exact action and get an explicit OK.",
+  "- Create an issue, epic, or PR only when I explicitly request it. Before opening one, show me its proposed title and body and get an explicit OK.",
+  "- A direct request to update an existing PR or issue body authorizes that update without another approval. Fetch the latest body from the host immediately before editing it.",
+  "- Pushing requested commits does not require another approval."
+].join("\n");