@maccesar/aiskills 1.15.0 → 1.16.1

package/README.md

@@ -74,6 +74,7 @@ All three platforms use the same Agent Skills format: a `SKILL.md` file with YAM
 | audit-codebase       | Auditing     | Evidence-based audit methodology     | 2 files         |
 | vscode-extension-dev | VS Code      | VS Code Extension API docs           | 14 files        |
 | stitch-showcase      | Design Tools | Google Stitch export workflow        | 16 files        |
+| session-log          | Project      | Convention + 3 A/B rounds            | 2 files         |
 
 Use `aiskills list` to see available skills from the command line. Pull requests are welcome.
 
@@ -133,8 +134,6 @@ Hard restrictions:
 Distribution note:
 - Available via the plugin install (Option A above). Slash commands are not distributed by the npm CLI (Option B) because they are a Claude Code feature.
 
----
-
 ## How skills work
 
 Skills activate based on what you ask. You can write prompts normally:
@@ -308,6 +307,52 @@ Reference files:
 
 ---
 
+### session-log
+
+Gives a project one predictable place for its working state, so both you and any assistant know where to look instead of hunting through scattered notes. It installs a fixed four-file convention under `docs/project/` and writes a short pointer into every context file the repo has — `CLAUDE.md`, `AGENTS.md`, `GEMINI.md` — so the notes stay findable no matter which assistant opens the project next.
+
+The convention:
+
+| File | Holds | Loaded at startup |
+| --- | --- | --- |
+| `status.md` | Where the work stands: half-done things, next step, what's blocked, deployment state | **No** |
+| `requirements.md` | What the system must do, and the acceptance criterion for each item | Yes |
+| `decisions.md` | What was chosen and why. Append-only, dated | Yes |
+| `context.md` | Documentation map, architecture, conventions, traps | Yes |
+
+**Why `status.md` is excluded from startup.** Cached context is matched as a prefix — the first byte that differs invalidates everything after it. Status written inside a startup-loaded file means every update throws away the cache for all the stable content behind it. The file you edit most often is the one that must not load at startup.
+
+How to use it — just say it, in whatever words you'd use anyway:
+
+```
+"set up the project notes here — the mobile app lives at ../../Apps/MyApp"
+"ya me voy, déjame anotado dónde quedé"
+"where did we leave off? I haven't touched this repo in weeks"
+"my CLAUDE.md has the progress and a date inside it — should I move that?"
+```
+
+Closing a session and resuming one are different jobs and it treats them differently. On the way out it writes; on the way back in it reads `status.md` and then checks it against the repo before repeating it to you — what landed since the file was written, whether the branch it names still exists, what's uncommitted that it never mentioned. A three-week-old note is a snapshot, and the most expensive way to use one is to trust it.
+
+There is no slash command, by design: a command and a skill doing the same job means two copies of the logic that drift apart, and a command only works in Claude Code. This is one file that Claude, Codex and Gemini all read the same way — point any of them at `skills/session-log/SKILL.md` if it doesn't pick it up on its own.
+
+Once the convention is installed, finding the notes no longer depends on the skill at all — the pointer in `CLAUDE.md`, `AGENTS.md` and `GEMINI.md` is what any assistant reads at startup.
+
+What it will not do:
+- Commit, tag, push, or write CHANGELOG entries — that is a release, and releasing assumes the work is finished, which is the opposite of why this exists. Use `/release` for that.
+- Edit your uncommitted code. It reports what it finds broken and leaves it alone.
+- Invent a completion percentage. Without a fixed denominator any number is made up, so it counts what is enumerable or describes status in words.
+- Write a token, a password or a client's private details into the files. They get committed, and a secret deleted in a later commit is still in the history — it records where the credential lives instead.
+- Overwrite the record on arrival. If a resumed file turns out to be badly out of date it says so and offers; rewriting is your call.
+
+Measured behaviour, across three A/B rounds against a no-skill baseline (18 runs, adversarially graded):
+
+| | With skill | Without |
+| --- | --- | --- |
+| Kept volatile status out of the startup chain | 9 / 9 | 0 / 9 |
+| Left the user's broken uncommitted code untouched | yes | no — fixed it unasked |
+
+Token cost is 3–13% higher per run. **Those rounds graded an earlier layout** — a single status file versus an imported memory index — so what they establish is the split itself, not the four filenames. The paths added since (resuming against a stale file, upgrading an earlier install, monorepos, a gitignored `docs/`) have prompts written for them and have not been run. The grading notes, and an explicit account of what is and isn't measured, are in `skills/session-log/evals/`.
+
 ### stitch-showcase
 
 A workflow skill for processing Google Stitch design exports. It handles the full lifecycle: from raw zips to a navigable showcase, component standardization, and a visual component catalog.

