@victortomaili/skill-cli 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -11,6 +11,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Cursor adapter (`.cursor/rules` format) for `init -g` bootstrap.
 - Per-agent hook adapters for automatic `/X` triggering (push model).
 
+## [0.6.0] - 2026-07-07
+
+### Changed
+- **`skill defaults` is now a description-only catalog.** It lists EVERY installed
+  skill (name + full description + triggers; ★ marks defaults) — never the skill
+  body. The agent reads the catalog and decides per skill: functional for the task
+  → `skill cat <name>`; context-altering (changes HOW the agent responds) → propose
+  and wait for the user's confirmation. This follows the existing SKILL.md standard
+  — no extra frontmatter field is required or expected on any skill.
+- **Context-altering detection is the agent's judgment, from the description.** Any
+  skill can be context-altering (including ones installed later); the agent decides
+  from the description text, with no hardcoded list. (`skill cat` is unchanged — it
+  still loads a full skill on demand.)
+
+### Added
+- AGENTS.md START GATE now enforces **"LOADED ≠ LISTED"**: a skill is loaded only
+  if the agent ran `skill cat <name>` for it this session — listing/cataloging a
+  skill (or its ★ / `active` status) is not loading.
+
+## [0.5.1] - 2026-07-07
+
+### Fixed
+- AGENTS.md bootstrap block hardened into hard rules after a live pi-agent test
+  surfaced two gaps. **(a) START GATE:** on the first user message, the agent's
+  VERY FIRST action — BEFORE ANYTHING ELSE (before thinking, before any tool call)
+  — MUST be `skill defaults` + `skill cat <name>` for each, then `skill list`
+  (discovery is mandatory, not optional). **(b) Context-altering = PROPOSE-ONLY:**
+  `active` / ★-default means *available*, not *applied* — propose ≠ auto-apply,
+  and the rule overrides any other skill's "always use" instruction. Also:
+  whenever a skill is loaded mid-session, re-evaluate the message and load/propose
+  any newly-relevant one.
+
 ## [0.5.0] - 2026-07-07
 
 ### Added

package/README.md

