@maccesar/aiskills 1.20.0 → 1.21.1

package/README.md

@@ -324,13 +324,15 @@ The convention:
 
 | File | Holds | Loaded at startup |
 | --- | --- | --- |
-| `status.md` | Where the work stands: half-done things, next step, what's blocked, deployment state | **No** |
+| `status.md` | Where the work stands: half-done things, next step, what's blocked, deployment state, which assistant wrote the note | **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 |
+| `context.md` | Documentation map, architecture, conventions, traps, provenance | 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.
 
+**It also records what built the project.** Months in, a question comes up that the four files used to leave unanswered: what was this made with? You want to reopen a piece of work by referring back to it, and that only works in the tool that still holds the transcript — a model remembers nothing between sessions, and Codex, Claude Code and Gemini each keep their own history where no other one can read it. So `context.md` gets a provenance table naming the tool, the model and what it produced, and `status.md` gets a line naming what wrote that note. One row per stretch of work, never per session: a row per session would grow without bound inside a startup-loaded file, which is the problem the split above exists to avoid. The model is recorded only as the environment states it — an invented model id reads as verified whether or not anyone checked it.
+
 How to use it — just say it, in whatever words you'd use anyway:
 
 ```

package/lib/commands/doctor.js

@@ -9,8 +9,10 @@ import { join } from 'path';
 import os from 'os';
 import {
   SKILLS,
+  COMMANDS,
   PACKAGE_VERSION,
   getAgentsSkillsDir,
+  getClaudeCommandsDir,
   getConfigDir,
   getPlatforms,
 } from '../config.js';
@@ -20,6 +22,7 @@ import {
   isClaudePluginEnabled,
   hasClaudePluginCache,
   pluginProvidesSkill,
+  pluginProvidesCommand,
 } from '../claude-plugin.js';
 
 const CHECK = chalk.green('✓');
@@ -30,6 +33,7 @@ export async function doctorCommand() {
   const homeDir = os.homedir();
   const skillsDir = getAgentsSkillsDir(homeDir);
   const claudeDir = join(homeDir, '.claude');
+  const commandsDir = getClaudeCommandsDir(homeDir);
   const cacheDir = getConfigDir();
 
   let issues = 0;
@@ -59,6 +63,27 @@ export async function doctorCommand() {
     issues += missingSkills.length;
   }
 
+  // Slash commands the enabled marketplace plugin serves are intentionally
+  // absent from ~/.claude/commands/ to avoid duplicate autocomplete entries.
+  const missingCommands = [];
+  const pluginCommands = [];
+  for (const command of COMMANDS) {
+    if (pluginProvidesCommand(command, homeDir)) {
+      pluginCommands.push(command);
+    } else if (!existsSync(join(commandsDir, `${command}.md`))) {
+      missingCommands.push(command);
+    }
+  }
+  const expectedCommands = COMMANDS.length - pluginCommands.length;
+  if (pluginCommands.length === COMMANDS.length) {
+    console.log(`  ${CHECK} Slash commands: all ${COMMANDS.length} served by the marketplace plugin`);
+  } else if (missingCommands.length === 0) {
+    console.log(`  ${CHECK} Slash commands: ${expectedCommands}/${expectedCommands} installed in ~/.claude/commands/`);
+  } else {
+    console.log(`  ${CROSS} Slash commands: ${expectedCommands - missingCommands.length}/${expectedCommands} installed (missing: ${missingCommands.join(', ')})`);
+    issues += missingCommands.length;
+  }
+
   // Hook check
   if (hasHook(claudeDir)) {
     console.log(`  ${CHECK} Hook: SessionStart configured`);

package/lib/commands/skills.js

@@ -304,11 +304,21 @@ export async function skillsCommand(options) {
           skillsToInstall,
           baseDir
         );
-        if (symlinkResult.linked.length === skillsToInstall.length) {
-          spinner.succeed(`${platform.displayName}: Skills linked`);
+        const expected = skillsToInstall.length - symlinkResult.skipped.length;
+        const pluginNote =
+          symlinkResult.skipped.length > 0
+            ? ` (${symlinkResult.skipped.length} served by the marketplace plugin)`
+            : '';
+
+        if (expected === 0) {
+          spinner.info(
+            `${platform.displayName}: All ${symlinkResult.skipped.length} skills served by the marketplace plugin`
+          );
+        } else if (symlinkResult.linked.length === expected) {
+          spinner.succeed(`${platform.displayName}: Skills linked${pluginNote}`);
         } else {
           spinner.warn(
-            `${platform.displayName}: ${symlinkResult.linked.length}/${skillsToInstall.length} skills linked`
+            `${platform.displayName}: ${symlinkResult.linked.length}/${expected} skills linked${pluginNote}`
           );
         }
       }

package/lib/config.js

@@ -52,7 +52,8 @@ export const LEGACY_COMMANDS = [];
 export const getConfigDir = () => path.join(os.homedir(), '.aiskills');
 
 // Directory paths
-export const getAgentsSkillsDir = (baseDir = os.homedir()) => path.join(baseDir, '.agents', 'skills');
+export const getAgentsDir = (baseDir = os.homedir()) => path.join(baseDir, '.agents');
+export const getAgentsSkillsDir = (baseDir = os.homedir()) => path.join(getAgentsDir(baseDir), 'skills');
 export const getClaudeSkillsDir = (baseDir = os.homedir()) => path.join(baseDir, '.claude', 'skills');
 export const getClaudeCommandsDir = (baseDir = os.homedir()) => path.join(baseDir, '.claude', 'commands');
 export const getGeminiSkillsDir = (baseDir = os.homedir()) => path.join(baseDir, '.gemini', 'skills');
@@ -111,11 +112,17 @@ export default {
   COMMANDS,
   LEGACY_COMMANDS,
   getConfigDir,
+  getAgentsDir,
   getAgentsSkillsDir,
   getClaudeSkillsDir,
   getClaudeCommandsDir,
   getGeminiSkillsDir,
   getCodexSkillsDir,
+  CLAUDE_PLUGIN_MARKETPLACE,
+  CLAUDE_PLUGIN_NAME,
+  CLAUDE_PLUGIN_KEY,
+  getClaudePluginSkillsPath,
+  getClaudeSettingsPaths,
   getPlatforms,
   GITHUB_API_HEADERS,
 };

package/lib/installer.js

@@ -18,6 +18,7 @@ import {
   getClaudeCommandsDir,
 } from './config.js';
 import { removeSkills, removeCommands } from './cleanup.js';
+import { createSymlinkOrCopy } from './symlink.js';
 
 /**
  * Recursively copy a directory
@@ -37,6 +38,8 @@ export async function copyDirectory(src, dest) {
  * @param {string} repoDir - Repository directory
  * @param {string} skillName - Name of the skill
  * @param {string} baseDir - Base directory for installation
+ * Development checkouts are linked so `npm link` users see edits immediately.
+ * Published npm packages are copied so installed skills remain independent.
  * @returns {Promise<boolean>} True if installed successfully
  */
 export async function installSkill(repoDir, skillName, baseDir = os.homedir()) {
@@ -52,6 +55,10 @@ export async function installSkill(repoDir, skillName, baseDir = os.homedir()) {
     return false;
   }
 
+  if (existsSync(join(repoDir, '.git'))) {
+    return createSymlinkOrCopy(skillSrc, skillDest, true);
+  }
+
   if (existsSync(skillDest)) {
     await remove(skillDest);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/aiskills",
-  "version": "1.20.0",
+  "version": "1.21.1",
   "description": "AI coding assistant skills for Claude Code, Gemini CLI, and Codex CLI",
   "type": "module",
   "bin": {
@@ -56,6 +56,8 @@
     "bin/",
     "lib/",
     "skills/",
+    "!skills/**/__pycache__/",
+    "!skills/**/*.py[cod]",
     "commands/"
   ],
   "publishConfig": {

package/skills/session-log/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: session-log
-description: 'The convention that decides WHERE a project keeps its working state, and why part of it must not load at startup. Four fixed files under docs/project/ — status (volatile, never imported), requirements, decisions, context (stable, imported) — plus a pointer written into every context file the repo has, so the notes are findable from Claude Code, Codex or Gemini alike. Use this whenever someone closes a working session or picks one up ("ya me voy, déjame anotado dónde quedé", "where did we leave off?"), asks where project notes should live or why they keep ending up scattered, wonders whether progress and dates belong inside CLAUDE.md / AGENTS.md / GEMINI.md, or wants project tracking set up or migrated — even when they never say "notes" or name this skill. Not for: releases and version bumps, commit messages, CHANGELOG entries, build or deploy status, issue trackers, or a spoken recap the user only wants to read.'
+description: 'The convention that decides WHERE a project keeps its working state, and why part of it must not load at startup. Four fixed files under docs/project/ — status (volatile, never imported), requirements, decisions, context (stable, imported) — plus a pointer written into every context file the repo has, so the notes are findable from Claude Code, Codex or Gemini alike. Use this whenever someone closes a working session or picks one up ("ya me voy, déjame anotado dónde quedé", "where did we leave off?"), asks where project notes should live or why they keep ending up scattered, wonders whether progress and dates belong inside CLAUDE.md / AGENTS.md / GEMINI.md, asks which assistant or model built a project and which one to go back to for a follow-up, or wants project tracking set up or migrated — even when they never say "notes" or name this skill. Not for: releases and version bumps, commit messages, CHANGELOG entries, build or deploy status, issue trackers, or a spoken recap the user only wants to read.'
 ---
 
 # Session Log
@@ -156,6 +156,39 @@ An acceptance criterion is the useful half. "Payments work" isn't checkable; "ch
 
 Proposal, requirements gathering, design — the work is real and it's exactly where people forget where they left off, but there's no diff to verify against. Adapt rather than skip: `requirements.md` and `decisions.md` carry the weight, `status.md` records what the client agreed and what's still open, and verification runs against the artifacts that do exist — a requirement that says "as agreed in the proposal" can be checked against the proposal. Don't create empty files waiting for a phase that hasn't arrived; `references/file-layout.md` covers how to size this down.
 
+## Which assistant did the work
+
+Months into a project a question comes up that none of the four files answers: what was this built with? It matters for a concrete reason — someone wants to reopen a piece of work by referring back to it, the way people refer to a conversation they had, and pick up a detail in the payments screen from last month. That only works in the tool that still holds the transcript.
+
+The intuition behind it is slightly wrong in a way that changes the answer, so it's worth being precise. The model remembers nothing between sessions; there is no continuity to return to. What exists is the **transcript, stored locally by the tool** — Codex keeps its own, Claude Code keeps its own, Gemini keeps its own, and none of them can read another's. So the thing worth recording is which tool was driving, with the model next to it, because the same tool behaves differently across models and the model is what you'd pick again.
+
+That belongs in `context.md`, and it earns a place in a startup-loaded file the same way the rest of that file does: it explains what the code doesn't say. A codebase whose scaffolding came from one assistant and whose auth rewrite came from another has two styles in it for a reason, and knowing that is the difference between "this is inconsistent" and "this had two authors".
+
+One row per **stretch of work**, never per session:
+
+| When | Assistant · model | What it produced |
+| --- | --- | --- |
+| 2026-06 | Codex · gpt-5.6-sol | Initial scaffolding, API layer |
+| 2026-08-17 | Claude Code · Opus 5 (`claude-opus-5`) | Auth rewrite, test suite |
+
+A row per session would grow without end and invalidate the cached prefix on every update — the one failure this convention exists to prevent. Add a row when a new assistant or model touches the project, or when one of them does something substantial enough that you'd want to return to it. Ten sessions of the same model on the same feature is one row whose date extends.
+
+`status.md` carries the volatile half: a `**Session by:**` line naming what wrote that note. It gets overwritten like the rest of the file, and `git log docs/project/status.md` then hands you the session-by-session history for free — which is why nothing has to accumulate anywhere.
+
+### Record what the environment tells you, not what you infer
+
+An assistant is a poor witness to its own identity. The tool name and the model are usually stated somewhere concrete — a line in the system prompt, a `--model` flag, a config file — and that is what to write down. **When you don't have it, name the tool and leave the model out**, or ask.
+
+An invented model id is worse than an absent one, because it reads as something that was checked. `gpt-5.6-sol` and `claude-opus-5` are exactly the kind of string that looks verified whether or not it is, and months later nobody can tell which. Write the commercial name and the id when you have both — commercial names get reused across versions, ids don't — and always the date, which is what makes a wrong guess recoverable.
+
+### If the continuation depends on a transcript, the record failed
+
+The table is a workaround, and mistaking it for the fix is the trap. Needing the original tool's transcript to continue means the reasoning behind that work exists only in a chat log: on one machine, inside one vendor's directory, unsearchable by anyone else and gone the day the project folder moves.
+
+That reasoning belongs in `decisions.md`, and the shape of the work in `context.md`. Do that and the table becomes a convenience — "this part came from Codex, which is why it's structured differently" — instead of the only way back in. A project any assistant can pick up is the goal; the table just says which one has the shortcut.
+
+Where each tool keeps its transcripts, and why Claude Code's are keyed to the project's absolute path — so moving the folder orphans them — is in `references/file-layout.md`.
+
 ## Which job this is
 
 Three jobs share this skill — install the convention, resume work, close a session — and the first has a variant worth catching before you write anything. Which one it is depends on the repo and on whether the person is arriving or leaving, not on how the request was phrased. Look before deciding:
@@ -220,7 +253,7 @@ Three more things belong in `status.md` and are routinely left out:
 - **What's blocked by someone else.** A client who hasn't sent the copy, a store review, a provider whose sandbox is down. These read like pending work but can't be unblocked by working, so mixing them into the technical list makes the list lie about what's actionable.
 - **Which phase the project is in** — proposal, requirements, design, build, testing, live. One line. It tells whoever arrives which of these files matters today.
 
-Update `requirements.md`, `decisions.md` or `context.md` only when something genuinely stable changed: scope moved, a choice was made, a new document appeared. Most sessions change nothing there, and that's normal.
+Update `requirements.md`, `decisions.md` or `context.md` only when something genuinely stable changed: scope moved, a choice was made, a new document appeared, a different assistant or model took over a stretch of the work. Most sessions change nothing there, and that's normal.
 
 **When `status.md` grows, the cause is usually stable content that drifted in.** The test is simple: would this text be the same next week? A test checklist, an acceptance walkthrough, a list of platform-specific gotchas — those don't change between sessions, so they belong in `requirements.md` or `context.md` even though you're using them right now. Being *currently relevant* is not the same as being *volatile*, and confusing the two is how the volatile file ends up carrying half the project.
 

package/skills/session-log/evals/evals.json

@@ -142,6 +142,38 @@
         "Does not create a docs/project/ inside apps/api or apps/web",
         "Pointer block written into the root AGENTS.md"
       ]
+    },
+    {
+      "id": 9,
+      "name": "which-assistant-built-this",
+      "prompt": "ya no me acuerdo con qué hice este proyecto. si quiero seguirle a la pantalla de pagos, a cuál le pido?",
+      "fixture": "gym-api-provenance",
+      "fixture_spec": "Laravel repo with docs/project/ installed. context.md has a Provenance section with two rows: 2026-06 Codex · gpt-5.6-sol (initial scaffolding, API layer) and 2026-08 Claude Code · Opus 5 (auth rewrite). The payments screen is not named in either row. status.md carries a Session by line naming Claude Code · Opus 5.",
+      "expected_output": "Answers from the provenance table, says which stretch each assistant produced, and is explicit that the payments screen is not attributed in the table rather than guessing — offering git log or the CHANGELOG as the way to narrow it.",
+      "assertions": [
+        "Answers from the provenance table in context.md rather than guessing",
+        "Does not attribute the payments screen to an assistant the table does not attribute it to",
+        "Suggests a checkable source (git log, commit authorship, CHANGELOG) for the part the table cannot answer",
+        "Does not claim that a model remembers the earlier work itself",
+        "Writes nothing — this is a read, not a session close"
+      ]
+    },
+    {
+      "id": 10,
+      "name": "first-session-by-a-new-assistant",
+      "prompt": "cierra la sesión. este proyecto lo empecé con Codex hace como dos meses y hoy fue la primera vez que le meto mano desde aquí",
+      "fixture": "tienda-app-no-provenance",
+      "fixture_spec": "Titanium/Alloy repo with docs/project/ installed and no Provenance section in context.md. Uncommitted work from today: two new controllers and a change to tiapp.xml. git log shows commits from two months ago authored with a Codex co-author trailer, then nothing until today.",
+      "expected_output": "Writes the handoff to status.md with a Session by line, and adds a Provenance section to context.md with a row for Codex (dated from the commit history) and a row for this session's assistant and model as reported by the environment.",
+      "assertions": [
+        "Adds a Provenance section to context.md with a row for the earlier Codex work and a row for this session",
+        "The date for the earlier row comes from the commit history rather than being invented",
+        "Names its own tool and model as the environment reports them, with no invented model id",
+        "status.md gains a Session by line naming the tool that wrote the note",
+        "Does not add one row per session or turn the table into a session log",
+        "The handoff itself still reflects the real uncommitted work (the two controllers and tiapp.xml)",
+        "Does not commit, tag or push"
+      ]
     }
   ]
 }

package/skills/session-log/references/file-layout.md

@@ -10,6 +10,7 @@ Read this when installing the convention in a project or migrating one that keep
 - [Two variants](#two-variants)
 - [Repos that come in pairs](#repos-that-come-in-pairs)
 - [Templates](#templates)
+- [Where each assistant keeps its transcripts](#where-each-assistant-keeps-its-transcripts)
 - [Migrating an existing project](#migrating-an-existing-project)
 - [Sizing](#sizing)
 
@@ -114,6 +115,8 @@ The only file that changes every session. Keep it short enough that someone actu
 # Status — <YYYY-MM-DD>
 
 **Phase:** <proposal · requirements · design · build · testing · live>
+**Session by:** <tool · model that wrote this note — drop the model if you
+                 can't confirm it from the environment>
 **Deployed:** <what's in production and since when — or "nothing yet">
 **Branch:** <branch, and whether it's pushed>
 **Sibling:** <other repo of this same project, and what it's waiting on — omit
@@ -146,7 +149,9 @@ The only file that changes every session. Keep it short enough that someone actu
 
 Absolute dates, never "yesterday" — the file outlives the session that wrote it.
 
-The three header lines exist because they're the questions asked first and answered worst. **Deployed is not the same as committed**: on a project that deploys by file sync, a change can be live and uncommitted, or committed and never uploaded. Write what you know and mark what you don't; a confident wrong answer here sends someone debugging the wrong copy of the code.
+The header lines exist because they're the questions asked first and answered worst. **Deployed is not the same as committed**: on a project that deploys by file sync, a change can be live and uncommitted, or committed and never uploaded. Write what you know and mark what you don't; a confident wrong answer here sends someone debugging the wrong copy of the code.
+
+**Session by** is overwritten every session, on purpose — `git log docs/project/status.md` is the session-by-session history, so nothing needs to pile up here. The lasting record of which assistant produced which stretch of the project is the provenance table in `context.md`.
 
 ### `docs/project/requirements.md`
 
@@ -254,10 +259,31 @@ How the project is put together, and what a newcomer would get wrong on day one.
 
 ## Traps
 - <The thing that cost someone a day, and how to avoid it.>
+
+## Provenance
+| When | Assistant · model | What it produced |
+| --- | --- | --- |
+| <YYYY-MM> | <tool · model, id in backticks if known> | <the stretch of work> |
 ```
 
 The map goes first because it's what someone new needs first: knowing what exists saves them from rewriting it. List every document you found, including the ones that turned out to be stale — marked as stale. A document omitted from the map is a document nobody will open again.
 