package/lib/claude-plugin.js

@@ -0,0 +1,105 @@
+/**
+ * Detection of the maccesar-aiskills Claude Code marketplace plugin.
+ *
+ * When the plugin is installed, Claude Code already lists our skills and slash
+ * commands from its plugin cache, so the CLI must not also install its own copy
+ * into ~/.claude/ — that produces duplicate entries in the autocomplete.
+ *
+ * The subtlety, and the reason this lives in its own module: **the cache on disk
+ * does not mean the plugin is installed.** Uninstalling a plugin removes it from
+ * `enabledPlugins` in settings.json but leaves the cache directory behind.
+ * Treating that leftover directory as proof of installation makes the CLI skip
+ * work it should do, which leaves Claude Code with no skills at all and no way
+ * for the user to repair it by re-running install. So the question we answer here
+ * is "is the plugin enabled AND does it carry this file", never just the latter.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import {
+  CLAUDE_PLUGIN_KEY,
+  getClaudePluginSkillsPath,
+  getClaudeSettingsPaths,
+} from './config.js';
+
+/**
+ * Whether Claude Code currently has the aiskills plugin enabled.
+ * @param {string} baseDir - Optional base directory (defaults to homedir via config)
+ * @returns {boolean} True only when a settings file explicitly enables the plugin
+ */
+export function isClaudePluginEnabled(baseDir) {
+  for (const settingsPath of getClaudeSettingsPaths(baseDir)) {
+    try {
+      const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+      if (settings?.enabledPlugins?.[CLAUDE_PLUGIN_KEY] === true) {
+        return true;
+      }
+    } catch {
+      // Missing or malformed settings: nothing here says the plugin is enabled.
+      // Falling through to `false` is the safe direction — the cost of a wrong
+      // `false` is a duplicate entry, the cost of a wrong `true` is a user with
+      // no skills installed.
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether a plugin cache directory exists at all, regardless of whether the
+ * plugin is enabled. An enabled plugin implies a cache; a cache implies nothing,
+ * because uninstalling leaves it behind. Diagnostics use this to tell "never
+ * installed" apart from "uninstalled, leftovers on disk".
+ * @param {string} baseDir - Optional base directory
+ * @returns {boolean}
+ */
+export function hasClaudePluginCache(baseDir) {
+  return existsSync(getClaudePluginSkillsPath(baseDir));
+}
+
+/**
+ * Whether any cached version of the plugin carries the given file.
+ * @param {string} kind - Subdirectory inside the plugin ('skills' or 'commands')
+ * @param {string} entry - Entry to look for (skill directory or command file)
+ * @param {string} baseDir - Optional base directory
+ * @returns {boolean} True if a cached version contains it
+ */
+function pluginCacheContains(kind, entry, baseDir) {
+  const pluginBase = getClaudePluginSkillsPath(baseDir);
+  if (!existsSync(pluginBase)) return false;
+  try {
+    return readdirSync(pluginBase).some((version) =>
+      existsSync(join(pluginBase, version, kind, entry))
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether the installed plugin already provides this skill to Claude Code.
+ * @param {string} skillName - Skill name (e.g. 'session-log')
+ * @param {string} baseDir - Optional base directory
+ * @returns {boolean}
+ */
+export function pluginProvidesSkill(skillName, baseDir) {
+  return isClaudePluginEnabled(baseDir) && pluginCacheContains('skills', skillName, baseDir);
+}
+
+/**
+ * Whether the installed plugin already provides this slash command.
+ * @param {string} commandName - Command name without the .md extension
+ * @param {string} baseDir - Optional base directory
+ * @returns {boolean}
+ */
+export function pluginProvidesCommand(commandName, baseDir) {
+  return (
+    isClaudePluginEnabled(baseDir) && pluginCacheContains('commands', `${commandName}.md`, baseDir)
+  );
+}
+
+export default {
+  isClaudePluginEnabled,
+  hasClaudePluginCache,
+  pluginProvidesSkill,
+  pluginProvidesCommand,
+};

package/lib/commands/doctor.js

@@ -16,6 +16,11 @@ import {
 } from '../config.js';
 import { hasHook } from '../hooks.js';
 import { readLastCheck } from '../cache.js';
+import {
+  isClaudePluginEnabled,
+  hasClaudePluginCache,
+  pluginProvidesSkill,
+} from '../claude-plugin.js';
 
 const CHECK = chalk.green('✓');
 const CROSS = chalk.red('✗');
@@ -79,8 +84,18 @@ export async function doctorCommand() {
   for (const platform of platforms) {
     const missing = [];
     const broken = [];
+    const servedByPlugin = [];
 
     for (const skill of SKILLS) {
+      // A skill the marketplace plugin provides is *supposed* to have no mirror
+      // here — the CLI removes it on purpose to avoid a duplicate entry. Counting
+      // it as missing turns a healthy marketplace install into a wall of errors
+      // telling the user to run a command that will correctly do nothing.
+      if (platform.name === 'claude' && pluginProvidesSkill(skill, homeDir)) {
+        servedByPlugin.push(skill);
+        continue;
+      }
+
       const linkPath = join(platform.skillsDir, skill);
       try {
         const stat = lstatSync(linkPath);
@@ -96,15 +111,26 @@ export async function doctorCommand() {
       }
     }
 
-    const linkedCount = SKILLS.length - missing.length - broken.length;
+    const expected = SKILLS.length - servedByPlugin.length;
+    const linkedCount = expected - missing.length - broken.length;
+    const pluginNote =
+      servedByPlugin.length > 0
+        ? chalk.dim(` (+${servedByPlugin.length} served by the marketplace plugin)`)
+        : '';
 
     if (missing.length === 0 && broken.length === 0) {
-      console.log(`    ${CHECK} ${platform.displayName}: ${SKILLS.length}/${SKILLS.length} skills linked`);
+      const summary =
+        expected === 0
+          ? `all ${servedByPlugin.length} skills served by the marketplace plugin`
+          : `${linkedCount}/${expected} skills linked${pluginNote}`;
+      console.log(`    ${CHECK} ${platform.displayName}: ${summary}`);
     } else {
       const problems = [];
       if (missing.length > 0) problems.push(`missing: ${missing.join(', ')}`);
       if (broken.length > 0) problems.push(`broken: ${broken.join(', ')}`);
-      console.log(`    ${CROSS} ${platform.displayName}: ${linkedCount}/${SKILLS.length} skills linked (${problems.join('; ')})`);
+      console.log(
+        `    ${CROSS} ${platform.displayName}: ${linkedCount}/${expected} skills linked${pluginNote} (${problems.join('; ')})`
+      );
       issues += missing.length + broken.length;
 
       // Collect symlink issues for detailed report
@@ -117,6 +143,27 @@ export async function doctorCommand() {
     }
   }
 
+  // Marketplace plugin
+  //
+  // Worth its own section because the two channels look identical from the
+  // outside and produce opposite expectations: with the plugin enabled, absent
+  // mirrors are correct; without it, absent mirrors mean no skills at all.
+  console.log('');
+  console.log('  Marketplace plugin:');
+  const pluginEnabled = isClaudePluginEnabled(homeDir);
+  const pluginCached = hasClaudePluginCache(homeDir);
+
+  if (pluginEnabled) {
+    console.log(`    ${CHECK} Enabled — Claude Code is served by the plugin, mirrors intentionally absent`);
+  } else if (pluginCached) {
+    console.log(`    ${WARN} Not enabled, but a cache directory remains from a previous install`);
+    console.log(`      ${chalk.dim('Harmless on this version. On aiskills < 1.16.1 it made install skip')}`);
+    console.log(`      ${chalk.dim('every symlink, leaving Claude Code with no skills. Remove it with:')}`);
+    console.log(`      ${chalk.cyan('rm -rf ~/.claude/plugins/cache/maccesar-aiskills')}`);
+  } else {
+    console.log(`    ${CHECK} Not installed — skills reach Claude Code through npm mirrors`);
+  }
+
   // Symlink issues detail
   if (symlinkIssues.length > 0) {
     console.log('');

package/lib/commands/skills.js

@@ -79,10 +79,12 @@ export async function skillsCommand(options) {
     chalk.dim('(agentskills.io standard)')
   );
   console.log(
-    '  ' + chalk.dim('Read directly by Gemini, Codex, Cursor, Cline, Amp, GitHub Copilot, +more.')
+    '  ' + chalk.green('✓'),
+    chalk.dim('Gemini, Codex, Cursor, Cline, Amp, GitHub Copilot +more read it directly —')
   );
+  console.log('    ' + chalk.dim('nothing else to configure for them.'));
   console.log(
-    '  ' + chalk.dim('Below: extra symlink mirrors for Claude Code.')
+    '  ' + chalk.dim('Claude Code needs symlink mirrors, created below.')
   );
   console.log('');
 
@@ -112,10 +114,19 @@ export async function skillsCommand(options) {
     process.exit(1);
   }
 
-  // Show detected platforms
+  // Show detected platforms.
+  //
+  // Only assistants that need aiskills-managed mirrors appear here, so a bare
+  // "Claude Code detected" reads as if the other assistants were not found at
+  // all. They were never looked for: Gemini, Codex and the rest read
+  // ~/.agents/skills/ directly and are already served by the install itself.
   if (detectedPlatforms.length > 0) {
     for (const platform of detectedPlatforms) {
-      console.log(chalk.green('✓'), `${platform.displayName} detected`);
+      console.log(
+        chalk.green('✓'),
+        `${platform.displayName} detected`,
+        chalk.dim('— needs mirrors, linked below')
+      );
     }
     console.log('');
   } else if (isLocal) {
@@ -269,6 +280,10 @@ export async function skillsCommand(options) {
           spinner.succeed(
             `${commandsResult.installed.length} slash command${commandsResult.installed.length !== 1 ? 's' : ''} installed`
           );
+        } else if (commandsResult.skipped.length > 0) {
+          spinner.info(
+            `${commandsResult.skipped.length} slash command${commandsResult.skipped.length !== 1 ? 's' : ''} already provided by the marketplace plugin`
+          );
         } else {
           spinner.info('No slash commands to install');
         }

package/lib/commands/update.js

@@ -67,6 +67,10 @@ async function performUpdate(baseDir, repoDir, spinner) {
       spinner.succeed(
         `${commandsResult.installed.length} slash command${commandsResult.installed.length !== 1 ? 's' : ''} synced`
       );
+    } else if (commandsResult.skipped.length > 0) {
+      spinner.info(
+        `${commandsResult.skipped.length} slash command${commandsResult.skipped.length !== 1 ? 's' : ''} already provided by the marketplace plugin`
+      );
     } else {
       spinner.info('No slash commands to sync');
     }

package/lib/config.js

@@ -30,6 +30,7 @@ export const SKILLS = [
   'audit-codebase',
   'humaniza',
   'refactoring-ui',
+  'session-log',
   'stitch-showcase',
   'vscode-extension-dev',
 ];
@@ -63,6 +64,17 @@ export const CLAUDE_PLUGIN_NAME = 'aiskills';
 export const getClaudePluginSkillsPath = (baseDir = os.homedir()) =>
   path.join(baseDir, '.claude', 'plugins', 'cache', CLAUDE_PLUGIN_MARKETPLACE, CLAUDE_PLUGIN_NAME);
 
+// The key Claude Code writes under "enabledPlugins" when the plugin is installed.
+export const CLAUDE_PLUGIN_KEY = `${CLAUDE_PLUGIN_NAME}@${CLAUDE_PLUGIN_MARKETPLACE}`;
+
+// Where Claude Code records which plugins are enabled. Both files are consulted
+// because the local variant overrides the shared one, and either may carry the
+// entry depending on how the plugin was installed.
+export const getClaudeSettingsPaths = (baseDir = os.homedir()) => [
+  path.join(baseDir, '.claude', 'settings.json'),
+  path.join(baseDir, '.claude', 'settings.local.json'),
+];
+
 // AI platform detection
 //
 // Only platforms that need aiskills-managed symlinks appear here.

package/lib/installer.js

@@ -135,6 +135,7 @@ export async function installCommands(repoDir, baseDir = os.homedir()) {
     installed: [],
     failed: [],
     removed: [],
+    skipped: [],
   };
 
   const legacyLocal = removeCommands(baseDir, { legacyOnly: true });
@@ -147,7 +148,24 @@ export async function installCommands(repoDir, baseDir = os.homedir()) {
     results.failed.push(...legacyGlobal.failed);
   }
 
+  const { pluginProvidesCommand } = await import('./claude-plugin.js');
+  const commandsDir = getClaudeCommandsDir(baseDir);
+
   for (const cmd of COMMANDS) {
+    // Same rule the symlink step applies to skills: when the marketplace plugin
+    // already provides the command, installing our own copy makes it show up
+    // twice in the autocomplete. Clean up any copy left from before the plugin
+    // was installed.
+    if (pluginProvidesCommand(cmd, baseDir)) {
+      const stalePath = join(commandsDir, `${cmd}.md`);
+      if (existsSync(stalePath)) {
+        await remove(stalePath);
+        results.removed.push(cmd);
+      }
+      results.skipped.push(cmd);
+      continue;
+    }
+
     if (await installCommand(repoDir, cmd, baseDir)) {
       results.installed.push(cmd);
     } else {

package/lib/symlink.js

@@ -75,21 +75,16 @@ async function removePath(path) {
  * and an additional symlink at ~/.claude/skills/<skill> produces a duplicate
  * entry in the slash-command autocomplete. This helper lets the symlink step
  * skip Claude when the plugin already covers it.
+ *
+ * Requires the plugin to be *enabled*, not merely cached — see `claude-plugin.js`
+ * for why the distinction matters.
  * @param {string} skillName - Skill name (e.g. 'stitch-showcase')
  * @param {string} baseDir - Optional base directory (defaults to homedir via config)
  * @returns {Promise<boolean>} True if the plugin provides this skill
  */
 export async function isClaudePluginSkillInstalled(skillName, baseDir) {
-  const { readdir } = await import('fs/promises');
-  const { getClaudePluginSkillsPath } = await import('./config.js');
-  const pluginBase = getClaudePluginSkillsPath(baseDir);
-  if (!existsSync(pluginBase)) return false;
-  try {
-    const versions = await readdir(pluginBase);
-    return versions.some((v) => existsSync(join(pluginBase, v, 'skills', skillName)));
-  } catch {
-    return false;
-  }
+  const { pluginProvidesSkill } = await import('./claude-plugin.js');
+  return pluginProvidesSkill(skillName, baseDir);
 }
 
 /**

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@maccesar/aiskills",
-  "version": "1.15.0",
+  "version": "1.16.1",
   "description": "AI coding assistant skills for Claude Code, Gemini CLI, and Codex CLI",
   "type": "module",
   "bin": {
     "aiskills": "./bin/aiskills.js"
   },
   "scripts": {
-    "test": "node --test test/**/*.test.js",
+    "test": "node --test test/*.test.js",
     "lint": "eslint lib/**/*.js",
     "format": "prettier --write lib/**/*.js"
   },