happyskills 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-03-27
+
+### Changed
+- Move canonical skill install directory from `.claude/skills/` to `.agents/skills/` — physical files now live in an agent-neutral location, and ALL agents (including Claude Code) receive symlinks
+- Move global lock root from `~/.claude/` to `~/.agents/`
+- Remove primary/secondary agent distinction — all agents are equal, each gets a symlink from `.agents/skills/`
+
 ## [0.14.0] - 2026-03-27
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.14.0",
+	"version": "0.15.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

@@ -2,7 +2,7 @@ const fs = require('fs')
 const path = require('path')
 const os = require('os')
 const { error: { catch_errors } } = require('puffy-core')
-const { AGENTS, PRIMARY_AGENT, get_agent } = require('./registry')
+const { AGENTS, get_agent } = require('./registry')
 
 const home_dir = os.homedir()
 
@@ -34,7 +34,7 @@ const detect_agents = () => catch_errors('Agent detection failed', async () => {
  * Parse a comma-separated agent list and validate each id against the registry.
  *
  * @param {string} agents_str — e.g. "claude,cursor,windsurf"
- * @returns {{ primary: Agent, secondaries: Agent[] }}
+ * @returns {{ agents: Agent[] }}
  */
 const _parse_agents_flag = (agents_str) => {
 	const ids = agents_str.split(',').map(s => s.trim()).filter(Boolean)
@@ -51,14 +51,7 @@ const _parse_agents_flag = (agents_str) => {
 		throw new Error(`Unknown agent(s): ${unknown.join(', ')}. Available: ${AGENTS.map(a => a.id).join(', ')}`)
 	}
 
-	// Ensure primary is always included
-	if (!agents.find(a => a.primary)) {
-		agents.unshift(PRIMARY_AGENT)
-	}
-
-	const primary = agents.find(a => a.primary)
-	const secondaries = agents.filter(a => !a.primary)
-	return { primary, secondaries }
+	return { agents }
 }
 
 /**
@@ -67,10 +60,11 @@ const _parse_agents_flag = (agents_str) => {
  *   2. HAPPYSKILLS_AGENTS env var (persistent user preference)
  *   3. Auto-detection (scan home dir for agent config folders)
  *
- * Always includes the primary agent (Claude).
+ * 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, { primary: Agent, secondaries: Agent[] }]
+ * @returns {Promise} [errors, { agents: Agent[] }]
  */
 const resolve_agents = (agents_flag) => catch_errors('Agent resolution failed', async () => {
 	// 1. Explicit --agents flag takes highest priority
@@ -88,12 +82,7 @@ const resolve_agents = (agents_flag) => catch_errors('Agent resolution failed',
 	const [errors, detected] = await detect_agents()
 	if (errors) throw errors[0]
 
-	// Ensure primary is always included
-	const all = detected.find(a => a.primary) ? detected : [PRIMARY_AGENT, ...detected]
-
-	const primary = all.find(a => a.primary)
-	const secondaries = all.filter(a => !a.primary)
-	return { primary, secondaries }
+	return { agents: detected }
 })
 
 module.exports = { detect_agents, resolve_agents }

package/src/agents/index.js

@@ -1,9 +1,9 @@
-const { AGENTS, PRIMARY_AGENT, get_agent, get_all_agent_ids } = require('./registry')
+const { AGENTS, get_agent, get_all_agent_ids } = require('./registry')
 const { detect_agents, resolve_agents } = require('./detector')
 const { link_to_agents, unlink_from_agents, is_symlink } = require('./linker')
 
 module.exports = {
-	AGENTS, PRIMARY_AGENT, get_agent, get_all_agent_ids,
+	AGENTS, get_agent, get_all_agent_ids,
 	detect_agents, resolve_agents,
 	link_to_agents, unlink_from_agents, is_symlink
 }

package/src/agents/linker.js

@@ -57,19 +57,19 @@ const _link_or_copy = async (source, target) => {
 }
 
 /**
- * Link a skill to secondary agents. Creates symlinks (or copies as fallback)
- * from the primary install location to each secondary agent's skills directory.
+ * Link a skill to detected agents. Creates symlinks (or copies as fallback)
+ * from the canonical `.agents/skills/` location to each agent's skills directory.
  *
- * @param {string} source_dir — absolute path to the primary skill dir (e.g. .claude/skills/deploy-aws)
- * @param {Agent[]} secondaries — array of secondary agent objects
+ * @param {string} source_dir — absolute path to the canonical skill dir (e.g. .agents/skills/deploy-aws)
+ * @param {Agent[]} agents — array of agent objects to link
  * @param {object} options — { global, project_root, skill_name }
  * @returns {Promise} [errors, { agent_id, path, method }[]]
  */
-const link_to_agents = (source_dir, secondaries, options = {}) => catch_errors('Agent linking failed', async () => {
+const link_to_agents = (source_dir, agents, options = {}) => catch_errors('Agent linking failed', async () => {
 	const { global: is_global = false, project_root, skill_name } = options
 	const results = []
 
-	for (const agent of secondaries) {
+	for (const agent of agents) {
 		const target = agent_skill_install_dir(agent, is_global, project_root, skill_name)
 
 		// If target already exists and is a symlink pointing to source, skip
@@ -102,18 +102,18 @@ const link_to_agents = (source_dir, secondaries, options = {}) => catch_errors('
 })
 
 /**
- * Unlink a skill from secondary agents. Removes symlinks or physical copies.
+ * Unlink a skill from agents. Removes symlinks or physical copies.
  *
  * @param {string} skill_name — skill directory name (e.g. "deploy-aws")
- * @param {Agent[]} secondaries — array of secondary agent objects
+ * @param {Agent[]} agents — array of agent objects to unlink
  * @param {object} options — { global, project_root }
  * @returns {Promise} [errors, { agent_id, removed: boolean }[]]
  */
-const unlink_from_agents = (skill_name, secondaries, options = {}) => catch_errors('Agent unlinking failed', async () => {
+const unlink_from_agents = (skill_name, agents, options = {}) => catch_errors('Agent unlinking failed', async () => {
 	const { global: is_global = false, project_root } = options
 	const results = []
 
-	for (const agent of secondaries) {
+	for (const agent of agents) {
 		const target = agent_skill_install_dir(agent, is_global, project_root, skill_name)
 
 		if (!(await _exists(target))) {

package/src/agents/registry.js

@@ -1,7 +1,8 @@
 /**
  * Agent registry — pure-data definitions for supported AI agents.
  *
- * Each entry describes where an agent stores skills and how to detect it.
+ * 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.
  */
 
@@ -11,71 +12,61 @@ const AGENTS = [
 		display_name: 'Claude Code',
 		skills_dir: '.claude/skills',
 		global_skills_dir: '.claude/skills',
-		detect_paths: ['.claude'],
-		primary: true
+		detect_paths: ['.claude']
 	},
 	{
 		id: 'cursor',
 		display_name: 'Cursor',
 		skills_dir: '.cursor/skills',
 		global_skills_dir: '.cursor/skills',
-		detect_paths: ['.cursor'],
-		primary: false
+		detect_paths: ['.cursor']
 	},
 	{
 		id: 'windsurf',
 		display_name: 'Windsurf',
 		skills_dir: '.windsurf/skills',
 		global_skills_dir: '.windsurf/skills',
-		detect_paths: ['.windsurf'],
-		primary: false
+		detect_paths: ['.windsurf']
 	},
 	{
 		id: 'codex',
 		display_name: 'Codex',
 		skills_dir: '.codex/skills',
 		global_skills_dir: '.codex/skills',
-		detect_paths: ['.codex'],
-		primary: false
+		detect_paths: ['.codex']
 	},
 	{
 		id: 'copilot',
 		display_name: 'GitHub Copilot',
 		skills_dir: '.github/skills',
 		global_skills_dir: '.github/skills',
-		detect_paths: ['.github/copilot'],
-		primary: false
+		detect_paths: ['.github/copilot']
 	},
 	{
 		id: 'aider',
 		display_name: 'Aider',
 		skills_dir: '.aider/skills',
 		global_skills_dir: '.aider/skills',
-		detect_paths: ['.aider'],
-		primary: false
+		detect_paths: ['.aider']
 	},
 	{
 		id: 'cline',
 		display_name: 'Cline',
 		skills_dir: '.cline/skills',
 		global_skills_dir: '.cline/skills',
-		detect_paths: ['.cline'],
-		primary: false
+		detect_paths: ['.cline']
 	},
 	{
 		id: 'roo',
 		display_name: 'Roo Code',
 		skills_dir: '.roo/skills',
 		global_skills_dir: '.roo/skills',
-		detect_paths: ['.roo'],
-		primary: false
+		detect_paths: ['.roo']
 	}
 ]
 
-const PRIMARY_AGENT = AGENTS.find(a => a.primary)
-
 const get_agent = (id) => AGENTS.find(a => a.id === id) || null
 
 const get_all_agent_ids = () => AGENTS.map(a => a.id)
 
-module.exports = { AGENTS, PRIMARY_AGENT, get_agent, get_all_agent_ids }
+module.exports = { AGENTS, get_agent, get_all_agent_ids }

package/src/config/paths.js

@@ -14,9 +14,9 @@ const credentials_path = () => path.join(config_dir(), 'credentials.json')
 
 const log_dir = () => path.join(config_dir(), 'logs')
 
-const global_skills_dir = () => path.join(home_dir, '.claude', 'skills')
+const global_skills_dir = () => path.join(home_dir, '.agents', 'skills')
 
-const project_skills_dir = (project_root = process.cwd()) => path.join(project_root, '.claude', 'skills')
+const project_skills_dir = (project_root = process.cwd()) => path.join(project_root, '.agents', 'skills')
 
 const skills_dir = (global = false, project_root) => {
 	return global ? global_skills_dir() : project_skills_dir(project_root)
@@ -27,7 +27,7 @@ const tmp_dir = (base_skills_dir) => path.join(base_skills_dir, '.tmp')
 const install_lock_path = (base_skills_dir) => path.join(base_skills_dir, '.install.lock')
 
 const lock_root = (is_global, project_root) => {
-	return is_global ? path.join(home_dir, '.claude') : project_root
+	return is_global ? path.join(home_dir, '.agents') : project_root
 }
 
 const lock_file_path = (project_root = process.cwd()) => path.join(project_root, 'skills-lock.json')

package/src/config/paths.test.js

@@ -46,16 +46,16 @@ describe('paths', () => {
 	})
 
 	describe('global_skills_dir', () => {
-		it('returns path under home .claude/skills', () => {
+		it('returns path under home .agents/skills', () => {
 			const result = paths.global_skills_dir()
-			assert.strictEqual(result, path.join(os.homedir(), '.claude', 'skills'))
+			assert.strictEqual(result, path.join(os.homedir(), '.agents', 'skills'))
 		})
 	})
 
 	describe('project_skills_dir', () => {
 		it('returns path under project root', () => {
 			const result = paths.project_skills_dir('/my/project')
-			assert.strictEqual(result, path.join('/my/project', '.claude', 'skills'))
+			assert.strictEqual(result, path.join('/my/project', '.agents', 'skills'))
 		})
 	})
 
@@ -109,10 +109,10 @@ describe('paths', () => {
 			}
 		})
 
-		it('does not walk up to a parent with .claude/skills', () => {
+		it('does not walk up to a parent with .agents/skills', () => {
 			const tmp = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'hs-test-')))
 			try {
-				fs.mkdirSync(path.join(tmp, '.claude', 'skills'), { recursive: true })
+				fs.mkdirSync(path.join(tmp, '.agents', 'skills'), { recursive: true })
 				const sub = path.join(tmp, 'sub')
 				fs.mkdirSync(sub, { recursive: true })
 				// should return sub, not tmp

package/src/engine/installer.js

@@ -24,10 +24,10 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 	const { version, global: is_global = false, force = false, fresh = false, project_root, agents: agents_flag } = options
 	const base_dir = skills_dir(is_global, project_root)
 
-	// Resolve target agents (primary + secondaries)
+	// Resolve target agents
 	const [agents_err, agents_result] = await resolve_agents(agents_flag)
 	if (agents_err) throw e('Agent resolution failed', agents_err)
-	const { secondaries } = agents_result
+	const { agents } = agents_result
 	const temp_dir = tmp_dir(base_dir)
 	const lock_dir = lock_root(is_global, project_root)
 
@@ -136,13 +136,13 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 			await fs.promises.rename(tmp_path, final_dir)
 		}
 
-		// Link to secondary agents (non-fatal — warnings only)
-		if (secondaries.length > 0) {
-			spinner.update(`Linking to ${secondaries.length} agent(s)...`)
+		// Link to detected agents (non-fatal — warnings only)
+		if (agents.length > 0) {
+			spinner.update(`Linking to ${agents.length} agent(s)...`)
 			for (const { pkg } of downloaded) {
 				const name = pkg.skill.split('/')[1]
 				const source = skill_install_dir(base_dir, name)
-				const [link_errs] = await link_to_agents(source, secondaries, { global: is_global, project_root, skill_name: name })
+				const [link_errs] = await link_to_agents(source, agents, { global: is_global, project_root, skill_name: name })
 				if (link_errs) {
 					print_warn(`Warning: failed to link ${pkg.skill} to some agents`)
 				}
@@ -181,8 +181,8 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 
 		spinner.succeed(`Installed ${packages_to_install.length} package(s)`)
 
-		if (secondaries.length > 0) {
-			print_info(`Linked to: ${secondaries.map(a => a.display_name).join(', ')}`)
+		if (agents.length > 0) {
+			print_info(`Linked to: ${agents.map(a => a.display_name).join(', ')}`)
 		}
 
 		const [, missing_deps] = await check_system_dependencies(packages)
@@ -201,7 +201,7 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 		const warnings = _format_warnings(missing_deps)
 		const forced = forced_pkgs.map(p => ({ skill: p.skill, version: p.version }))
 
-		const linked_agents = secondaries.map(a => a.id)
+		const linked_agents = agents.map(a => a.id)
 		return { skill, version: packages[0]?.version, no_op: false, installed, skipped, warnings, forced, packages: packages_to_install.length, linked_agents }
 	} catch (err) {
 		await remove_dir(temp_dir)

package/src/engine/uninstaller.js

@@ -25,7 +25,7 @@ const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', asyn
 	// Resolve target agents
 	const [agents_err, agents_result] = await resolve_agents(agents_flag)
 	if (agents_err) throw e('Agent resolution failed', agents_err)
-	const { secondaries } = agents_result
+	const { agents } = agents_result
 	const base_dir = skills_dir(is_global, project_root)
 	const lock_dir = lock_root(is_global, project_root)
 
@@ -56,10 +56,10 @@ const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', asyn
 		if (rm_errors) throw e(`Failed to remove ${name}`, rm_errors)
 	}
 
-	// Unlink from secondary agents
-	if (secondaries.length > 0) {
+	// Unlink from detected agents
+	if (agents.length > 0) {
 		for (const name of to_remove) {
-			await unlink_from_agents(name.split('/')[1], secondaries, { global: is_global, project_root })
+			await unlink_from_agents(name.split('/')[1], agents, { global: is_global, project_root })
 		}
 	}
 

package/src/integration/cli.test.js

@@ -315,8 +315,8 @@ describe('CLI — --json: success responses use { data } envelope', () => {
 	it('init --json error when skill.json already exists returns { error }', () => {
 		const tmp = make_tmp()
 		try {
-			// Create .claude/skills/test-skill/skill.json first
-			const skill_dir = path.join(tmp, '.claude', 'skills', 'test-skill')
+			// Create .agents/skills/test-skill/skill.json first
+			const skill_dir = path.join(tmp, '.agents', 'skills', 'test-skill')
 			fs.mkdirSync(skill_dir, { recursive: true })
 			fs.writeFileSync(path.join(skill_dir, 'skill.json'), '{}')
 			const { stdout, code } = run(['init', 'test-skill', '--json'], {}, { cwd: tmp })
@@ -533,7 +533,7 @@ describe('CLI — validate command', () => {
 
 	it('exits 0 for a valid skill and reports all checks passed', () => {
 		const tmp = make_tmp()
-		const skill_dir = path.join(tmp, '.claude', 'skills', 'test-skill')
+		const skill_dir = path.join(tmp, '.agents', 'skills', 'test-skill')
 		fs.mkdirSync(skill_dir, { recursive: true })
 		fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), '---\nname: test-skill\ndescription: A valid test skill for unit testing\n---\n\n# Test Skill\n')
 		fs.writeFileSync(path.join(skill_dir, 'skill.json'), JSON.stringify({
@@ -551,7 +551,7 @@ describe('CLI — validate command', () => {
 
 	it('exits 1 for an invalid skill', () => {
 		const tmp = make_tmp()
-		const skill_dir = path.join(tmp, '.claude', 'skills', 'bad-skill')
+		const skill_dir = path.join(tmp, '.agents', 'skills', 'bad-skill')
 		fs.mkdirSync(skill_dir, { recursive: true })
 		fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), '---\nname: bad-skill\n---\n')
 		fs.writeFileSync(path.join(skill_dir, 'skill.json'), JSON.stringify({ name: 'bad-skill' }, null, '\t'))
@@ -565,7 +565,7 @@ describe('CLI — validate command', () => {
 
 	it('--json returns correct schema for a valid skill', () => {
 		const tmp = make_tmp()
-		const skill_dir = path.join(tmp, '.claude', 'skills', 'test-skill')
+		const skill_dir = path.join(tmp, '.agents', 'skills', 'test-skill')
 		fs.mkdirSync(skill_dir, { recursive: true })
 		fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), '---\nname: test-skill\ndescription: A valid test skill for unit testing\n---\n\n# Test\n')
 		fs.writeFileSync(path.join(skill_dir, 'skill.json'), JSON.stringify({
@@ -592,7 +592,7 @@ describe('CLI — validate command', () => {
 
 	it('--json returns errors for an invalid skill', () => {
 		const tmp = make_tmp()
-		const skill_dir = path.join(tmp, '.claude', 'skills', 'bad-skill')
+		const skill_dir = path.join(tmp, '.agents', 'skills', 'bad-skill')
 		fs.mkdirSync(skill_dir, { recursive: true })
 		fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), '---\nname: bad-skill\n---\n')
 		fs.writeFileSync(path.join(skill_dir, 'skill.json'), JSON.stringify({ name: 'bad-skill' }, null, '\t'))