@victortomaili/skill-cli 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -11,6 +11,30 @@ 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.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
+- AGENTS.md bootstrap block now instructs the agent to (a) **discover & load relevant skills per message** (skills are not in context until loaded — match the message to a skill's triggers/topic, then `skill cat`), and (b) **propose — don't auto-apply — context-altering skills** (those that change HOW the agent responds, e.g. an output-style/mode skill): apply only after the user confirms (an explicit `/X` counts as confirmation).
+
+### Changed
+- Manager + `skill list`: clearer activation UI. New **`source`** column shows *why* a skill is/isn't active in the current project — `global` (inherited default), `global·off` (default but denied here), `project` (project allow only), `—` (passive). The label is derived from `active` + `isDefault`, so it can never disagree with the ●/○ marker. The manager now also prints the project path + counts (`installed · active here · global defaults`) and an explicit legend; the `space` (per-project) vs `a` (global default) keys are labelled distinctly.
+
+### Fixed
+- `source` label: a global-default skill that is **also** explicitly enabled in the current project now shows `project` (the more-specific source), with ★ still marking its default membership. Previously `isDefault && active` short-circuited to `global`.
+
 ## [0.4.0] - 2026-07-07
 
 ### Changed (breaking — config format)

package/README.md

@@ -196,9 +196,13 @@ 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>`.
-> When the user types `/X`, run `skill trigger X`. Single match → apply the output;
-> multiple → show candidates; load each skill only once per session.
+> **START GATE:** on the first user message, your VERY FIRST action — BEFORE
+> ANYTHING ELSE (before thinking, before any tool call) — is `skill defaults` +
+> `skill cat <name>` for each, then `skill list`. Then each
+> message, discover/load relevant skills (`skill cat` / `skill trigger`), once each.
+> A **context-altering** skill (changes HOW you respond — style/mode) is
+> **PROPOSE-ONLY**: propose it, then apply only after the user confirms
+> (`active` ≠ applied; an explicit `/X` counts). `/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.4.0",
+  "version": "0.5.1",
   "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/list.js

@@ -1,7 +1,7 @@
 import c from 'picocolors'
 import { listStore } from '../lib/store.js'
 import { readGlobalConfig, readProjectConfig, computeEffective, computeDefaults } from '../lib/config.js'
-import { trunc } from '../lib/format.js'
+import { trunc, sourceLabel } from '../lib/format.js'
 
 export function cmdList(_args = []) {
   const installed = listStore()
@@ -22,19 +22,17 @@ export function cmdList(_args = []) {
   for (const s of installed) {
     const active = effective.includes(s.name)
     const mark = active ? c.green('●') : c.gray('○')
-    const star = defaults.includes(s.name) ? c.yellow('★') : c.gray('·')
-    const sc = labelScope(s.name, globalCfg, projCfg)
+    const isDef = defaults.includes(s.name)
+    const isProjAllow = projCfg && (projCfg.allow || []).some(a => a.toLowerCase() === s.name.toLowerCase())
+    const star = isDef ? c.yellow('★') : c.gray('·')
+    const sc = sourceLabel(c, active, isDef, isProjAllow)
     const trg = s.triggers.length ? '  ' + c.gray('/' + s.triggers.join(', /')) : ''
     console.log(`  ${mark} ${star} ${c.bold(s.name.padEnd(22))} ${c.gray(String(s.version).padEnd(8))} ${sc}${trg}`)
     if (s.description) console.log(c.gray('      ' + trunc(s.description, 68)))
   }
   console.log()
-  console.log(c.green('● active   ') + c.gray('○ passive   ') + c.yellow('★ default (auto-load on session start)'))
+  console.log(c.green('●') + c.gray(' active here   ') + c.gray('○ passive   ') + c.yellow('★') + c.gray(' global default'))
+  console.log(c.gray('  source: global = inherited default · project = on here only · global·off = default off here'))
   console.log(c.cyan('Details: ') + 'skill show <name>   ' + c.cyan('Load: ') + 'skill cat <name>')
 }
 
-function labelScope(name, globalCfg, projCfg) {
-  if (projCfg && (projCfg.allow || []).some(a => a.toLowerCase() === name.toLowerCase())) return c.magenta('project')
-  if ((globalCfg.defaults || []).some(a => a.toLowerCase() === name.toLowerCase())) return c.blue('global ')
-  return c.gray('-      ')
-}

package/src/commands/manager.js

@@ -6,16 +6,9 @@ import { STORE_DIR } from '../lib/paths.js'
 import { listStore } from '../lib/store.js'
 import { readGlobalConfig, writeGlobalConfig, readProjectConfig, writeProjectConfig, computeEffective, computeDefaults } from '../lib/config.js'
 import { cleanConfig } from './remove.js'
-import { trunc } from '../lib/format.js'
+import { trunc, sourceLabel } from '../lib/format.js'
 
-const KEYS = c.gray('↑↓ move · space toggle · a default · d delete · enter view · q/esc quit')
-
-// where a skill's activation currently comes from (mirrors `skill list`)
-function labelScope(name, g, p) {
-  if (p && (p.allow || []).some(a => a.toLowerCase() === name.toLowerCase())) return c.magenta('project')
-  if ((g.defaults || []).some(a => a.toLowerCase() === name.toLowerCase())) return c.blue('global ')
-  return c.gray('-      ')
-}
+const KEYS = c.gray('↑↓ move · space toggle here · a global default · d delete · enter view · q/esc quit')
 
 // Pure decision: given the current configs, compute the new {allow, deny} arrays
 // that flip `name`'s active state in THIS project. No I/O → unit-testable without
@@ -147,21 +140,29 @@ const managerPrompt = createPrompt((_config, done) => {
   if (mode === 'view' && s) {
     return prefix + ' ' + c.bold(s.name) + c.gray('  (any key to go back)') + '\n' + viewBody(s)
   }
-  const lines = [prefix + ' ' + c.bold('skill manager') + c.gray(' — ' + installed.length + ' installed · ' + eff.length + ' active')]
+  const lines = [
+    prefix + ' ' + c.bold('skill manager') + c.gray(' — project: ') + c.magenta(process.cwd()),
+    c.gray('  ' + installed.length + ' installed · ' + eff.length + ' active here · ' + defs.length + ' global default' + (defs.length === 1 ? '' : 's')),
+    '',
+  ]
   for (let i = 0; i < installed.length; i++) {
     const sk = installed[i]
     const active = eff.includes(sk.name)
+    const isDef = defs.includes(sk.name)
+    const isProjAllow = p && (p.allow || []).some(a => a.toLowerCase() === sk.name.toLowerCase())
     const arrow = i === cur ? c.cyan('❯') : ' '
     const mark = active ? c.green('●') : c.gray('○')
-    const star = defs.includes(sk.name) ? c.yellow('★') : c.gray('·')
-    const sc = labelScope(sk.name, g, p)
+    const star = isDef ? c.yellow('★') : c.gray('·')
+    const src = sourceLabel(c, active, isDef, isProjAllow)
     const trg = sk.triggers.length ? '  ' + c.gray('/' + sk.triggers.join(', /')) : ''
-    const nameStr = sk.name.padEnd(24)
+    const nameStr = sk.name.padEnd(22)
     const nameCol = i === cur ? c.bold(nameStr) : nameStr
-    lines.push(`${arrow} ${mark} ${star} ${nameCol} ${c.gray(String(sk.version || '').padEnd(8))} ${sc}${trg}`)
-    if (i === cur && sk.description) lines.push(c.gray('      ' + trunc(sk.description, 62)))
+    lines.push(`${arrow} ${mark} ${star} ${nameCol} ${c.gray(String(sk.version || '').padEnd(7))} ${src}${trg}`)
+    if (i === cur && sk.description) lines.push(c.gray('      ' + trunc(sk.description, 60)))
   }
-  lines.push(c.gray('  ' + '─'.repeat(58)))
+  lines.push(c.gray('  ' + '─'.repeat(62)))
+  lines.push('  ' + c.green('●') + c.gray(' active here   ') + c.gray('○ passive   ') + c.yellow('★') + c.gray(' global default   ') + c.gray('· not default'))
+  lines.push(c.gray('  source: global = inherited default · project = on here only · global·off = default off here'))
   lines.push('  ' + KEYS)
   if (mode === 'confirm') {
     lines.push('')

package/src/lib/agents-md.js

@@ -6,7 +6,8 @@ const BEGIN = '<!-- BEGIN skill-cli -->'
 const END = '<!-- END skill-cli -->'
 
 // Global instruction block — injected into each agent's global instruction file.
-// Kept short (~140 words) so it doesn't bloat agent context on every session.
+// Covers usage, defaults (auto-load), per-message discovery, and the
+// propose-then-confirm rule for context-altering skills.
 export const AGENTS_BLOCK = `## skill-cli
 
 This machine uses the \`skill\` command to manage skills (instruction / workflow
@@ -15,18 +16,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\` then
+\`skill cat <name>\` for each result, then \`skill list\` to learn every skill's
+triggers. Do this even if the task looks trivial: skills shape how you should
+approach the task, so you cannot reason about it correctly until they are loaded.
+
+Discovery (mandatory, every message): On EVERY user message, decide whether a
+skill is relevant by matching the message against the trigger catalog from
+\`skill list\`. If a relevant skill is not yet loaded, load it with \`skill cat
+<name>\` (or \`skill trigger <keyword>\` to resolve a keyword). Load each skill only
+ONCE per session. When you load or re-read ANY skill mid-session, immediately
+re-evaluate the current message and load/propose any newly-relevant skill.
+
+Context-altering skills (HARD RULE): 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. These are PROPOSE-ONLY. You MUST propose
+such a skill and apply it ONLY after the user confirms; an explicit \`/X\` trigger
+counts as confirmation. \`active\` / \u2605-default means AVAILABLE, not APPLIED —
+propose \u2260 auto-apply. This rule overrides any other skill's "always use" rule for
+context-altering skills.
 
 Triggers: when the user types \`/X\`, run \`skill trigger X\`.
 - Single match → apply the output directly.
 - Multiple matches → show the candidate list; load the right one with \`skill cat <name>\`.
-- Load each skill only ONCE per session (avoid re-injecting).
 `
 
 export function injectBlock(content) {

package/src/lib/format.js

@@ -10,3 +10,17 @@ export function trunc(s, n) {
 export function pad(s, n = 22) {
   return (String(s) + ' '.repeat(n)).slice(0, n)
 }
+
+// WHY a skill is (or isn't) active in THIS project — source of activation.
+// `hasProjectAllow` WINS: a skill explicitly enabled in this project shows
+// `project` even when it's ALSO a global default (★ stays — it's a separate col).
+//   project    = explicitly enabled in this project's allow-list (★ stays if default)
+//   global     = inherited global default, active here
+//   global·off = global default, but this project denies it (passive here)
+//   —          = passive
+export function sourceLabel(c, active, isDefault, hasProjectAllow) {
+  if (hasProjectAllow) return c.magenta('project'.padEnd(10))
+  if (isDefault && active) return c.blue('global'.padEnd(10))
+  if (isDefault) return c.gray('global·off'.padEnd(10))
+  return c.gray('—'.padEnd(10))
+}