@iceinvein/agent-skills 0.1.17 → 0.1.19

package/README.md

@@ -87,7 +87,7 @@ Skills that control how the agent communicates — output compression, token eff
 ## Commands
 
 ```
-bunx @iceinvein/agent-skills install <skill> [--tool <tool>] [-g]
+bunx @iceinvein/agent-skills install <skill> [--tool <tool>] [--activation <mode>] [-g]
 bunx @iceinvein/agent-skills remove <skill> [-g]
 bunx @iceinvein/agent-skills update <skill> [-g]
 bunx @iceinvein/agent-skills list
@@ -97,8 +97,18 @@ bunx @iceinvein/agent-skills info <skill>
 | Flag | |
 |------|---|
 | `--tool <tool>` | Target a specific tool: `claude`, `cursor`, `codex`, `gemini` |
+| `--activation <mode>` | For skills that support it: `session` (manual `/skill`) or `global` (auto via `SessionStart` hook). Claude Code only. |
 | `-g, --global` | Install to home directory (available in all projects) |
 
+## Activation Modes (Claude Code)
+
+Some skills — like `terse` — support activation modes. Pick one at install time:
+
+- **session** (default) — invoke the skill manually with `/<skill>` each session
+- **global** — auto-activate every Claude Code session via a `SessionStart` hook in `.claude/settings.json`
+
+If a skill declares activation support and you're installing for Claude Code interactively, the CLI prompts you. Use `--activation session` or `--activation global` for scripted installs. `remove` strips the hook cleanly; `update` preserves your choice across version bumps.
+
 ## Supported Tools
 
 | Tool | Prompt Skills | MCP Skills |

package/dist/cli/index.js

@@ -25,6 +25,7 @@ async function detectTools(cwd) {
 // src/cli/types.ts
 var TOOL_NAMES = ["claude", "cursor", "codex", "gemini"];
 var SKILL_TYPES = ["prompt", "code", "hybrid"];
+var ACTIVATION_MODES = ["session", "global"];
 function validateManifest(data) {
   if (typeof data !== "object" || data === null) {
     return { ok: false, error: "Manifest must be an object" };
@@ -56,6 +57,29 @@ function validateManifest(data) {
   if (typeof d.install !== "object" || d.install === null) {
     return { ok: false, error: "Missing 'install' configuration" };
   }
+  if (d.activation !== undefined) {
+    if (typeof d.activation !== "object" || d.activation === null) {
+      return { ok: false, error: "'activation' must be an object" };
+    }
+    const a = d.activation;
+    if (!Array.isArray(a.modes) || a.modes.length === 0) {
+      return { ok: false, error: "'activation.modes' must be a non-empty array" };
+    }
+    for (const m of a.modes) {
+      if (!ACTIVATION_MODES.includes(m)) {
+        return { ok: false, error: `Invalid activation mode '${m}': must be one of ${ACTIVATION_MODES.join(", ")}` };
+      }
+    }
+    if (!ACTIVATION_MODES.includes(a.default)) {
+      return { ok: false, error: `Invalid 'activation.default': must be one of ${ACTIVATION_MODES.join(", ")}` };
+    }
+    if (!a.modes.includes(a.default)) {
+      return { ok: false, error: "'activation.default' must be one of 'activation.modes'" };
+    }
+    if (a.claudeHookDirective !== undefined && typeof a.claudeHookDirective !== "string") {
+      return { ok: false, error: "'activation.claudeHookDirective' must be a string" };
+    }
+  }
   return { ok: true, manifest: d };
 }
 
@@ -109,9 +133,56 @@ async function fetchAllSkillFiles(skillName, manifest) {
 // src/cli/adapters/claude.ts
 import { existsSync as existsSync2, mkdirSync, rmSync, unlinkSync } from "node:fs";
 import { dirname, join as join2 } from "node:path";
+function matchesSkillDirective(command, skillName) {
+  return command.includes(`Activate ${skillName} skill`);
+}
+async function wireSessionStartHook(settingsPath, skillName, directive) {
+  let settings = {};
+  if (existsSync2(settingsPath)) {
+    settings = await Bun.file(settingsPath).json();
+  }
+  if (!settings.hooks)
+    settings.hooks = {};
+  if (!settings.hooks.SessionStart)
+    settings.hooks.SessionStart = [];
+  const command = `echo '${directive}'`;
+  for (const group of settings.hooks.SessionStart) {
+    for (const hook of group.hooks ?? []) {
+      if (matchesSkillDirective(hook.command, skillName))
+        return;
+    }
+  }
+  settings.hooks.SessionStart.push({
+    hooks: [{ type: "command", command }]
+  });
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  await Bun.write(settingsPath, JSON.stringify(settings, null, 2) + `
+`);
+}
+async function unwireSessionStartHook(settingsPath, skillName) {
+  if (!existsSync2(settingsPath))
+    return;
+  const settings = await Bun.file(settingsPath).json();
+  const sessionStart = settings.hooks?.SessionStart;
+  if (!sessionStart)
+    return;
+  const filteredGroups = sessionStart.map((group) => ({
+    hooks: (group.hooks ?? []).filter((h) => !matchesSkillDirective(h.command, skillName))
+  })).filter((group) => group.hooks.length > 0);
+  if (filteredGroups.length === 0) {
+    delete settings.hooks.SessionStart;
+  } else {
+    settings.hooks.SessionStart = filteredGroups;
+  }
+  if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+  await Bun.write(settingsPath, JSON.stringify(settings, null, 2) + `
+`);
+}
 var claudeAdapter = {
   name: "claude",
-  async install(cwd, manifest, files) {
+  async install(cwd, manifest, files, activation) {
     const installed = [];
     const config = manifest.install.claude;
     if (!config)
@@ -147,6 +218,13 @@ var claudeAdapter = {
 `);
       installed.push(".claude/settings.json");
     }
