@victortomaili/skill-cli 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -11,6 +11,27 @@ 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.2] - 2026-07-07
+
+### Changed
+- AGENTS.md START GATE: stricter, broader PROPOSE rule. The agent now auto-loads
+  only skills STRICTLY NECESSARY to attempt the task, and PROPOSES (waits for user
+  confirmation) everything else — explicitly including: response STYLE/format/mode
+  skills, CONTEXT-COST / token optimizers, ACTIVATE-BEFORE-WORK workflows, and any
+  facilitator/accelerator that would make the job EASIER or FASTER. When unsure,
+  propose (propose is the safe default; loading is silent).
+
+## [0.6.1] - 2026-07-07
+
+### Changed
+- Renamed the agent catalog command `skill defaults` → **`skill active`** (`skill
+  status` is an alias; `skill defaults` is kept as a legacy alias so already-bootstrapped
+  agents keep working). It now lists ONLY the skills active in the current project
+  (defaults + project allow, minus deny) with full descriptions — not every installed
+  skill. `skill default <name>` / `skill undefault <name>` (marking) are unchanged.
+- AGENTS.md START GATE updated to run `skill active` and scope the catalog to
+  active skills.
+
 ## [0.6.0] - 2026-07-07
 
 ### Changed

package/README.md

@@ -83,7 +83,7 @@ short bootstrap block telling it to run `skill` on `/X`.
 | `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 active` | List ACTIVE skills + descriptions (the command your agent runs on start; alias: `status`) |
 | `skill list` | Show installed + active skills (cwd-aware, ★ = default) |
 | `skill show <name>` | Skill metadata (path, triggers, version) |
 | `skill cat <name>` | Dump skill content into context |
@@ -181,8 +181,8 @@ with no source also opens it.
 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>`
+`skill undefault <name>`, list them with `skill active`. The AGENTS.md bootstrap
+block tells your agent to run `skill active` on start, then `skill cat <name>`
 for each.
 
 Defaults are a **global** concept (never per-project). A project can still turn a
@@ -197,14 +197,15 @@ default; `space` toggles the per-project override.
 instruction file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`):
 
 > **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).
