happyskills 0.26.0 → 0.27.1

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.27.1] - 2026-04-02
+
+### Fixed
+- Fix `no_executable_code` validator producing thousands of false-positive warnings for documentation-heavy skills — rule now scans only SKILL.md, not `references/*.md` files where code blocks are expected content
+- Fix `publish` flooding stderr with one warning per line — warnings are now summarized into a single line grouped by rule (e.g., `⚠ 3 warnings: no_executable_code (2), name_match (1)`), and suppressed from stderr entirely in `--json` mode
+
+## [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.1",
 	"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/commands/publish.js

@@ -18,9 +18,10 @@ const { validate_skill_json } = require('../validation/skill_json_rules')
 const { validate_cross } = require('../validation/cross_rules')
 const { validate_no_conflict_markers } = require('../validation/conflict_marker_rules')
 const { create_spinner } = require('../ui/spinner')
-const { print_help, print_success, print_error, print_warn, print_hint, print_json, code } = require('../ui/output')
+const { print_help, print_success, print_error, print_warn, print_hint, print_json, code, summarize_warnings } = require('../ui/output')
 const { exit_with_error, UsageError, CliError } = require('../utils/errors')
 const { EXIT_CODES } = require('../constants')
+const { is_json_mode } = require('../state')
 
 const HELP_TEXT = `Usage: happyskills publish <skill-name> [options]
 
@@ -108,7 +109,6 @@ const run = (args) => catch_errors('Publish failed', async () => {
 	const validation_warnings = all_results.filter(r => r.severity === 'warning')
 
 	if (validation_errors.length > 0) {
-		const { is_json_mode } = require('../state')
 		if (is_json_mode()) {
 			const structured_errors = validation_errors.map(({ severity, ...rest }) => rest)
 			print_json({
@@ -125,8 +125,8 @@ const run = (args) => catch_errors('Publish failed', async () => {
 		throw new CliError(`Skill failed validation with ${validation_errors.length} error(s):\n  ${error_msgs.join('\n  ')}\n\nRun \`happyskills validate ${skill_name}\` for full details.`, EXIT_CODES.ERROR)
 	}
 
-	for (const w of validation_warnings) {
-		print_warn(`${w.file || 'General'}${w.field ? ` (${w.field})` : ''}: ${w.message}`)
+	if (validation_warnings.length > 0 && !is_json_mode()) {
+		print_warn(summarize_warnings(validation_warnings, skill_name))
 	}
 
 	const spinner = create_spinner('Preparing to publish...')

package/src/ui/output.js

@@ -97,6 +97,17 @@ const print_table = (headers, rows) => {
 	})
 }
 
+const summarize_warnings = (warnings, skill_name) => {
+	if (!warnings || warnings.length === 0) return null
+	const by_rule = new Map()
+	for (const w of warnings) {
+		const key = w.rule || 'unknown'
+		by_rule.set(key, (by_rule.get(key) || 0) + 1)
+	}
+	const parts = [...by_rule.entries()].map(([rule, count]) => `${rule} (${count})`)
+	return `${warnings.length} warning${warnings.length === 1 ? '' : 's'}: ${parts.join(', ')} — run 'happyskills validate ${skill_name}' for details`
+}
+
 const print_json = (data) => {
 	console.log(JSON.stringify(data, null, 2))
 }
@@ -105,4 +116,4 @@ const print_label = (label, value) => {
 	console.log(`${gray(label + ':')} ${value}`)
 }
 
-module.exports = { print_success, print_error, print_warn, print_info, print_hint, print_help, print_table, print_json, print_label, code, format_help, visible_len, ansi_pad, truncate }
+module.exports = { print_success, print_error, print_warn, print_info, print_hint, print_help, print_table, print_json, print_label, code, format_help, visible_len, ansi_pad, truncate, summarize_warnings }

package/src/ui/output.test.js

@@ -2,7 +2,7 @@
 const { describe, it, before, after, beforeEach, afterEach } = require('node:test')
 const assert = require('node:assert/strict')
 
-const { visible_len, ansi_pad, truncate, format_help, print_table } = require('./output')
+const { visible_len, ansi_pad, truncate, format_help, print_table, summarize_warnings } = require('./output')
 
 // ─── visible_len ─────────────────────────────────────────────────────────────
 
@@ -182,6 +182,53 @@ describe('print_table', () => {
 	})
 })
 