+    if (activation === "global" && manifest.activation?.claudeHookDirective) {
+      const settingsPath = join2(cwd, ".claude/settings.json");
+      await wireSessionStartHook(settingsPath, manifest.name, manifest.activation.claudeHookDirective);
+      if (!installed.includes(".claude/settings.json")) {
+        installed.push(".claude/settings.json");
+      }
+    }
     return installed;
   },
   async remove(cwd, manifest, installedFiles) {
@@ -178,6 +256,10 @@ var claudeAdapter = {
         }
       }
     }
+    if (manifest.activation?.claudeHookDirective) {
+      const settingsPath = join2(cwd, ".claude/settings.json");
+      await unwireSessionStartHook(settingsPath, manifest.name);
+    }
   }
 };
 
@@ -186,7 +268,7 @@ import { existsSync as existsSync3, mkdirSync as mkdirSync2, unlinkSync as unlin
 import { dirname as dirname2, join as join3 } from "node:path";
 var cursorAdapter = {
   name: "cursor",
-  async install(cwd, manifest, files) {
+  async install(cwd, manifest, files, _activation) {
     const installed = [];
     const config = manifest.install.cursor;
     if (!config)
@@ -260,7 +342,7 @@ import { existsSync as existsSync4 } from "node:fs";
 import { join as join4 } from "node:path";
 var codexAdapter = {
   name: "codex",
-  async install(cwd, manifest, files) {
+  async install(cwd, manifest, files, _activation) {
     const installed = [];
     const config = manifest.install.codex;
     if (!config)
@@ -316,7 +398,7 @@ import { existsSync as existsSync5, mkdirSync as mkdirSync3, unlinkSync as unlin
 import { dirname as dirname3, join as join5 } from "node:path";
 var geminiAdapter = {
   name: "gemini",
-  async install(cwd, manifest, files) {
+  async install(cwd, manifest, files, _activation) {
     const installed = [];
     const config = manifest.install.gemini;
     if (!config)
@@ -424,7 +506,7 @@ async function removeSkillFromLockfile(cwd, skillName) {
 }
 
 // src/cli/commands/install.ts
-async function installSkill(cwd, manifest, files, targetTools) {
+async function installSkill(cwd, manifest, files, targetTools, activation) {
   const compatibleTools = targetTools.filter((t) => manifest.tools.includes(t));
   const skipped = targetTools.filter((t) => !manifest.tools.includes(t));
   if (compatibleTools.length === 0) {
@@ -437,7 +519,7 @@ async function installSkill(cwd, manifest, files, targetTools) {
   const allFiles = [];
   for (const tool of compatibleTools) {
     const adapter = getAdapter(tool);
-    const toolFiles = await adapter.install(cwd, manifest, files);
+    const toolFiles = await adapter.install(cwd, manifest, files, activation);
     installed[tool] = toolFiles;
     allFiles.push(...toolFiles);
   }
@@ -445,7 +527,8 @@ async function installSkill(cwd, manifest, files, targetTools) {
     version: manifest.version,
     tools: compatibleTools,
     installedAt: new Date().toISOString(),
-    files: allFiles
+    files: allFiles,
+    ...activation !== undefined ? { activation } : {}
   });
   return { ok: true, installed, skipped };
 }
@@ -594,7 +677,7 @@ async function removeSkill2(cwd, skillName) {
 }
 
 // src/cli/commands/install.ts
-async function installSkill2(cwd, manifest, files, targetTools) {
+async function installSkill2(cwd, manifest, files, targetTools, activation) {
   const compatibleTools = targetTools.filter((t) => manifest.tools.includes(t));
   const skipped = targetTools.filter((t) => !manifest.tools.includes(t));
   if (compatibleTools.length === 0) {
@@ -607,7 +690,7 @@ async function installSkill2(cwd, manifest, files, targetTools) {
   const allFiles = [];
   for (const tool of compatibleTools) {
     const adapter = getAdapter(tool);
-    const toolFiles = await adapter.install(cwd, manifest, files);
+    const toolFiles = await adapter.install(cwd, manifest, files, activation);
     installed[tool] = toolFiles;
     allFiles.push(...toolFiles);
   }
@@ -615,7 +698,8 @@ async function installSkill2(cwd, manifest, files, targetTools) {
     version: manifest.version,
     tools: compatibleTools,
     installedAt: new Date().toISOString(),
-    files: allFiles
+    files: allFiles,
+    ...activation !== undefined ? { activation } : {}
   });
   return { ok: true, installed, skipped };
 }
@@ -629,6 +713,7 @@ async function updateSkill(cwd, skillName) {
   }
   const oldVersion = entry.version;
   const tools = entry.tools;
+  const activation = entry.activation;
   const manifestResult = await fetchSkillManifest2(skillName);
   if (!manifestResult.ok) {
     return { ok: false, error: manifestResult.error };
@@ -638,7 +723,7 @@ async function updateSkill(cwd, skillName) {
     return { ok: false, error: filesResult.error };
   }
   await removeSkill2(cwd, skillName);
-  const installResult = await installSkill2(cwd, manifestResult.manifest, filesResult, tools);
+  const installResult = await installSkill2(cwd, manifestResult.manifest, filesResult, tools, activation);
   if (!installResult.ok) {
     return { ok: false, error: installResult.error };
   }
@@ -832,6 +917,26 @@ Select (comma-separated numbers, e.g. 1,3): `);
   }
   return selected;
 }
+async function promptActivation(skillName, modes) {
+  console.log(`
+How should ${skillName} activate in Claude Code?
+`);
+  const labels = {
+    session: `Per-session - invoke manually with /${skillName}`,
+    global: "Global - auto-activate every session (adds SessionStart hook)"
+  };
+  for (let i = 0;i < modes.length; i++) {
+    console.log(`  ${i + 1}) ${labels[modes[i]]}`);
+  }
+  const answer = await ask(`
+Select: `);
+  const n = parseInt(answer, 10);
+  if (isNaN(n) || n < 1 || n > modes.length) {
+    console.error("Invalid selection. Exiting.");
+    process.exit(1);
+  }
+  return modes[n - 1];
+}
 
 // src/cli/index.ts
 import { mkdirSync as mkdirSync4 } from "fs";
@@ -873,7 +978,7 @@ function printHelp() {
 @iceinvein/agent-skills \u2014 Install agent skills into AI coding tools
 
 Usage:
-  agent-skills install <skill>  [--tool <tool>] [-g]  Install a skill
+  agent-skills install <skill>  [--tool <tool>] [--activation <session|global>] [-g]  Install a skill
   agent-skills remove  <skill>  [-g]                   Remove a skill
   agent-skills update  <skill>  [-g]                   Update a skill
   agent-skills update  --all    [-g]                   Update all installed skills
@@ -886,6 +991,7 @@ Flags:
   --tool <tool>   Install for a specific tool (${TOOL_NAMES2.join(", ")})
   -g, --global    Install to home directory (available in all projects)
   --dry-run       With bump --all: check without writing (exit 1 if unbumped)
+  --activation <mode>  Set activation mode for skills that support it (session or global)
 `);
 }
 function printInstalled(result, skipped) {
@@ -953,7 +1059,23 @@ async function main() {
           console.log(`Detected tools: ${tools.join(", ")}`);
         }
       }
-      const result = await installSkill(installDir, manifestResult.manifest, filesResult, tools);
+      let activation;
+      const manifest = manifestResult.manifest;
+      if (manifest.activation && tools.includes("claude")) {
+        const validModes = manifest.activation.modes;
+        if (flags.activation) {
+          if (!validModes.includes(flags.activation)) {
+            console.error(`Error: activation mode '${flags.activation}' not supported. Must be one of: ${validModes.join(", ")}`);
+            process.exit(1);
+          }
+          activation = flags.activation;
+        } else if (process.stdin.isTTY) {
+          activation = await promptActivation(manifest.name, validModes);
+        } else {
+          activation = manifest.activation.default;
+        }
+      }
+      const result = await installSkill(installDir, manifestResult.manifest, filesResult, tools, activation);
       if (!result.ok) {
         console.error(`Error: ${result.error}`);
         process.exit(1);
@@ -1010,7 +1132,11 @@ async function main() {
         console.error(`Error: ${result.error}`);
         process.exit(1);
       }
-      console.log(`\u2713 Updated '${skillName}' from v${result.from} to v${result.to}`);
+      if (result.from === result.to) {
+        console.log(`\u2298 '${skillName}' is already up to date (v${result.to})`);
+      } else {
+        console.log(`\u2713 Updated '${skillName}' from v${result.from} to v${result.to}`);
+      }
       break;
     }
     case "list": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Install agent skills into AI coding tools",
   "author": "iceinvein",
   "license": "MIT",

package/skills/index.json

@@ -165,6 +165,6 @@
     "name": "terse",
     "description": "Professional output compression — proper grammar, no fluff, ~50-60% fewer tokens. Three levels: clean, tight, sharp.",
     "type": "prompt",
-    "version": "1.0.0"
+    "version": "1.1.0"
   }
 ]

package/skills/terse/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "terse",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Professional output compression — proper grammar, no fluff, ~50-60% fewer tokens. Three levels: clean, tight, sharp.",
   "author": "iceinvein",
   "type": "prompt",
@@ -27,5 +27,10 @@
     "gemini": {
       "prompt": ".gemini/skills/terse.md"
     }
+  },
+  "activation": {
+    "modes": ["session", "global"],
+    "default": "session",
+    "claudeHookDirective": "Activate terse skill at tight level for this session."
   }
 }