+**Provenance goes last** because it's the section consulted least often and the one that most easily turns into noise. One row per stretch of work, not per session: a row per session grows without bound inside an imported file, which is the cache problem this convention exists to avoid. Extend an existing row's date rather than adding a row for the same model doing more of the same thing.
+
+### Where each assistant keeps its transcripts
+
+The provenance table says which tool to go back to. This is where that tool's memory of the work actually sits — and none of them can read another's, which is the whole reason the table is worth keeping.
+
+| Tool | Transcripts |
+| --- | --- |
+| Claude Code | `~/.claude/projects/<absolute-path-with-slashes-as-dashes>/` |
+| Codex | `~/.codex/sessions/<year>/…`, older ones under `~/.codex/archived_sessions/` |
+| Gemini CLI | under `~/.gemini/` |
+
+Check the layout on the machine instead of trusting this table. These are vendor-internal directories, they get reorganized without notice, and a confidently wrong path here sends someone hunting for a history that is sitting somewhere else.
+
+Claude Code's key is the project's **absolute path**, with `/` replaced by `-`. Rename or move the project folder and the slug changes: the old transcripts stay on disk, unreachable, and the project starts again with no history. That is a good reason not to let a chat log be the only record of a decision — and the reason the four files live inside the repo, where they travel with it.
+
 ## Migrating an existing project
 
 Projects that already keep notes somewhere — `.claude/memory/`, a roadmap under `docs/`, a planning doc — get migrated rather than duplicated. Two locations is the problem this convention exists to solve.