@victortomaili/skill-cli 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -11,6 +11,17 @@ 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.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

@@ -197,8 +197,12 @@ default; `space` toggles the per-project override.
 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.
+> 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.
 
 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.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/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
@@ -23,10 +24,20 @@ 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).
 
+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.
+
 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))
+}