happyskills 0.45.0 → 0.46.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.46.0] - 2026-05-20
+
+### Added
+- Add `happyskills agents` command for project-scoped agent configuration with three subcommands: `agents list` (default — show every supported agent with configured/linked status for the current scope), `agents add <ids>` (create `.<agent>/skills/` and mirror every currently-enabled installed skill as symlinks), and `agents remove <ids>` (remove the CLI-managed symlinks; delete the `skills/` folder if it ends up empty; never touch the agent's other state). Accepts comma- or space-separated agent ids (`claude,cursor` or `claude cursor`), supports `-g` for global scope and `--json` everywhere. The common use case is trying a new agentic client (e.g., Codex) on a single project without changing the user-global default — `happyskills agents add codex` makes that one-line. `add` respects per-skill disabled state: skills with no symlinks in any other configured agent are skipped with a clear message pointing at `enable`. Kits are not mirrored (not agent-invocable).
+- Add a fifth tier to the agent-resolution priority chain used by `install`, `uninstall`, `update`, `enable`, `disable`, `init`, `convert`, `setup`, and the new `agents` command: **project-physical** now sits at tier 3, above the user-global `config agents` value. The priority chain is now (top wins): (1) `--agents` flag, (2) `HAPPYSKILLS_AGENTS` env var, (3) project-physical (any `.<agent>/skills/` in the project root, project scope only), (4) `~/.config/happyskills/config.json` agents value, (5) home-physical fallback (auto-detect from `~/.<agent>/skills/`). This is what makes `agents add` decisions stick across subsequent commands without re-passing flags — the folder IS the project's configuration, no new JSON file required.
+
+### Changed
+- Tighten multi-agent detection to key on `.<agent>/skills/` (the subfolder), not the bare `.<agent>/` directory. `.<agent>/skills/` is unambiguously a HappySkills artifact — only the CLI ever creates it — whereas `.<agent>/` is also used by the agent itself for unrelated state (settings, history, sessions, `CLAUDE.md`, etc.). The looser previous signal would treat any project with `.claude/` as "Claude is configured here," causing installs to drop symlinks into projects where the user never asked for skill integration. **Possible behavior change for fresh projects:** a user who has Claude Code installed (`~/.claude/` exists) but has never installed any HappySkills skill in this project AND has no `~/.claude/skills/` will no longer auto-detect Claude on their very first install. Mitigations: (a) running `happyskills setup` once globally creates `~/.claude/skills/` and tier 5 takes over, (b) `happyskills agents add claude` makes the intent explicit and creates the project-level folder, (c) the `--agents` flag and `HAPPYSKILLS_AGENTS` env var continue to override unconditionally.
+- Drop the `detect_paths` field from the agent registry (`cli/src/agents/registry.js`). Detection now derives from the per-agent `skills_dir` / `global_skills_dir` fields directly — one source of truth per agent.
+- Update `resolve_agents()` and `detect_agents()` signatures to accept an `{ global, project_root }` options object so resolution is scope-aware. All call sites (`installer`, `uninstaller`, `enable`, `disable`, `init`, `convert`, `update`, `list`, `config`) updated to pass the right scope.
+
+## [0.45.1] - 2026-05-14
+
+### Changed
+- `validate` soft-cap warning text now references the **Constellation Pattern** (formerly "Suite Pattern") and the **Constellation Decomposition Workflow** (formerly "Suite Decomposition Workflow"), and points at `happyskills-design references/constellation-pattern.md` (formerly `references/suite-pattern.md`). Terminology alignment with `happyskillsai/happyskills-design@0.8.0` — no behaviour change; the warning still fires at the same 250-char threshold and still recommends decomposition.
+
 ## [0.45.0] - 2026-05-13
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.45.0",
+	"version": "0.46.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/agents/detector.js

@@ -8,23 +8,37 @@ const { get_config_value } = require('../config/store')
 const home_dir = os.homedir()
 
 /**
- * Detect which agents are installed by checking for home-level config folders.
- * All checks run in parallel via Promise.all.
+ * Resolve the on-disk skills folder for an agent in a given scope.
  *
+ * @param {Agent} agent
+ * @param {boolean} is_global
+ * @param {string} project_root
+ * @returns {string} absolute path to .<agent>/skills/
+ */
+const _agent_skills_path = (agent, is_global, project_root) => {
+	if (is_global) return path.join(home_dir, agent.global_skills_dir)
+	return path.join(project_root || process.cwd(), agent.skills_dir)
+}
+
+/**
+ * Detect which agents are configured by checking for the `.<agent>/skills/`
+ * folder. This is the only unambiguous signal: that subfolder is created by
+ * this CLI, never by the agent itself, so it carries deliberate intent.
+ *
+ * @param {object} options — { global, project_root }
  * @returns {Promise} [errors, Agent[]] — array of detected agent objects
  */
-const detect_agents = () => catch_errors('Agent detection failed', async () => {
+const detect_agents = (options = {}) => catch_errors('Agent detection failed', async () => {
+	const { global: is_global = false, project_root } = options
+
 	const checks = AGENTS.map(async (agent) => {
-		for (const rel_path of agent.detect_paths) {
-			const full_path = path.join(home_dir, rel_path)
-			try {
-				await fs.promises.access(full_path)
-				return agent
-			} catch {
-				// path not found — agent not detected
-			}
+		const skills_path = _agent_skills_path(agent, is_global, project_root)
+		try {
+			const stat = await fs.promises.stat(skills_path)
+			return stat.isDirectory() ? agent : null
+		} catch {
+			return null
 		}
-		return null
 	})
 
 	const results = await Promise.all(checks)
@@ -59,38 +73,51 @@ const _parse_agents_flag = (agents_str) => {
  * Resolve which agents to target. Priority:
  *   1. --agents flag (explicit per-command override)
  *   2. HAPPYSKILLS_AGENTS env var (persistent user preference)
- *   3. Config file agents value (~/.config/happyskills/config.json)
- *   4. Auto-detection (scan home dir for agent config folders)
+ *   3. Project-physical (only when !global) — any .<agent>/skills/ that exists
+ *      in the project root. The folders ARE the project-level configuration.
+ *   4. Config file agents value (~/.config/happyskills/config.json)
+ *   5. Home-physical fallback — auto-detect from ~/.<agent>/skills/
  *
  * Physical files always go to the canonical `.agents/skills/` directory.
  * Each resolved agent gets a symlink from the canonical location.
  *
  * @param {string|undefined} agents_flag — from --agents CLI flag
- * @returns {Promise} [errors, { agents: Agent[] }]
+ * @param {object} options — { global, project_root }
+ * @returns {Promise} [errors, { agents: Agent[], source: string }]
  */
-const resolve_agents = (agents_flag) => catch_errors('Agent resolution failed', async () => {
-	// 1. Explicit --agents flag takes highest priority
+const resolve_agents = (agents_flag, options = {}) => catch_errors('Agent resolution failed', async () => {
+	const { global: is_global = false, project_root } = options
+
+	// 1. Explicit --agents flag
 	if (agents_flag) {
-		return _parse_agents_flag(agents_flag)
+		return { ...(_parse_agents_flag(agents_flag)), source: 'flag' }
 	}
 
 	// 2. HAPPYSKILLS_AGENTS env var
 	const env_agents = process.env.HAPPYSKILLS_AGENTS
 	if (env_agents) {
-		return _parse_agents_flag(env_agents)
+		return { ...(_parse_agents_flag(env_agents)), source: 'env' }
+	}
+
+	// 3. Project-physical (project scope only)
+	if (!is_global) {
+		const [, project_detected] = await detect_agents({ global: false, project_root })
+		if (project_detected && project_detected.length > 0) {
+			return { agents: project_detected, source: 'project' }
+		}
 	}
 
-	// 3. Config file
+	// 4. Config file
 	const [, config_agents] = await get_config_value('agents')
 	if (config_agents) {
-		return _parse_agents_flag(config_agents)
+		return { ...(_parse_agents_flag(config_agents)), source: 'config' }
 	}
 
-	// 4. Auto-detect
-	const [errors, detected] = await detect_agents()
+	// 5. Home-physical fallback (legacy auto-detect)
+	const [errors, home_detected] = await detect_agents({ global: true })
 	if (errors) throw errors[0]
 
-	return { agents: detected }
+	return { agents: home_detected, source: 'home' }
 })
 
 module.exports = { detect_agents, resolve_agents }

package/src/agents/registry.js

@@ -4,6 +4,11 @@
  * Physical skill files live in the canonical `.agents/skills/` directory.
  * Each agent listed here gets a symlink from `.agents/skills/` to its own skills directory.
  * Adding a new agent = adding one object to the AGENTS array.
+ *
+ * Detection signal: an agent is considered configured for a given scope when
+ * `<scope>/<skills_dir>` (project) or `<home>/<global_skills_dir>` (global) exists
+ * on disk. The `.<agent>/skills/` subfolder is unambiguous — it is only ever
+ * created by this CLI, never by the agent itself.
  */
 
 const AGENTS = [
@@ -11,57 +16,49 @@ const AGENTS = [
 		id: 'claude',
 		display_name: 'Claude Code',
 		skills_dir: '.claude/skills',
-		global_skills_dir: '.claude/skills',
-		detect_paths: ['.claude']
+		global_skills_dir: '.claude/skills'
 	},
 	{
 		id: 'cursor',
 		display_name: 'Cursor',
 		skills_dir: '.cursor/skills',
-		global_skills_dir: '.cursor/skills',
-		detect_paths: ['.cursor']
+		global_skills_dir: '.cursor/skills'
 	},
 	{
 		id: 'windsurf',
 		display_name: 'Windsurf',
 		skills_dir: '.windsurf/skills',
-		global_skills_dir: '.windsurf/skills',
-		detect_paths: ['.windsurf']
+		global_skills_dir: '.windsurf/skills'
 	},
 	{
 		id: 'codex',
 		display_name: 'Codex',
 		skills_dir: '.codex/skills',
-		global_skills_dir: '.codex/skills',
-		detect_paths: ['.codex']
+		global_skills_dir: '.codex/skills'
 	},
 	{
 		id: 'copilot',
 		display_name: 'GitHub Copilot',
 		skills_dir: '.github/skills',
-		global_skills_dir: '.github/skills',
-		detect_paths: ['.github/copilot']
+		global_skills_dir: '.github/skills'
 	},
 	{
 		id: 'aider',
 		display_name: 'Aider',
 		skills_dir: '.aider/skills',
-		global_skills_dir: '.aider/skills',
-		detect_paths: ['.aider']
+		global_skills_dir: '.aider/skills'
 	},
 	{
 		id: 'cline',
 		display_name: 'Cline',
 		skills_dir: '.cline/skills',
-		global_skills_dir: '.cline/skills',
-		detect_paths: ['.cline']
+		global_skills_dir: '.cline/skills'
 	},
 	{
 		id: 'roo',
 		display_name: 'Roo Code',
 		skills_dir: '.roo/skills',
-		global_skills_dir: '.roo/skills',
-		detect_paths: ['.roo']
+		global_skills_dir: '.roo/skills'
 	}
 ]
 

package/src/commands/agents.js

@@ -0,0 +1,312 @@
+const fs = require('fs')
+const path = require('path')
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { AGENTS, get_agent, get_all_agent_ids } = require('../agents/registry')
+const { detect_agents } = require('../agents/detector')
+const { link_to_agents, unlink_from_agents } = require('../agents/linker')
+const { is_skill_enabled } = require('../agents/status')
+const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { file_exists } = require('../utils/fs')
+const { find_project_root, lock_root, skills_dir, skill_install_dir, agent_skills_dir } = require('../config/paths')
+const { print_help, print_json, print_success, print_warn, print_info, print_table, code } = require('../ui/output')
+const { green, dim } = require('../ui/colors')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES, SKILL_TYPES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills agents <subcommand> [args] [options]
+
+Configure which agentic clients (Claude Code, Cursor, Codex, ...) receive
+the skills installed in this project. Detection is filesystem-based: an
+agent is "configured" for this project when .<agent>/skills/ exists.
+
+Subcommands:
+  happyskills agents                       Alias for 'list'
+  happyskills agents list                  Show every supported agent + its status here
+  happyskills agents add <ids>             Create .<agent>/skills/ and mirror every
+                                           enabled skill into it (symlinks)
+  happyskills agents remove <ids>          Remove .<agent>/skills/ symlinks for this
+                                           project. Physical files in .agents/skills/
+                                           are untouched. The agent's other state
+                                           (settings, history, ...) is left alone.
+
+<ids> is a comma- or space-separated list of agent ids:
+  ${get_all_agent_ids().join(', ')}
+
+Options:
+  -g, --global      Operate on ~/.<agent>/skills/ instead of project-local
+  --json            Output as JSON
+
+Examples:
+  happyskills agents add codex
+  happyskills agents add codex,cursor
+  happyskills agents add codex cursor
+  happyskills agents remove codex
+  happyskills agents list
+  happyskills agents add codex -g`
+
+const _parse_agent_ids = (raw_args) => {
+	const ids = raw_args.flatMap(a => a.split(',')).map(s => s.trim()).filter(Boolean)
+	if (ids.length === 0) {
+		throw new UsageError(`Please specify at least one agent id. Available: ${get_all_agent_ids().join(', ')}`)
+	}
+	const resolved = []
+	const unknown = []
+	for (const id of ids) {
+		const agent = get_agent(id)
+		if (agent) resolved.push(agent)
+		else unknown.push(id)
+	}
+	if (unknown.length > 0) {
+		throw new UsageError(`Unknown agent(s): ${unknown.join(', ')}. Available: ${get_all_agent_ids().join(', ')}`)
+	}
+	return resolved
+}
+
+/**
+ * For each installed skill, decide whether it should be mirrored into the
+ * newly added agent. A skill is mirrored when it is currently enabled — i.e.,
+ * a symlink for it exists in at least one *other* already-configured agent.
+ *
+ * When no other agent folders exist yet (fresh project bootstrap), every
+ * non-kit installed skill is mirrored.
+ */
+const _select_skills_to_mirror = async (lock_data, is_global, project_root, new_agent) => {
+	const all = get_all_locked_skills(lock_data)
+	const installed = Object.entries(all).filter(([, data]) => data && data.type !== SKILL_TYPES.KIT)
+
+	// Find any *other* agents that are already configured in this scope
+	const [, all_detected] = await detect_agents({ global: is_global, project_root })
+	const other_detected = (all_detected || []).filter(a => a.id !== new_agent.id)
+
+	const selected = []
+	const skipped_disabled = []
+
+	for (const [full_name, data] of installed) {
+		const short = full_name.split('/')[1] || full_name
+
+		if (other_detected.length === 0) {
+			selected.push({ full_name, short })
+			continue
+		}
+
+		const [, enabled] = await is_skill_enabled(short, other_detected, is_global, project_root)
+		if (enabled) selected.push({ full_name, short })
+		else skipped_disabled.push(full_name)
+	}
+
+	return { selected, skipped_disabled }
+}
+
+const _add = async (raw_args, args) => {
+	const agents = _parse_agent_ids(raw_args)
+	const is_global = args.flags.global || false
+	const project_root = find_project_root()
+	const is_json = args.flags.json || false
+	const base_dir = skills_dir(is_global, project_root)
+
+	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
+	const has_lock = !!(lock_data && lock_data.skills && Object.keys(lock_data.skills).length > 0)
+
+	const per_agent = []
+
+	for (const agent of agents) {
+		const target_root = agent_skills_dir(agent, is_global, project_root)
+		await fs.promises.mkdir(target_root, { recursive: true })
+
+		if (!has_lock) {
+			per_agent.push({ agent_id: agent.id, status: 'configured', linked: [], skipped_disabled: [] })
+			continue
+		}
+
+		const { selected, skipped_disabled } = await _select_skills_to_mirror(lock_data, is_global, project_root, agent)
+		const linked = []
+
+		for (const { full_name, short } of selected) {
+			const source = skill_install_dir(base_dir, short)
+			const [, exists] = await file_exists(source)
+			if (!exists) {
+				if (!is_json) print_warn(`Skipping ${full_name}: source missing at ${source} (re-install required)`)
+				continue
+			}
+			const [link_err] = await link_to_agents(source, [agent], { global: is_global, project_root, skill_name: short })
+			if (link_err) {
+				if (!is_json) print_warn(`Failed to link ${full_name} into ${agent.display_name}`)
+				continue
+			}
+			linked.push(full_name)
+		}
+
+		per_agent.push({ agent_id: agent.id, status: 'configured', linked, skipped_disabled })
+
+		if (!is_json) {
+			const scope = is_global ? 'globally' : 'in this project'
+			print_success(`${agent.display_name} configured ${scope} (${target_root})`)
+			if (linked.length > 0) print_info(`  Linked ${linked.length} skill(s): ${linked.join(', ')}`)
+			if (skipped_disabled.length > 0) {
+				print_info(`  Skipped ${skipped_disabled.length} disabled skill(s): ${skipped_disabled.join(', ')}`)
+				print_info(`  Re-enable with: ${code('happyskills enable <skill>')}`)
+			}
+		}
+	}
+
+	if (is_json) {
+		print_json({ data: { added: per_agent, global: is_global } })
+	}
+}
+
+const _remove = async (raw_args, args) => {
+	const agents = _parse_agent_ids(raw_args)
+	const is_global = args.flags.global || false
+	const project_root = find_project_root()
+	const is_json = args.flags.json || false
+
+	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
+	const all = get_all_locked_skills(lock_data)
+	const short_names = Object.keys(all).map(k => k.split('/')[1] || k)
+
+	const per_agent = []
+
+	for (const agent of agents) {
+		const target_root = agent_skills_dir(agent, is_global, project_root)
+		const [, exists] = await file_exists(target_root)
+		if (!exists) {
+			per_agent.push({ agent_id: agent.id, status: 'not_configured' })
+			if (!is_json) print_info(`${agent.display_name}: nothing to remove (no ${target_root})`)
+			continue
+		}
+
+		const unlinked = []
+		if (short_names.length > 0) {
+			const [unlink_err, results] = await unlink_from_agents_each(short_names, agent, is_global, project_root)
+			if (unlink_err) {
+				if (!is_json) print_warn(`Failed to remove some symlinks from ${agent.display_name}`)
+			}
+			for (const r of (results || [])) {
+				if (r.removed) unlinked.push(r.skill_name)
+			}
+		}
+
+		// If the agent's skills folder is now empty, remove it (leave the parent .<agent>/ alone)
+		let removed_folder = false
+		try {
+			const entries = await fs.promises.readdir(target_root)
+			if (entries.length === 0) {
+				await fs.promises.rmdir(target_root)
+				removed_folder = true
+			}
+		} catch {
+			// best-effort cleanup
+		}
+
+		per_agent.push({ agent_id: agent.id, status: 'removed', unlinked, removed_folder })
+
+		if (!is_json) {
+			print_success(`${agent.display_name} disconnected from this ${is_global ? 'machine' : 'project'}`)
+			if (unlinked.length > 0) print_info(`  Removed ${unlinked.length} symlink(s)`)
+			if (!removed_folder) print_info(`  Folder ${target_root} kept (non-empty — left untouched)`)
+		}
+	}
+
+	if (is_json) {
+		print_json({ data: { removed: per_agent, global: is_global } })
+	}
+}
+
+/**
+ * Unlink one agent across many skills. Returns per-skill results.
+ */
+const unlink_from_agents_each = async (short_names, agent, is_global, project_root) => {
+	const results = []
+	let last_err = null
+	for (const short of short_names) {
+		const [err, res] = await unlink_from_agents(short, [agent], { global: is_global, project_root })
+		if (err) { last_err = err; continue }
+		const item = (res || [])[0]
+		if (item) results.push({ skill_name: short, removed: !!item.removed })
+	}
+	return [last_err, results]
+}
+
+const _list = async (args) => {
+	const is_global = args.flags.global || false
+	const project_root = find_project_root()
+	const is_json = args.flags.json || false
+
+	const [, detected] = await detect_agents({ global: is_global, project_root })
+	const detected_ids = new Set((detected || []).map(a => a.id))
+
+	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
+	const all = get_all_locked_skills(lock_data)
+	const short_names = Object.keys(all).map(k => k.split('/')[1] || k)
+
+	const rows = []
+	for (const agent of AGENTS) {
+		const target_root = agent_skills_dir(agent, is_global, project_root)
+		const is_detected = detected_ids.has(agent.id)
+		let linked_count = 0
+		if (is_detected && short_names.length > 0) {
+			for (const short of short_names) {
+				const [, enabled] = await is_skill_enabled(short, [agent], is_global, project_root)
+				if (enabled) linked_count++
+			}
+		}
+		rows.push({ agent, target_root, configured: is_detected, linked_count })
+	}
+
+	if (is_json) {
+		print_json({
+			data: {
+				scope: is_global ? 'global' : 'project',
+				agents: rows.map(r => ({
+					id: r.agent.id,
+					display_name: r.agent.display_name,
+					skills_dir: r.target_root,
+					configured: r.configured,
+					linked_skills: r.linked_count
+				}))
+			}
+		})
+		return
+	}
+
+	const table_rows = rows.map(r => [
+		r.agent.id,
+		r.agent.display_name,
+		r.configured ? green('yes') : dim('no'),
+		r.configured ? String(r.linked_count) : dim('—'),
+		r.target_root
+	])
+	print_table(['ID', 'Agent', 'Configured', 'Linked', 'Folder'], table_rows)
+	console.log()
+	print_info(`Scope: ${is_global ? 'global (~)' : 'project (' + project_root + ')'}`)
+	print_info(`Add an agent here: ${code('happyskills agents add <id>')}`)
+}
+
+const run = (args) => catch_errors('Agents command failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const sub = args._.shift()
+	const rest = args._
+
+	if (!sub || sub === 'list' || sub === 'ls') {
+		await _list(args)
+		return
+	}
+
+	if (sub === 'add') {
+		await _add(rest, args)
+		return
+	}
+
+	if (sub === 'remove' || sub === 'rm') {
+		await _remove(rest, args)
+		return
+	}
+
+	throw new UsageError(`Unknown subcommand: '${sub}'. Use add, remove, or list.`)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run }

package/src/commands/config.js

@@ -54,7 +54,7 @@ const _validate_agent_ids = (agents_str) => {
 }
 
 const _list_agents = async (config, is_json) => {
-	const [, detected] = await detect_agents()
+	const [, detected] = await detect_agents({ global: true })
 	const detected_ids = new Set((detected || []).map(a => a.id))
 	const config_agents = config.agents ? config.agents.split(',').map(s => s.trim()) : null
 	const default_ids = config_agents ? new Set(config_agents) : null

package/src/commands/convert.js

@@ -215,7 +215,7 @@ const run = (args) => catch_errors('Convert failed', async () => {
 
 	// Link to detected agents (non-fatal — warnings only)
 	const linked_agents = []
-	const [agents_err, agents_result] = await resolve_agents(args.flags.agents || undefined)
+	const [agents_err, agents_result] = await resolve_agents(args.flags.agents || undefined, { global: is_global, project_root })
 	if (!agents_err && agents_result?.agents?.length > 0) {
 		pub_spinner.update(`Linking to ${agents_result.agents.length} agent(s)...`)
 		const [link_errs] = await link_to_agents(skill_dir, agents_result.agents, { global: is_global, project_root, skill_name })

package/src/commands/disable.js

@@ -57,7 +57,7 @@ const run = (args) => catch_errors('Disable failed', async () => {
 	const is_global = args.flags.global || false
 	const project_root = find_project_root()
 
-	const [agents_err, agents_result] = await resolve_agents(args.flags.agents)
+	const [agents_err, agents_result] = await resolve_agents(args.flags.agents, { global: is_global, project_root })
 	if (agents_err) throw e('Agent resolution failed', agents_err)
 	const { agents } = agents_result
 

package/src/commands/enable.js

@@ -57,7 +57,7 @@ const run = (args) => catch_errors('Enable failed', async () => {
 	const project_root = find_project_root()
 	const base_dir = skills_dir(is_global, project_root)
 
-	const [agents_err, agents_result] = await resolve_agents(args.flags.agents)
+	const [agents_err, agents_result] = await resolve_agents(args.flags.agents, { global: is_global, project_root })
 	if (agents_err) throw e('Agent resolution failed', agents_err)
 	const { agents } = agents_result
 

package/src/commands/init.js

@@ -109,7 +109,7 @@ const run = (args) => catch_errors('Init failed', async () => {
 
 	// Link to detected agents (non-fatal — warnings only)
 	const linked_agents = []
-	const [agents_err, agents_result] = await resolve_agents(args.flags.agents || undefined)
+	const [agents_err, agents_result] = await resolve_agents(args.flags.agents || undefined, { global: is_global, project_root })
 	if (!agents_err && agents_result?.agents?.length > 0) {
 		const [link_errs] = await link_to_agents(dir, agents_result.agents, { global: is_global, project_root, skill_name: final_name })
 		if (link_errs) {

package/src/commands/list.js

@@ -42,7 +42,7 @@ const run = (args) => catch_errors('List failed', async () => {
 	const managed_entries = Object.entries(skills)
 
 	// Resolve agents and build enabled/disabled map for managed skills
-	const [, agents_result] = await resolve_agents(args.flags.agents)
+	const [, agents_result] = await resolve_agents(args.flags.agents, { global: is_global, project_root })
 	const agents = agents_result?.agents || []
 	const managed_short_names = managed_entries.map(([k]) => k.split('/')[1])
 	const [, enabled_map] = agents.length > 0

package/src/commands/update.js

@@ -184,7 +184,7 @@ const run = (args) => catch_errors('Update failed', async () => {
 	const drifted = results.filter(r => r.status === 'drift')
 
 	// Verify and repair symlinks (even when nothing is outdated)
-	const [, agents_data] = await resolve_agents(args.flags.agents)
+	const [, agents_data] = await resolve_agents(args.flags.agents, { global: is_global, project_root })
 	const detected_agents = agents_data?.agents || []
 	let symlink_repairs = []
 	if (detected_agents.length > 0) {

package/src/constants.js

@@ -72,7 +72,8 @@ const COMMANDS = [
 	'enable',
 	'disable',
 	'versions',
-	'changelog'
+	'changelog',
+	'agents'
 ]
 
 module.exports = {

package/src/engine/installer.js

@@ -27,7 +27,7 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 	const base_dir = skills_dir(is_global, project_root)
 
 	// Resolve target agents
-	const [agents_err, agents_result] = await resolve_agents(agents_flag)
+	const [agents_err, agents_result] = await resolve_agents(agents_flag, { global: is_global, project_root })
 	if (agents_err) throw e('Agent resolution failed', agents_err)
 	const { agents } = agents_result
 	const temp_dir = tmp_dir(base_dir)

package/src/engine/uninstaller.js

@@ -23,7 +23,7 @@ const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', asyn
 	const { global: is_global = false, project_root, agents: agents_flag } = options
 
 	// Resolve target agents
-	const [agents_err, agents_result] = await resolve_agents(agents_flag)
+	const [agents_err, agents_result] = await resolve_agents(agents_flag, { global: is_global, project_root })
 	if (agents_err) throw e('Agent resolution failed', agents_err)
 	const { agents } = agents_result
 	const base_dir = skills_dir(is_global, project_root)

package/src/index.js

@@ -108,6 +108,7 @@ Commands:
   access <sub>             Manage group skill access (list, grant, revoke, set)
   enable <skill> [...]     Enable disabled skills (alias: on)
   disable <skill> [...]    Disable skills without uninstalling (alias: off)
+  agents <sub>             Configure agentic clients for this project (list, add, remove)
   login                    Authenticate with the registry
   logout                   Clear stored credentials
   whoami                   Show current user

package/src/validation/skill_md_rules.js

@@ -95,12 +95,12 @@ const validate_description = (fm) => {
 
 		if (desc.length > DESC_SOFT_CAP) {
 			results.push({
-				...result('description', 'soft_cap', 'warning', `Description is ${desc.length} chars (target: ${DESC_TARGET_MIN}-${DESC_TARGET_MAX}, soft cap: ${DESC_SOFT_CAP}). Above ${DESC_SOFT_CAP} chars usually signals a mega-skill — apply the Suite Pattern to decompose it into a core skill plus focused satellites. Run "npx happyskills audit <name>" or ask your agent "audit this skill" — happyskills-design will walk you through the Suite Decomposition Workflow.`, desc),
+				...result('description', 'soft_cap', 'warning', `Description is ${desc.length} chars (target: ${DESC_TARGET_MIN}-${DESC_TARGET_MAX}, soft cap: ${DESC_SOFT_CAP}). Above ${DESC_SOFT_CAP} chars usually signals a mega-skill — apply the Constellation Pattern to decompose it into a core skill plus focused satellites. Run "npx happyskills audit <name>" or ask your agent "audit this skill" — happyskills-design will walk you through the Constellation Decomposition Workflow.`, desc),
 				recommendations: [
-					'CANONICAL — Apply the Suite Pattern: decompose the skill into a core entry-point skill plus satellite skills, each owning one orthogonal verb cluster, bundled via the core skill.json dependencies. This is the answer once a description crosses the soft cap. happyskills-design implements the Suite Decomposition Workflow end-to-end — invoke it with "audit this skill" or "decompose this mega-skill".',
+					'CANONICAL — Apply the Constellation Pattern: decompose the skill into a core entry-point skill plus satellite skills, each owning one orthogonal verb cluster, bundled via the core skill.json dependencies. This is the answer once a description crosses the soft cap. happyskills-design implements the Constellation Decomposition Workflow end-to-end — invoke it with "audit this skill" or "decompose this mega-skill".',
 					'Alternative — Compress the description first (AUDIT/LOSSLESS/LOSSY procedure in happyskills-design references/skill-authoring.md). Buys time, but compression alone will not keep up as the API surface grows.',
 					'Alternative — Hybrid umbrella+satellites: keep one main skill for high-frequency operations, extract specialized domains into satellites.',
-					'For the canonical Suite Pattern reference (orthogonal verb ownership, the five-slot description grammar, failure modes, orthogonality test): happyskills-design references/suite-pattern.md, or docs/cli-skill.md in the HappySkills repo.'
+					'For the canonical Constellation Pattern reference (orthogonal verb ownership, the five-slot description grammar, failure modes, orthogonality test): happyskills-design references/constellation-pattern.md, or docs/cli-skill.md in the HappySkills repo.'
 				]
 			})
 		} else {