@@ -196,13 +196,16 @@ default; `space` toggles the per-project override.
 `skill init -g` injects a short, idempotent block into each detected agent's global
 instruction file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`):
 
-> On session start, run `skill defaults` and load each with `skill cat <name>`.
-> Skills are NOT in context until you load them — each message, decide whether one
-> is relevant and load it (`skill cat <name>` / `skill trigger <keyword>`); load each
-> only once. A skill that changes HOW you respond (output style/mode) is PROPOSED,
-> not auto-applied — apply only after the user confirms (an explicit `/X` counts).
-> When the user types `/X`, run `skill trigger X` — single match → apply; multiple →
-> show candidates.
+> **START GATE:** on the first user message, your VERY FIRST action — BEFORE
+> ANYTHING ELSE (before thinking, before any tool call) — is `skill defaults`, the
+> skill **catalog** (every skill's name + full description; never the body). Read
+> it and decide per skill from its description: **functional** for the task → load
+> it (`skill cat <name>`); **context-altering** (changes HOW you respond —
+> style/mode) → **propose**, apply only after the user confirms (`/X` = confirm).
+> **LOADED ≠ LISTED**: a skill is loaded only if you `cat`-ed it this session —
+> listing it (or its ★ / `active` status) is not loading. Any skill can be
+> context-altering; the agent judges from the description (no flag, no fixed list).
+> `/X` → `skill trigger X`.
 
 It's wrapped in `<!-- BEGIN skill-cli --> … <!-- END skill-cli -->` markers, never
 duplicates, and preserves your existing file content. Re-run `init -g` any time —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@victortomaili/skill-cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Cross-agent skill manager — one global store, clean agent folders, activation via skill.config",
   "license": "MIT",
   "author": "Victor Tomaili <victor@tomaili.com>",

package/src/commands/defaults.js

@@ -1,7 +1,6 @@
 import c from 'picocolors'
 import { listStore } from '../lib/store.js'
-import { readGlobalConfig, writeGlobalConfig, computeDefaults } from '../lib/config.js'
-import { trunc } from '../lib/format.js'
+import { readGlobalConfig, writeGlobalConfig } from '../lib/config.js'
 
 // `skill defaults` — list the skills marked as defaults. In the unified model a
 // default skill is BOTH active-by-default in every project AND auto-loaded on
@@ -11,24 +10,31 @@ import { trunc } from '../lib/format.js'
 export function cmdDefaults() {
   const installed = listStore()
   const globalCfg = readGlobalConfig()
-  const eff = computeDefaults(installed, globalCfg)
+  const defs = new Set((globalCfg.defaults || []).map(d => String(d).toLowerCase()))
 
-  console.log(c.bold('skill defaults') + c.gray(' — active by default + auto-load on session start (global)'))
+  console.log(c.bold('skill defaults') + c.gray(' — skill catalog (descriptions only; the agent decides: functional → `skill cat`, context-altering → propose)'))
   console.log()
 
-  if (eff.length === 0) {
-    console.log(c.gray('  No default skills yet. Mark with: ') + c.cyan('skill default <name>'))
+  if (installed.length === 0) {
+    console.log(c.gray('  No skills installed. Install with: ') + c.cyan('skill install <source>'))
     return
   }
 
-  for (const name of eff) {
-    const s = installed.find(x => x.name === name)
-    const trg = s && s.triggers.length ? '  ' + c.gray('/' + s.triggers.join(', /')) : ''
-    console.log(`  ${c.yellow('★')} ${c.bold(name.padEnd(22))}${trg}`)
-    if (s && s.description) console.log(c.gray('      ' + trunc(s.description, 66)))
+  // CATALOG, not a loader: print every installed skill's name + FULL description
+  // (collapsed to one line) + triggers. Never dump the skill body here — the
+  // agent reads descriptions, then itself decides per skill: load (skill cat) if
+  // it's functional for the task, or PROPOSE if it's context-altering (changes
+  // HOW the agent responds). Detection is the agent's judgment from the
+  // description, so it works for any skill — including ones loaded later — with
+  // no hardcoded list or flag.
+  for (const s of installed) {
+    const star = defs.has(s.name.toLowerCase()) ? c.yellow('★') + ' ' : '  '
+    const trg = s.triggers.length ? '  ' + c.gray('/' + s.triggers.join(', /')) : ''
+    console.log(`  ${star}${c.bold(s.name)}${trg}`)
+    if (s.description) console.log(c.gray('      ' + String(s.description).replace(/[\r\n]+/g, ' ').trim()))
   }
   console.log()
-  console.log(c.gray('Load each into context: ') + c.cyan('skill cat <name>'))
+  console.log(c.yellow('★') + c.gray(' = default (active by default). Load a skill: ') + c.cyan('skill cat <name>'))
 }
 
 // `skill default <name>` — mark a skill as a default (active by default in every

package/src/lib/agents-md.js

@@ -6,8 +6,10 @@ const BEGIN = '<!-- BEGIN skill-cli -->'
 const END = '<!-- END skill-cli -->'
 
 // Global instruction block — injected into each agent's global instruction file.
-// Covers usage, defaults (auto-load), per-message discovery, and the
-// propose-then-confirm rule for context-altering skills.
+// `skill defaults` is a description-only CATALOG; the agent reads it, then itself
+// decides per skill: functional → `skill cat`, context-altering → propose. No flag
+// or fixed list — detection is the agent's judgment from the description, so it
+// covers any skill (including ones installed later).
 export const AGENTS_BLOCK = `## skill-cli
 
 This machine uses the \`skill\` command to manage skills (instruction / workflow
@@ -16,24 +18,36 @@ NOT copied into agent directories (\`~/.claude\`, \`~/.codex\`, etc.) — so the
 won't appear here.
 
 Usage:
-- \`skill list\` — skills installed and active in the current project
+- \`skill list\` — skills installed + active in the current project (with triggers)
 - \`skill show <name>\` — skill summary (path, triggers, version)
 - \`skill cat <name>\` — load skill content into context
+- \`skill default <name>\` — mark a skill as a global default (active + auto-load)
 
-Defaults: on session start, run \`skill defaults\` to list skills marked as
-defaults (active by default + auto-load), then \`skill cat <name>\` for each. Mark
-your own with \`skill default <name>\` (global — active in every project).
+START GATE (mandatory): On the FIRST user message of a session, your VERY FIRST
+action — BEFORE ANYTHING ELSE: before you start thinking/reasoning about the task
+and before any tool call — MUST be to run \`skill defaults\`. It prints the skill
+CATALOG — every installed skill's name + FULL description (NOT the skill body).
+Read it, then for EACH skill decide FROM ITS DESCRIPTION:
+- Functional / useful for THIS task → load it: \`skill cat <name>\`.
+- Changes HOW you respond (a style, tone, format, or persistent MODE — e.g. a
+  brevity/compression style) → it is CONTEXT-ALTERING: PROPOSE it to the user and
+  apply ONLY after they confirm (\`/X\` = confirm). Do NOT load/apply it yourself.
+LOADED ≠ LISTED. A skill is loaded ONLY if you have run \`skill cat <name>\` for
+it THIS session. Seeing a skill in \`skill defaults\` / \`skill list\` does NOT load
+it — you then know only its name + description, nothing more. Never infer a skill
+is in your context from its name, the \u2605 marker, or an \`active\` status: if you
+haven't catted it, treat it as NOT loaded (then decide: cat it, or propose it).
+Do not assume a skill is already applied — \`active\`/\u2605-default = AVAILABLE, not
+APPLIED. ANY skill can be context-altering; judge from the description — there is
+no fixed list and no flag. Do this even if the task looks trivial: skills shape
+how you approach it, so you cannot reason about it correctly until you've reviewed
+them.
 
-Discovery: skills are NOT used unless you load them — never assume a skill is
-already in context. On each user message, decide whether a skill is relevant to
-the task (match the message against a skill's triggers/topic); if one is relevant
-AND not yet loaded, load it with \`skill cat <name>\` (or \`skill trigger <keyword>\`
-to resolve a keyword to a skill). Load each skill only ONCE per session.
-
-Context-altering skills: some skills change HOW you respond — output style, tone,
-format, or a persistent mode (e.g. a terseness/compression style) — rather than
-just adding task knowledge. Do NOT auto-apply these. PROPOSE the skill and apply
-it only after the user confirms; an explicit \`/X\` trigger counts as confirmation.
+Discovery (every message): On EVERY later user message, re-check the catalog
+against the new request; load any newly-relevant functional skill
+(\`skill cat <name>\`), and PROPOSE any newly-relevant context-altering one.
+Load each skill only ONCE per session (\`skill trigger <keyword>\` resolves a
+keyword to a skill).
 
 Triggers: when the user types \`/X\`, run \`skill trigger X\`.
 - Single match → apply the output directly.