happyskills 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-04-02
+
+### Added
+- Add agent-orphan skill detection to `list` command — scans all agent-specific skill directories (`.claude/skills/`, `.cursor/skills/`, etc.) for skills placed directly in agent folders without going through HappySkills, and reports them as `agent_orphans` in JSON output or `agent-orphan (<agent>)` source in table output
+
 ## [0.26.0] - 2026-04-01
 
 ### Added

package/package.json

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

package/src/commands/list.js

@@ -2,7 +2,8 @@ const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { skills_dir, skill_install_dir, find_project_root, lock_root } = require('../config/paths')
 const { file_exists, read_json } = require('../utils/fs')
-const { scan_skills_dir } = require('../utils/skill_scanner')
+const { scan_skills_dir, scan_agent_orphan_skills } = require('../utils/skill_scanner')
+const { AGENTS } = require('../agents/registry')
 const { print_help, print_table, print_json, print_info } = require('../ui/output')
 const { exit_with_error } = require('../utils/errors')
 const { EXIT_CODES, SKILL_JSON, SKILL_TYPES } = require('../constants')
@@ -40,9 +41,14 @@ const run = (args) => catch_errors('List failed', async () => {
 	const managed_names = new Set(managed_entries.map(([k]) => k.split('/')[1]))
 	const external_skills = (disk_skills || []).filter(s => !managed_names.has(s.name))
 
-	if (managed_entries.length === 0 && external_skills.length === 0) {
+	// Scan agent-specific dirs for skills placed directly in agent folders (not symlinked from .agents/skills/)
+	const all_known_names = new Set([...managed_names, ...external_skills.map(s => s.name)])
+	const [, agent_orphans] = await scan_agent_orphan_skills(AGENTS, is_global, project_root, all_known_names)
+	const orphan_skills = agent_orphans || []
+
+	if (managed_entries.length === 0 && external_skills.length === 0 && orphan_skills.length === 0) {
 		if (args.flags.json) {
-			print_json({ data: { skills: {}, external: [] } })
+			print_json({ data: { skills: {}, external: [], agent_orphans: [] } })
 			return
 		}
 		print_info('No skills installed.')
@@ -69,7 +75,12 @@ const run = (args) => catch_errors('List failed', async () => {
 			skills_map[name] = { version: data.version, type, source, status }
 		}
 		const external = external_skills.map(s => ({ name: s.name, description: s.description || '' }))
-		print_json({ data: { skills: skills_map, external } })
+		const agent_orphan_list = orphan_skills.map(s => ({
+			name: s.name,
+			description: s.description || '',
+			agents: s.agents
+		}))
+		print_json({ data: { skills: skills_map, external, agent_orphans: agent_orphan_list } })
 		return
 	}
 
@@ -88,6 +99,11 @@ const run = (args) => catch_errors('List failed', async () => {
 		rows.push([s.name, '-', 'external', 'installed'])
 	}
 
+	for (const s of orphan_skills) {
+		const agent_label = s.agents.map(a => a.name).join(', ')
+		rows.push([s.name, '-', `agent-orphan (${agent_label})`, 'installed'])
+	}
+
 	print_table(['Skill', 'Version', 'Source', 'Status'], rows)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 

package/src/utils/skill_scanner.js

@@ -53,4 +53,80 @@ const scan_skills_dir = (base_dir) => catch_errors('Failed to scan skills direct
 	return skills
 })
 
-module.exports = { scan_skills_dir, parse_frontmatter }
+/**
+ * Scans agent-specific skill directories for skills that are NOT symlinks
+ * back to the canonical .agents/skills/ directory. These are "agent-orphan"
+ * skills — placed directly in an agent folder without going through HappySkills.
+ *
+ * @param {Array} agents - Agent definitions from the registry (AGENTS array)
+ * @param {boolean} is_global - Whether to scan global or project-level dirs
+ * @param {string} project_root - Project root path
+ * @param {Set<string>} known_names - Names already tracked (managed + external from canonical dir)
+ * @returns {[Error|null, Array<{name:string, description:string, agent_id:string, agent_name:string}>]}
+ */
+const scan_agent_orphan_skills = (agents, is_global, project_root, known_names) => catch_errors('Failed to scan agent skill directories', async () => {
+	const orphans = []
+
+	for (const agent of agents) {
+		const agent_dir = is_global
+			? path.join(require('os').homedir(), agent.global_skills_dir)
+			: path.join(project_root || process.cwd(), agent.skills_dir)
+
+		let entries
+		try {
+			entries = await fs.promises.readdir(agent_dir, { withFileTypes: true })
+		} catch {
+			continue
+		}
+
+		for (const entry of entries) {
+			if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+			if (entry.name.startsWith('.') || SKIP_ENTRIES.has(entry.name)) continue
+
+			// Skip symlinks — those are managed by HappySkills
+			if (entry.isSymbolicLink()) continue
+
+			// Skip skills already known from the canonical dir or lock file
+			if (known_names.has(entry.name)) continue
+
+			const dir = path.join(agent_dir, entry.name)
+			const skill_md_path = path.join(dir, 'SKILL.md')
+
+			let content
+			try {
+				content = await fs.promises.readFile(skill_md_path, 'utf-8')
+			} catch {
+				continue
+			}
+
+			const frontmatter = parse_frontmatter(content)
+			if (!frontmatter || !frontmatter.name) continue
+
+			orphans.push({
+				name: frontmatter.name,
+				description: frontmatter.description || '',
+				agent_id: agent.id,
+				agent_name: agent.display_name
+			})
+		}
+	}
+
+	// Deduplicate — the same skill dir name might appear in multiple agent dirs.
+	// Keep the first occurrence and collect all agent IDs.
+	const by_name = new Map()
+	for (const s of orphans) {
+		if (by_name.has(s.name)) {
+			by_name.get(s.name).agents.push({ id: s.agent_id, name: s.agent_name })
+		} else {
+			by_name.set(s.name, {
+				name: s.name,
+				description: s.description,
+				agents: [{ id: s.agent_id, name: s.agent_name }]
+			})
+		}
+	}
+
+	return [...by_name.values()]
+})
+
+module.exports = { scan_skills_dir, scan_agent_orphan_skills, parse_frontmatter }