+// ─── summarize_warnings ──────────────────────────────────────────────────────
+
+describe('summarize_warnings', () => {
+	it('returns null for empty array', () => {
+		assert.strictEqual(summarize_warnings([], 'my-skill'), null)
+	})
+
+	it('returns null for null/undefined input', () => {
+		assert.strictEqual(summarize_warnings(null, 'my-skill'), null)
+		assert.strictEqual(summarize_warnings(undefined, 'my-skill'), null)
+	})
+
+	it('uses singular "warning" for a single warning', () => {
+		const warnings = [{ rule: 'name_match', message: 'names differ' }]
+		const result = summarize_warnings(warnings, 'my-skill')
+		assert.ok(result.startsWith('1 warning:'))
+		assert.ok(result.includes('name_match (1)'))
+		assert.ok(result.includes("'happyskills validate my-skill'"))
+	})
+
+	it('uses plural "warnings" for multiple warnings', () => {
+		const warnings = [
+			{ rule: 'no_executable_code', message: 'found code block' },
+			{ rule: 'no_executable_code', message: 'found another block' },
+			{ rule: 'name_match', message: 'names differ' }
+		]
+		const result = summarize_warnings(warnings, 'deploy-aws')
+		assert.ok(result.startsWith('3 warnings:'))
+		assert.ok(result.includes('no_executable_code (2)'))
+		assert.ok(result.includes('name_match (1)'))
+		assert.ok(result.includes("'happyskills validate deploy-aws'"))
+	})
+
+	it('groups by rule and counts correctly', () => {
+		const warnings = Array.from({ length: 100 }, () => ({ rule: 'no_executable_code', message: 'x' }))
+		const result = summarize_warnings(warnings, 'big-skill')
+		assert.ok(result.startsWith('100 warnings:'))
+		assert.ok(result.includes('no_executable_code (100)'))
+	})
+
+	it('falls back to "unknown" for warnings without a rule field', () => {
+		const warnings = [{ message: 'something' }]
+		const result = summarize_warnings(warnings, 'my-skill')
+		assert.ok(result.includes('unknown (1)'))
+	})
+})
+
 // ─── json mode silencing ──────────────────────────────────────────────────────
 
 describe('print_success / print_info / print_hint — json mode silencing', () => {

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 }

package/src/validation/cross_rules.js

@@ -1,5 +1,3 @@
-const fs = require('fs')
-const path = require('path')
 const { error: { catch_errors } } = require('puffy-core')
 const { SKILL_TYPES } = require('../constants')
 
@@ -61,20 +59,6 @@ const validate_cross = (skill_dir, frontmatter, manifest, skill_md_content, skil
 		results.push(...scan_code_blocks(skill_md_content, 'SKILL.md'))
 	}
 
-	// Executable code in references/*.md
-	const refs_dir = path.join(skill_dir, 'references')
-	try {
-		const entries = await fs.promises.readdir(refs_dir, { withFileTypes: true })
-		for (const entry of entries) {
-			if (!entry.isFile() || !entry.name.endsWith('.md')) continue
-			const ref_path = path.join(refs_dir, entry.name)
-			const ref_content = await fs.promises.readFile(ref_path, 'utf-8')
-			results.push(...scan_code_blocks(ref_content, `references/${entry.name}`))
-		}
-	} catch {
-		// No references dir — that's fine
-	}
-
 	return results
 })
 

package/src/validation/cross_rules.test.js

@@ -89,7 +89,7 @@ describe('validate_cross — executable code detection', () => {
 		assert.ok(!results.some(r => r.rule === 'no_executable_code'))
 	})
 
-	it('warns for executable code in references/*.md', async () => {
+	it('does not scan references/*.md for executable code', async () => {
 		const refs_dir = path.join(tmp, 'references')
 		fs.mkdirSync(refs_dir)
 		const code = '```bash\n#!/bin/bash\nimport os\nset -e\necho "deploy"\n' + 'echo "step"\n'.repeat(8) + '```'
@@ -97,14 +97,6 @@ describe('validate_cross — executable code detection', () => {
 
 		const [err, results] = await validate_cross(tmp, { name: 'x' }, { name: 'x' }, '')
 		assert.ifError(err)
-		const check = results.find(r => r.rule === 'no_executable_code' && r.file === 'references/deploy.md')
-		assert.strictEqual(check.severity, 'warning')
-	})
-
-	it('does not error when references dir is missing', async () => {
-		const [err, results] = await validate_cross(tmp, { name: 'x' }, { name: 'x' }, '')
-		assert.ifError(err)
-		// Should not throw or produce error results — just no code block warnings
-		assert.ok(!results.some(r => r.severity === 'error'))
+		assert.ok(!results.some(r => r.rule === 'no_executable_code'))
 	})
 })