@victortomaili/skill-cli 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -11,6 +11,29 @@ 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)
+- **Unified the "default" and "enabled" concepts into ONE global list.** Previously there were two independent global lists — `enabled_global` (skills active by default in every project) and `defaults_global` (skills auto-loaded on session start, independent of active state). Now there is a single `defaults` list in `config.yaml`: a default skill is BOTH active by default in every project AND auto-loaded on session start. This dissolves the confusion where the manager used a hidden `deny` to turn off a global skill — a default is simply the active-by-default set, and a project refines it with `allow` / `deny`.
+  - `skill default <name>` is now always GLOBAL (the `-g` flag is accepted but a no-op). `skill enable -g <name>` and `skill default <name>` now do the same thing; `skill disable -g` / `skill undefault` remove it.
+  - The per-project `defaults:` key in `skill.config` is removed — defaults are a global concept only. A project refines the active set with `allow` / `deny` / `inherit` (see Activation).
+  - **Automatic migration:** a legacy `config.yaml` with `enabled_global:` and/or `defaults_global:` is folded into `defaults:` (the union of both, deduped) on the next write. No manual steps.
+- AGENTS.md bootstrap block: the "Defaults" line now describes the unified model (active by default + auto-load, global).
+
+### Added
+- `skill init -g` now bootstraps **pi** too — the AGENTS.md block is injected into `~/.pi/agent/AGENTS.md` (pi's global context file). Claude Code, Codex, Gemini, and pi are now all bootstrapped on a single re-run.
+
 ## [0.3.0] - 2026-07-07
 
 ### Added

package/README.md

@@ -19,7 +19,7 @@ config file.
 - 🔌 **Universal sources** — `owner/repo`, GitHub/GitLab URL, git URL, local path, npm package (via `npx skills`).
 - ⚡ **Pull-based** — agents pull skill content into context on demand via `skill trigger /X`. No hooks required.
 - 🔍 **Interactive TUIs** — `skill search` to discover & multi-install from the skills registry; `skill` (no args) to manage every installed skill with the keyboard. TTY-only; agents & CI stay non-interactive.
-- ⭐ **Default skills** — mark skills to auto-load on every agent session start.
+- ⭐ **Default skills** — one global list: active by default in every project AND auto-loaded on session start.
 - 🖥️ **Cross-platform** — Windows, macOS, Linux (handles the Windows `npx` spawn quirk for you).
 - 🧪 **Well tested** — 225 unit + CLI tests, network-free by default.
 
@@ -58,12 +58,13 @@ That's it. Your agent now knows: *when the user types `/X`, run `skill trigger X
 ```
 ~/.skill-cli/
   store/<skill>/SKILL.md     ← one canonical store (skills live here)
-  config.yaml                ← global config (enabled_global, defaults_global)
+  config.yaml                ← global defaults (active by default + auto-load)
 
-<project>/skill.config       ← per-project activation + defaults (inherit / deny / allow / defaults)
+<project>/skill.config       ← per-project overrides (inherit / deny / allow)
 ~/.claude/CLAUDE.md          ← bootstrap block injected by `skill init -g`
 ~/.codex/AGENTS.md             (idempotent — preserves your existing content)
 ~/.gemini/GEMINI.md
+~/.pi/agent/AGENTS.md
 ```
 
 Agents don't read `skill.config` directly — the CLI does. The agent only needs the
@@ -78,10 +79,10 @@ short bootstrap block telling it to run `skill` on `/X`.
 | `skill install <source>` | Fetch skill(s) to the store (agent dirs untouched) |
 | `skill search` | Interactive search & multi-install from the skills registry (TTY) |
 | `skill` / `skill manager` | Interactive manager: toggle, default, delete, view (TTY) |
-| `skill enable <name> [-g]` | Enable in project, or globally with `-g` |
-| `skill disable <name> [-g]` | Disable |
-| `skill default <name> [-g]` | Mark a skill to auto-load on session start |
-| `skill undefault <name> [-g]` | Remove the auto-load flag |
+| `skill enable <name> [-g]` | Allow in project, or global default with `-g` |
+| `skill disable <name> [-g]` | Deny in project, or remove global default with `-g` |
+| `skill default <name>` | Mark a default skill (global: active + auto-load) |
+| `skill undefault <name>` | Remove the default flag |
 | `skill defaults` | List default skills (the command your agent runs on start) |
 | `skill list` | Show installed + active skills (cwd-aware, ★ = default) |
 | `skill show <name>` | Skill metadata (path, triggers, version) |
@@ -129,23 +130,26 @@ for a minimal, copy-paste template.
 
 ## Activation
 
-Three layers, most-specific wins:
+One global concept, refined per project:
 
 1. **installed** — present in the store (passive)
-2. **enabled globally** — listed in `config.yaml`; active by default in every project
-3. **enabled per project** — in the project's `skill.config` `allow` list
+2. **default (global)** — listed in `config.yaml` `defaults:`; **active by default in every project** and **auto-loaded on agent session start**. Mark one with `skill default <name>` (or `skill enable -g`).
+3. **per-project override** — a project's `skill.config` refines the set:
+   - `allow` — activate an otherwise-passive skill **in this project only**
+   - `deny` — turn off a default skill **in this project only**
+   - `inherit: false` — ignore global defaults entirely (only `allow` applies)
 
-A project `skill.config` overrides the global set. Pure allowlist mode:
+A project with **no `skill.config`** inherits the global defaults (all active). Pure
+allowlist mode in a single project:
 
 ```yaml
 # <project>/skill.config
-inherit: true
-deny: ["*"]                    # block every globally-enabled skill in this project
-allow: [react-best-practices]  # then open them one by one
+inherit: false                 # ignore global defaults in this project
+allow: [react-best-practices]  # only this skill is active here
 ```
 
-> `allow` always wins over `deny`, so `deny: ["*"]` + `allow: [X]` = "only X".
-> Matching is case-insensitive throughout.
+> `allow` always wins over `deny`, so with `inherit: true` you can also write
+> `deny: ["*"]` + `allow: [X]` = "only X here". Matching is case-insensitive throughout.
 
 ## Interactive mode (terminal only)
 
@@ -160,7 +164,7 @@ Opens a full-screen manager over your store:
 |---|---|
 | `↑` / `↓` | move |
 | `space` | toggle active in the current project |
-| `a` | toggle the default (auto-load) flag |
+| `a` | toggle the global default (active + auto-load) |
 | `d` | delete (asks `y/N`) |
 | `enter` | view the `SKILL.md` |
 | `q` / `esc` | quit |
@@ -172,15 +176,20 @@ Type a query → browse live results from the [skills registry](https://skills.s
 → loops back so you can search again. `esc` or an empty query quits. `skill install`
 with no source also opens it.
 
-## Default skills (auto-load)
+## Default skills
 
-A "default" is a skill your agent loads automatically on every session start.
-It's a flag **independent** of enable/disable (a skill can be a default without
-being active). Mark one with `skill default <name>` (or `-g` for every project),
-list them with `skill defaults`. The AGENTS.md bootstrap block tells your agent to
-run `skill defaults` then `skill cat <name>` for each.
+A **default** is a skill that is **active by default in every project** AND
+**auto-loaded on agent session start** — one unified global list in `config.yaml`
+(`defaults:`). Mark one with `skill default <name>`, remove with
+`skill undefault <name>`, list them with `skill defaults`. The AGENTS.md bootstrap
+block tells your agent to run `skill defaults` on start, then `skill cat <name>`
+for each.
 
-Defaults live in `skill.config` (`defaults:`) and `config.yaml` (`defaults_global:`).
+Defaults are a **global** concept (never per-project). A project can still turn a
+default off locally with `skill disable <name>` (a project `deny`), or activate a
+non-default locally with `skill enable <name>` (a project `allow`) — see
+[Activation](#activation). In the interactive manager, `a` toggles the global
+default; `space` toggles the per-project override.
 
 ## Bootstrap
 
@@ -188,14 +197,18 @@ Defaults live in `skill.config` (`defaults:`) and `config.yaml` (`defaults_globa
 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 —
 it reports `already set up` and rewrites nothing.
 
-**Supported agents:** Claude Code, Codex, Gemini. (Cursor uses `.cursor/rules` with
+**Supported agents:** Claude Code, Codex, Gemini, and pi. (Cursor uses `.cursor/rules` with
 a different format — adapter planned. See [issue tracker](https://github.com/victortomaili/skill-cli/issues).)
 
 ## Cross-platform

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@victortomaili/skill-cli",
-  "version": "0.3.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/cli.js

@@ -30,14 +30,14 @@ ${c.bold('Acquire skills')}
   ${c.cyan('skill search')}                  interactive search & multi-install (TTY only)
 
 ${c.bold('Activation')}
-  ${c.cyan('skill enable')} ${c.gray('<name> [-g]')}  enable in project, or globally (-g)
-  ${c.cyan('skill disable')} ${c.gray('<name> [-g]')} disable
+  ${c.cyan('skill enable')} ${c.gray('<name> [-g]')}  allow in project, or global default (-g)
+  ${c.cyan('skill disable')} ${c.gray('<name> [-g]')} deny in project, or remove global default (-g)
   ${c.cyan('skill list')}                  installed + active skills (cwd-aware)
 
-${c.bold('Defaults (auto-load)')}
-  ${c.cyan('skill default')} ${c.gray('<name> [-g]')} mark a skill for auto-load on session start
-  ${c.cyan('skill undefault')} ${c.gray('<name> [-g]')} remove the default flag
-  ${c.cyan('skill defaults')}                 list default skills (agent runs this on start)
+${c.bold('Defaults (active + auto-load)')}
+  ${c.cyan('skill default')} ${c.gray('<name>')}    mark a default skill (global: active in every project)
+  ${c.cyan('skill undefault')} ${c.gray('<name>')}  remove the default flag
+  ${c.cyan('skill defaults')}                  list default skills (agent runs this on start)
 
 ${c.bold('Usage (agent)')}
   ${c.cyan('skill show')} ${c.gray('<name>')}         metadata + path + triggers

package/src/commands/defaults.js

@@ -1,19 +1,19 @@
 import c from 'picocolors'
 import { listStore } from '../lib/store.js'
-import { readGlobalConfig, writeGlobalConfig, readProjectConfig, writeProjectConfig, computeDefaults } from '../lib/config.js'
+import { readGlobalConfig, writeGlobalConfig, computeDefaults } from '../lib/config.js'
 import { trunc } from '../lib/format.js'
 
-// `skill defaults` — list the skills marked as defaults (auto-loaded on agent
-// session start). This is the agent-facing command the AGENTS.md block tells the
-// agent to run, then `skill cat <name>` for each. cwd-aware (global + project).
+// `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
+// agent session start (one global `defaults` list). This is the agent-facing
+// command the AGENTS.md block tells the agent to run, then `skill cat <name>`
+// for each. Defaults are a GLOBAL concept (never per-folder).
 export function cmdDefaults() {
   const installed = listStore()
   const globalCfg = readGlobalConfig()
-  const projCfg = readProjectConfig()
-  const eff = computeDefaults(installed, globalCfg, projCfg)
+  const eff = computeDefaults(installed, globalCfg)
 
-  const scope = projCfg ? c.magenta(process.cwd()) : c.gray('(global)')
-  console.log(c.bold('skill defaults') + c.gray(' — auto-load on session start · project: ') + scope)
+  console.log(c.bold('skill defaults') + c.gray(' — active by default + auto-load on session start (global)'))
   console.log()
 
   if (eff.length === 0) {
@@ -31,14 +31,15 @@ export function cmdDefaults() {
   console.log(c.gray('Load each into context: ') + c.cyan('skill cat <name>'))
 }
 
-// `skill default <name> [-g]` — mark a skill as a default (auto-load). Requires
-// the skill to be installed (a typo would silently "succeed" but never resolve).
+// `skill default <name>` — mark a skill as a default (active by default in every
+// project + auto-loaded on session start). Always GLOBAL. Requires the skill to
+// be installed (a typo would silently "succeed" but never resolve). `-g`/`--global`
+// is accepted for compatibility but is a no-op — defaults are inherently global.
 export function cmdDefault(args) {
-  const global = args.includes('-g') || args.includes('--global')
   const name = args.find(a => !a.startsWith('-'))
   if (!name) {
-    console.error(c.red('Usage: skill default <name> [-g]'))
-    console.error(c.gray('  Marks a skill as a default (auto-loaded on agent session start).'))
+    console.error(c.red('Usage: skill default <name>'))
+    console.error(c.gray('  Marks a skill as a default: active by default in every project + auto-load on session start.'))
     process.exit(1)
   }
   if (!listStore().some(s => s.name.toLowerCase() === name.toLowerCase())) {
@@ -46,47 +47,27 @@ export function cmdDefault(args) {
     console.error(c.gray('  Install first: skill install <source>'))
     process.exit(1)
   }
-  if (global) {
-    const cfg = readGlobalConfig()
-    if (!(cfg.defaults_global || []).some(d => d.toLowerCase() === name.toLowerCase())) {
-      cfg.defaults_global.push(name.toLowerCase())
-      cfg.defaults_global.sort()
-    }
-    writeGlobalConfig(cfg)
-    console.log(c.green('✓') + ' default globally: ' + c.bold(name) + c.gray('  (auto-load in every project)'))
-  } else {
-    const cwd = process.cwd()
-    const cfg = readProjectConfig(cwd) || { inherit: true, deny: [], allow: [], defaults: [] }
-    if (!(cfg.defaults || []).some(d => d.toLowerCase() === name.toLowerCase())) cfg.defaults.push(name.toLowerCase())
-    writeProjectConfig(cwd, cfg)
-    console.log(c.green('✓') + ' default in project: ' + c.bold(name) + c.gray('  (' + cwd + ')'))
+  const cfg = readGlobalConfig()
+  if (!(cfg.defaults || []).some(d => d.toLowerCase() === name.toLowerCase())) {
+    cfg.defaults.push(name.toLowerCase())
+    cfg.defaults.sort()
   }
+  writeGlobalConfig(cfg)
+  console.log(c.green('✓') + ' default (global): ' + c.bold(name) + c.gray('  (active + auto-load in every project)'))
 }
 
-// `skill undefault <name> [-g]` — remove the default flag.
+// `skill undefault <name>` — remove the default flag (always global).
 export function cmdUndefault(args) {
-  const global = args.includes('-g') || args.includes('--global')
   const name = args.find(a => !a.startsWith('-'))
   if (!name) {
-    console.error(c.red('Usage: skill undefault <name> [-g]'))
+    console.error(c.red('Usage: skill undefault <name>'))
     process.exit(1)
   }
-  if (global) {
-    const cfg = readGlobalConfig()
-    const had = (cfg.defaults_global || []).some(d => d.toLowerCase() === name.toLowerCase())
-    cfg.defaults_global = (cfg.defaults_global || []).filter(d => d.toLowerCase() !== name.toLowerCase())
-    writeGlobalConfig(cfg)
-    console.log(had
-      ? (c.green('✓') + ' removed global default: ' + c.bold(name))
-      : (c.gray('·') + ' not a global default: ' + c.bold(name) + c.gray(' (nothing to do)')))
-  } else {
-    const cwd = process.cwd()
-    const cfg = readProjectConfig(cwd) || { inherit: true, deny: [], allow: [], defaults: [] }
-    const had = (cfg.defaults || []).some(d => d.toLowerCase() === name.toLowerCase())
-    cfg.defaults = (cfg.defaults || []).filter(d => d.toLowerCase() !== name.toLowerCase())
-    writeProjectConfig(cwd, cfg)
-    console.log(had
-      ? (c.green('✓') + ' removed project default: ' + c.bold(name))
-      : (c.gray('·') + ' not a project default: ' + c.bold(name) + c.gray(' (nothing to do)')))
-  }
+  const cfg = readGlobalConfig()
+  const had = (cfg.defaults || []).some(d => d.toLowerCase() === name.toLowerCase())
+  cfg.defaults = (cfg.defaults || []).filter(d => d.toLowerCase() !== name.toLowerCase())
+  writeGlobalConfig(cfg)
+  console.log(had
+    ? (c.green('✓') + ' removed default: ' + c.bold(name))
+    : (c.gray('·') + ' not a default: ' + c.bold(name) + c.gray(' (nothing to do)')))
 }

package/src/commands/disable.js

@@ -8,12 +8,12 @@ export function cmdDisable(args) {
 
   if (global) {
     const cfg = readGlobalConfig()
-    const had = (cfg.enabled_global || []).some(a => a.toLowerCase() === name.toLowerCase())
-    cfg.enabled_global = (cfg.enabled_global || []).filter(a => a.toLowerCase() !== name.toLowerCase())
+    const had = (cfg.defaults || []).some(a => a.toLowerCase() === name.toLowerCase())
+    cfg.defaults = (cfg.defaults || []).filter(a => a.toLowerCase() !== name.toLowerCase())
     writeGlobalConfig(cfg)
     console.log(had
-      ? (c.green('✓') + ' disabled globally: ' + c.bold(name))
-      : (c.gray('·') + ' not enabled globally: ' + c.bold(name) + c.gray(' (nothing to do)')))
+      ? (c.green('✓') + ' removed global default: ' + c.bold(name))
+      : (c.gray('·') + ' not a global default: ' + c.bold(name) + c.gray(' (nothing to do)')))
   } else {
     const cwd = process.cwd()
     const cfg = readProjectConfig(cwd) || { inherit: true, deny: [], allow: [] }

package/src/commands/enable.js

@@ -16,11 +16,11 @@ export function cmdEnable(args) {
 
   if (global) {
     const cfg = readGlobalConfig()
-    if (!cfg.enabled_global.some(a => a.toLowerCase() === name.toLowerCase())) {
-      cfg.enabled_global.push(name.toLowerCase()); cfg.enabled_global.sort()
+    if (!(cfg.defaults || []).some(a => a.toLowerCase() === name.toLowerCase())) {
+      cfg.defaults.push(name.toLowerCase()); cfg.defaults.sort()
     }
     writeGlobalConfig(cfg)
-    console.log(c.green('✓') + ' enabled globally: ' + c.bold(name) + c.gray('  (active in all projects)'))
+    console.log(c.green('✓') + ' enabled globally (default): ' + c.bold(name) + c.gray('  (active + auto-load in all projects)'))
   } else {
     const cwd = process.cwd()
     const cfg = readProjectConfig(cwd) || { inherit: true, deny: [], allow: [] }

package/src/commands/list.js

@@ -1,14 +1,14 @@
 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()
   const globalCfg = readGlobalConfig()
   const projCfg = readProjectConfig()
   const effective = computeEffective(installed, globalCfg, projCfg)
-  const defaults = computeDefaults(installed, globalCfg, projCfg)
+  const defaults = computeDefaults(installed, globalCfg)
 
   const scope = projCfg ? c.magenta(process.cwd()) : c.gray('(global)')
   console.log(c.bold('skill list') + c.gray(' — project: ') + scope)
@@ -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.enabled_global || []).some(a => a.toLowerCase() === name.toLowerCase())) return c.blue('global ')
-  return c.gray('-      ')
-}

package/src/commands/manager.js

@@ -4,22 +4,15 @@ import { createPrompt, useState, useKeypress, usePrefix, isEnterKey, isUpKey, is
 import c from 'picocolors'
 import { STORE_DIR } from '../lib/paths.js'
 import { listStore } from '../lib/store.js'
-import { readGlobalConfig, readProjectConfig, writeProjectConfig, computeEffective, computeDefaults } from '../lib/config.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.enabled_global || []).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
-// SKILL_CLI_HOME. enabled_global is untouched (the manager toggle is project-scoped).
+// SKILL_CLI_HOME. The global `defaults` list is untouched (the manager toggle is project-scoped).
 //   passive → add to project allow (active here)
 //   active via project allow → remove from allow
 //   active via global only → add a local deny so it goes passive HERE
@@ -31,7 +24,7 @@ export function computeToggle(installed, globalCfg, projCfg, name) {
     allow: [...(projCfg?.allow || [])],
   }
   const active = computeEffective(installed, globalCfg, p).includes(name)
-  const isGlobal = (globalCfg.enabled_global || []).some(a => String(a).toLowerCase() === lc)
+  const isGlobal = (globalCfg.defaults || []).some(a => String(a).toLowerCase() === lc)
   const isProjectAllow = p.allow.some(a => String(a).toLowerCase() === lc)
   if (active) {
     p.allow = p.allow.filter(a => String(a).toLowerCase() !== lc)
@@ -73,25 +66,25 @@ function viewBody(s) {
   return shown.join('\n')
 }
 
-// Pure decision: the new project `defaults` array after toggling `name`'s default
-// flag. (The manager `a` key is project-scoped; global defaults use the CLI.)
-export function computeToggleDefault(projCfg, name) {
+// Pure decision: the new global `defaults` array after toggling `name`'s default
+// flag. (Defaults are a GLOBAL concept — active by default + auto-load. The
+// manager `a` key edits this list; `space` does the per-folder allow/deny.)
+export function computeToggleDefault(list, name) {
   const lc = String(name).toLowerCase()
-  const defs = [...(projCfg?.defaults || [])]
+  const defs = [...(list || [])]
   return defs.some(d => String(d).toLowerCase() === lc)
     ? defs.filter(d => String(d).toLowerCase() !== lc)
     : [...defs, lc]
 }
 
-// Apply the default toggle to disk and return a status line for the UI.
-function toggleDefault(name, cwd = process.cwd()) {
+// Apply the default toggle to the GLOBAL config and return a status line for the UI.
+function toggleDefault(name) {
   const installed = listStore()
   const g = readGlobalConfig()
-  const p = readProjectConfig(cwd) || { inherit: true, deny: [], allow: [], defaults: [] }
-  const wasDefault = computeDefaults(installed, g, p).includes(name)
-  const next = computeToggleDefault(p, name)
-  writeProjectConfig(cwd, { ...p, defaults: next })
-  return wasDefault ? (c.gray('· un-defaulted: ') + name) : (c.yellow('★ default: ') + name + c.gray(' (auto-load)'))
+  const wasDefault = computeDefaults(installed, g).includes(name)
+  g.defaults = computeToggleDefault(g.defaults, name)
+  writeGlobalConfig(g)
+  return wasDefault ? (c.gray('· un-defaulted: ') + name) : (c.yellow('★ default: ') + name + c.gray(' (active + auto-load)'))
 }
 
 // Clamp a cursor move so it can't leave the list bounds (pure → unit-tested).
@@ -115,7 +108,7 @@ const managerPrompt = createPrompt((_config, done) => {
   const g = readGlobalConfig()
   const p = readProjectConfig()
   const eff = computeEffective(installed, g, p)
-  const defs = computeDefaults(installed, g, p)
+  const defs = computeDefaults(installed, g)
   const cur = installed.length ? Math.max(0, Math.min(cursor, installed.length - 1)) : 0
   const s = installed[cur]
 
@@ -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/commands/remove.js

@@ -94,8 +94,8 @@ export function cmdRemove(args) {
 // Exported so the interactive manager can reuse it on its `d` (delete) action.
 export function cleanConfig(name) {
   const g = readGlobalConfig()
-  if ((g.enabled_global || []).some(a => a.toLowerCase() === name.toLowerCase())) {
-    g.enabled_global = (g.enabled_global || []).filter(a => a.toLowerCase() !== name.toLowerCase())
+  if ((g.defaults || []).some(a => a.toLowerCase() === name.toLowerCase())) {
+    g.defaults = (g.defaults || []).filter(a => a.toLowerCase() !== name.toLowerCase())
     writeGlobalConfig(g)
   }
   const cwd = process.cwd()

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
@@ -19,14 +20,24 @@ Usage:
 - \`skill show <name>\` — skill summary (path, triggers, version)
 - \`skill cat <name>\` — load skill content into context
 
-Defaults: on session start, run \`skill defaults\` to list skills marked for
-auto-load, then \`skill cat <name>\` for each. Mark your own with
-\`skill default <name>\` (or \`-g\` for every project).
+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/config.js

@@ -6,8 +6,7 @@ import { CLI_ROOT, GLOBAL_CONFIG, PROJECT_CONFIG, STORE_DIR } from './paths.js'
 const DEFAULT_GLOBAL = {
   version: 1,
   store: STORE_DIR,
-  enabled_global: [],
-  defaults_global: [],
+  defaults: [],
 }
 
 export function readGlobalConfig() {
@@ -18,7 +17,20 @@ export function readGlobalConfig() {
     process.stderr.write('skill-cli config: parse error (' + (e.message || e) + ') — using defaults\n')
     return { ...DEFAULT_GLOBAL }
   }
-  return { ...DEFAULT_GLOBAL, ...(parsed || {}) }
+  const merged = { ...DEFAULT_GLOBAL, ...(parsed || {}) }
+  // backward-compat: legacy configs split the active-by-default set
+  // (`enabled_global`) from the auto-load set (`defaults_global`). The unified
+  // model collapses them into one `defaults` list (a default skill is now BOTH
+  // active-by-default AND auto-loaded). On read, adopt the union of both legacy
+  // lists when no new-format `defaults` is present; `defaults` always wins.
+  if (!Array.isArray(merged.defaults) || merged.defaults.length === 0) {
+    const legacy = [
+      ...(Array.isArray(parsed?.enabled_global) ? parsed.enabled_global : []),
+      ...(Array.isArray(parsed?.defaults_global) ? parsed.defaults_global : []),
+    ]
+    if (legacy.length) merged.defaults = [...new Set(legacy.map(String))]
+  }
+  return merged
 }
 
 export function writeGlobalConfig(cfg) {
@@ -29,8 +41,7 @@ export function writeGlobalConfig(cfg) {
   const out = {
     version: cfg.version ?? 1,
     store: cfg.store ?? STORE_DIR,
-    enabled_global: cfg.enabled_global || [],
-    defaults_global: cfg.defaults_global || [],
+    defaults: cfg.defaults || [],
   }
   fs.writeFileSync(GLOBAL_CONFIG, yaml.stringify(out), 'utf8')
 }
@@ -49,7 +60,7 @@ export function readProjectConfig(cwd = process.cwd()) {
     process.stderr.write('skill.config: parse error (' + (e.message || e) + ') — using global behavior\n')
     return null
   }
-  return { inherit: true, deny: [], allow: [], defaults: [], ...(parsed || {}) }
+  return { inherit: true, deny: [], allow: [], ...(parsed || []) }
 }
 
 export function writeProjectConfig(cwd, cfg) {
@@ -58,7 +69,6 @@ export function writeProjectConfig(cwd, cfg) {
     inherit: cfg.inherit !== false,
     deny: cfg.deny || [],
     allow: cfg.allow || [],
-    defaults: cfg.defaults || [],
   }
   fs.writeFileSync(projectConfigPath(cwd), yaml.stringify(out), 'utf8')
 }
@@ -81,7 +91,7 @@ function globMatch(pattern, name) {
 export function computeEffective(installed, globalCfg, projCfg) {
   const canonByLower = new Map(installed.map(s => [String(s.name).toLowerCase(), s.name]))
   const enabled = new Set(
-    (projCfg && projCfg.inherit === false ? [] : (globalCfg.enabled_global || []))
+    (projCfg && projCfg.inherit === false ? [] : (globalCfg.defaults || []))
       .map(s => String(s).toLowerCase())
   )
   if (projCfg) {
@@ -103,15 +113,15 @@ export function computeEffective(installed, globalCfg, projCfg) {
 }
 
 // Effective DEFAULT skills (auto-loaded on agent session start), as CANONICAL
-// names. Independent of enable/disable: a skill may be active-but-not-default or
-// default-but-not-active. Inherits global defaults unless the project sets
-// inherit:false. Case-insensitive throughout.
-export function computeDefaults(installed, globalCfg, projCfg) {
+// names. In the unified model the default list IS the globally-active-by-default
+// set (one `defaults` key in config.yaml): a default skill is active in every
+// project AND auto-loaded on start. So this just returns that list filtered to
+// installed skills. Defaults are GLOBAL (never per-folder) and ignore a
+// project's deny rules (deny only governs active state, not auto-load).
+export function computeDefaults(installed, globalCfg) {
   const canonByLower = new Map(installed.map(s => [String(s.name).toLowerCase(), s.name]))
-  const set = new Set()
-  if (!projCfg || projCfg.inherit !== false) {
-    for (const d of (globalCfg.defaults_global || [])) set.add(String(d).toLowerCase())
-  }
-  if (projCfg) for (const d of (projCfg.defaults || [])) set.add(String(d).toLowerCase())
-  return [...set].filter(n => canonByLower.has(n)).map(n => canonByLower.get(n)).sort()
+  return [...new Set((globalCfg.defaults || []).map(s => String(s).toLowerCase()))]
+    .filter(n => canonByLower.has(n))
+    .map(n => canonByLower.get(n))
+    .sort()
 }

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))
+}

package/src/lib/paths.js

@@ -17,4 +17,6 @@ export const AGENT_GLOBALS = [
   { id: 'claude', dir: '.claude', file: 'CLAUDE.md' },
   { id: 'codex', dir: '.codex', file: 'AGENTS.md' },
   { id: 'gemini', dir: '.gemini', file: 'GEMINI.md' },
+  // pi loads global context from ~/.pi/agent/AGENTS.md (or CLAUDE.md).
+  { id: 'pi', dir: '.pi/agent', file: 'AGENTS.md' },
 ]