+> ANYTHING ELSE (before thinking, before any tool call) — is `skill active`, the
+> skill **catalog** (every active skill's name + full description; never the body).
+> Read it and decide per skill from its description: **strictly necessary** to even
+> attempt the task → load it (`skill cat <name>`); **otherwise PROPOSE** — including
+> any skill that changes your response *style/format*, optimizes *context cost*, is
+> meant to be *activated before the work*, or would make the job *easier/faster*
+> (a facilitator). Apply only after the user confirms (`/X` = confirm); when unsure,
+> propose. **LOADED ≠ LISTED**: a skill is loaded only if you `cat`-ed it this
+> session — listing it (or its ★ / `active` status) is not loading.
 > `/X` → `skill trigger X`.
 
 It's wrapped in `<!-- BEGIN skill-cli --> … <!-- END skill-cli -->` markers, never

package/package.json

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

@@ -12,7 +12,7 @@ import { cmdUpdate } from './commands/update.js'
 import { cmdRemove } from './commands/remove.js'
 import { cmdSearch } from './commands/search.js'
 import { cmdManager } from './commands/manager.js'
-import { cmdDefaults, cmdDefault, cmdUndefault } from './commands/defaults.js'
+import { cmdActive, cmdDefault, cmdUndefault } from './commands/defaults.js'
 import { isInteractive } from './lib/interactive.js'
 import { VERSION } from './lib/version.js'
 
@@ -33,11 +33,11 @@ ${c.bold('Activation')}
   ${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.cyan('skill active')}               active skills + descriptions (agent runs on start; alias: status)
 
 ${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
@@ -90,7 +90,7 @@ async function main() {
     case 'enable': cmdEnable(rest); break
     case 'disable': cmdDisable(rest); break
     case 'list': case 'ls': cmdList(rest); break
-    case 'defaults': cmdDefaults(rest); break
+    case 'active': case 'status': case 'defaults': cmdActive(rest); break
     case 'default': case 'def': cmdDefault(rest); break
     case 'undefault': case 'undef': cmdUndefault(rest); break
     case 'show': case 'info': cmdShow(rest); break

package/src/commands/defaults.js

@@ -1,40 +1,46 @@
 import c from 'picocolors'
 import { listStore } from '../lib/store.js'
-import { readGlobalConfig, writeGlobalConfig } from '../lib/config.js'
+import { readGlobalConfig, writeGlobalConfig, readProjectConfig, computeEffective } 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
-// 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() {
+// `skill active` (aliases: `status`, legacy `defaults`) — the description-only
+// catalog of ACTIVE skills in the current project (defaults + project allow,
+// minus deny). The agent runs this at session start: it lists each active skill's
+// name + FULL description (never the body), then the agent itself decides per
+// skill — functional → `skill cat`, context-altering → propose. Detection of
+// context-altering is the agent's judgment from the description (no flag, no fixed
+// list), so it works for any skill, including ones installed later.
+export function cmdActive() {
   const installed = listStore()
   const globalCfg = readGlobalConfig()
+  const projCfg = readProjectConfig()
+  const eff = computeEffective(installed, globalCfg, projCfg)
   const defs = new Set((globalCfg.defaults || []).map(d => String(d).toLowerCase()))
 
-  console.log(c.bold('skill defaults') + c.gray(' — skill catalog (descriptions only; the agent decides: functional → `skill cat`, context-altering → propose)'))
+  console.log(c.bold('skill active') + c.gray(' — active skills (descriptions only). Load only what is STRICTLY necessary; PROPOSE style/cost/workflow/facilitator skills and wait for confirmation.'))
   console.log()
 
-  if (installed.length === 0) {
-    console.log(c.gray('  No skills installed. Install with: ') + c.cyan('skill install <source>'))
+  if (eff.length === 0) {
+    console.log(c.gray('  No active skills in this project.'))
     return
   }
 
-  // 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) {
+  // CATALOG of ACTIVE skills only (not all installed): defaults + project allow,
+  // minus deny. Print each one's name + FULL description (one line) + triggers —
+  // never the body. The agent reads descriptions and itself decides per skill:
+  // load (skill cat) if functional for the task, or PROPOSE if context-altering
+  // (changes HOW the agent responds). Detection is the agent's judgment from the
+  // description, so it works for any skill — including ones installed later —
+  // with no hardcoded list or flag.
+  for (const name of eff) {
+    const s = installed.find(x => x.name === name)
+    if (!s) continue
     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.yellow('★') + c.gray(' = default (active by default). Load a skill: ') + c.cyan('skill cat <name>'))
+  console.log(c.yellow('★') + c.gray(' = 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,7 +6,7 @@ const BEGIN = '<!-- BEGIN skill-cli -->'
 const END = '<!-- END skill-cli -->'
 
 // Global instruction block — injected into each agent's global instruction file.
-// `skill defaults` is a description-only CATALOG; the agent reads it, then itself
+// `skill active` (alias: `status`) is a description-only CATALOG of ACTIVE skills;
 // 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).
@@ -25,15 +25,24 @@ Usage:
 
 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).
+and before any tool call — MUST be to run \`skill active\`. It prints the skill
+CATALOG — every ACTIVE 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.
+- It is STRICTLY NECESSARY to even attempt the task (you cannot do it without
+  this knowledge) → load it: \`skill cat <name>\`.
+- OTHERWISE PROPOSE it — tell the user it's available and what it does, then apply
+  ONLY after they confirm (\`/X\` = confirm). You MUST propose (never silently apply)
+  any skill that:
+  • changes your communication / response STYLE, tone, format, or a persistent
+    mode (e.g. a brevity / compression style);
+  • optimizes CONTEXT COST / token usage;
+  • is meant to be ACTIVATED BEFORE the work (a workflow / methodology);
+  • would make the job EASIER or FASTER — a facilitator / accelerator / tool —
+    even if optional. Surface it so the user can opt in.
+When unsure whether a skill is necessary or optional → PROPOSE (proposing is the
+  safe default; loading is silent).
 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 THIS session. Seeing a skill in \`skill active\` / \`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).