happyskills 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-03-30
+
+### Added
+- Add `--agents` flag to `init` and `convert` commands for explicit agent targeting, matching `install` behavior
+- Add `recommendations` array to `validate` description max_length error — provides a 4-step procedure (audit, lossless compression, lossy compression, verify) for safely shortening descriptions without breaking auto-invocation triggers
+
+### Fixed
+- Fix `init` not creating symlinks to secondary agents (Cursor, Windsurf, Codex, etc.) — newly scaffolded skills now use the same multi-agent linking as `install`
+- Fix `convert` not creating symlinks to secondary agents — converted skills now get symlinked to all detected agents
+
 ## [0.24.0] - 2026-03-30
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.24.0",
+	"version": "0.25.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/convert.js

@@ -13,6 +13,7 @@ const { write_lock, update_lock_skills } = require('../lock/writer')
 const { hash_directory } = require('../lock/integrity')
 const { skills_dir, find_project_root, lock_root } = require('../config/paths')
 const { file_exists } = require('../utils/fs')
+const { resolve_agents, link_to_agents } = require('../agents')
 const { create_spinner } = require('../ui/spinner')
 const { print_help, print_success, print_error, print_info, print_warn, print_label, print_json } = require('../ui/output')
 const { exit_with_error, UsageError, CliError } = require('../utils/errors')
@@ -26,10 +27,12 @@ Arguments:
   skill-name            Name of the skill in .claude/skills/
 
 Options:
-  -g, --global          Look in global skills (~/.claude/skills/)
+  -g, --global          Look in global skills (~/.agents/skills/)
   --workspace <slug>    Target workspace (if you have multiple)
   --version <ver>       Initial version (default: 1.0.0)
   --keywords <tags>     Comma-separated keywords (e.g., "deploy,aws,iac")
+  --agents <list>       Target specific agents (comma-separated, e.g., claude,cursor)
+                        Default: auto-detect. Env: HAPPYSKILLS_AGENTS
   -y, --yes             Skip confirmation prompt
 
 Examples:
@@ -190,8 +193,25 @@ const run = (args) => catch_errors('Convert failed', async () => {
 	const [lock_err] = await write_lock(lock_dir, new_skills)
 	if (lock_err) { pub_spinner.fail('Failed to write lock file'); throw e('Lock write failed', lock_err) }
 
+	// Link to detected agents (non-fatal — warnings only)
+	const linked_agents = []
+	const [agents_err, agents_result] = await resolve_agents(args.flags.agents || undefined)
+	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 })
+		if (link_errs) {
+			print_warn(`Warning: failed to link ${skill_name} to some agents`)
+		} else {
+			linked_agents.push(...agents_result.agents.map(a => a.id))
+		}
+	}
+
 	pub_spinner.succeed(`Converted ${full_name}@${merged_version}`)
 
+	if (linked_agents.length > 0) {
+		print_info(`Linked to: ${agents_result.agents.map(a => a.display_name).join(', ')}`)
+	}
+
 	if (args.flags.json) {
 		const json_data = {
 			skill: full_name,
@@ -199,6 +219,7 @@ const run = (args) => catch_errors('Convert failed', async () => {
 			workspace: workspace.slug,
 			description: merged_description || ''
 		}
+		if (linked_agents.length > 0) json_data.linked_agents = linked_agents
 		if (frontmatter_warnings.length > 0) json_data.warnings = frontmatter_warnings
 		print_json({ data: json_data })
 		return

package/src/commands/init.js

@@ -2,26 +2,29 @@ const path = require('path')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { write_manifest } = require('../manifest/writer')
 const { write_file, file_exists, ensure_dir } = require('../utils/fs')
-const { print_success, print_error, print_help, print_hint, print_json, code } = require('../ui/output')
+const { print_success, print_error, print_help, print_hint, print_json, print_info, print_warn, code } = require('../ui/output')
 const { exit_with_error, CliError, UsageError } = require('../utils/errors')
 const { SKILL_JSON, SKILL_MD, EXIT_CODES, SKILL_TYPES, KIT_PREFIX } = require('../constants')
 const { find_project_root, skills_dir } = require('../config/paths')
+const { resolve_agents, link_to_agents } = require('../agents')
 
 const HELP_TEXT = `Usage: happyskills init <name> [options]
 
-Scaffold a new skill in .claude/skills/<name>/.
+Scaffold a new skill in .agents/skills/<name>/.
 
 Creates:
-  .claude/skills/<name>/skill.json    Skill manifest (name, version, deps)
-  .claude/skills/<name>/SKILL.md      Skill instructions for AI agents
+  .agents/skills/<name>/skill.json    Skill manifest (name, version, deps)
+  .agents/skills/<name>/SKILL.md      Skill instructions for AI agents
 
 Arguments:
   name          Skill name (required, e.g., my-deploy-skill)
 
 Options:
-  -g, --global  Create in global skills (~/.claude/skills/)
-  --kit         Initialize as a kit (collection of skills)
-  --json        Output as JSON
+  -g, --global    Create in global skills (~/.agents/skills/)
+  --kit           Initialize as a kit (collection of skills)
+  --agents <list> Target specific agents (comma-separated, e.g., claude,cursor)
+                  Default: auto-detect. Env: HAPPYSKILLS_AGENTS
+  --json          Output as JSON
 
 Examples:
   happyskills init my-deploy-skill
@@ -104,14 +107,31 @@ const run = (args) => catch_errors('Init failed', async () => {
 
 	const label = is_kit ? 'kit' : 'skill'
 
+	// Link to detected agents (non-fatal — warnings only)
+	const linked_agents = []
+	const [agents_err, agents_result] = await resolve_agents(args.flags.agents || undefined)
+	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) {
+			print_warn(`Warning: failed to link ${final_name} to some agents`)
+		} else {
+			linked_agents.push(...agents_result.agents.map(a => a.id))
+		}
+	}
+
 	if (args.flags.json) {
-		print_json({ data: { name: final_name, type: is_kit ? SKILL_TYPES.KIT : SKILL_TYPES.SKILL, files_created, directory: dir } })
+		const data = { name: final_name, type: is_kit ? SKILL_TYPES.KIT : SKILL_TYPES.SKILL, files_created, directory: dir }
+		if (linked_agents.length > 0) data.linked_agents = linked_agents
+		print_json({ data })
 		return
 	}
 
 	print_success(`Initialized ${label} "${final_name}" at ${dir}`)
 	console.log(`  ${SKILL_JSON}  — manifest`)
 	console.log(`  ${SKILL_MD}    — ${is_kit ? 'kit description' : 'instructions'}`)
+	if (linked_agents.length > 0) {
+		print_info(`Linked to: ${agents_result.agents.map(a => a.display_name).join(', ')}`)
+	}
 	console.log()
 	print_hint(`Edit these files, then run ${code('happyskills publish')} to share.`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })

package/src/validation/skill_md_rules.js

@@ -74,7 +74,19 @@ const validate_description = (fm) => {
 	}
 
 	if (desc.length > 1024) {
-		results.push(result('description', 'max_length', 'error', `Description is ${desc.length} chars (max 1024)`, desc))
+		const deficit = desc.length - 1024
+		results.push({
+			...result('description', 'max_length', 'error', `Description is ${desc.length} chars (max 1024). Must reduce by ${deficit} chars.`, desc),
+			recommendations: [
+				'STEP 1 - AUDIT: Before changing anything, read the skill\'s routing table or capability list. Map each phrase in the description to the capability it triggers. Mark each phrase as: IDENTITY (describes what the skill is, usually one phrase), UNIQUE (the only phrase matching a specific capability), or REINFORCING (overlaps with another phrase\'s coverage).',
+				'STEP 2 - LOSSLESS COMPRESSION: Apply these transformations that reduce characters without changing semantic meaning: (a) Remove articles (a, an, the). (b) Remove possessives (my, your) when the subject is implied. (c) Remove filler verbs (do, does, can, have, is, am). (d) Merge parallel structures that share the same verb (e.g., \'install kit. publish kit\' becomes \'install, publish kits\') or the same object (e.g., \'find kits, search kits\' becomes \'find, search kits\'). Stop here if now under the limit.',
+				'STEP 3 - LOSSY COMPRESSION (only if still over the limit after step 2): Remove REINFORCING phrases only. When two phrases overlap semantically, remove the more general one and keep the more specific one. In synonym clusters, keep the two most commonly used verbs and remove the rest.',
+				'NEVER remove an IDENTITY phrase — it anchors the understanding of the skill\'s purpose and provides context for all other trigger phrases.',
+				'NEVER remove a UNIQUE trigger phrase — it is the only semantic path to that capability. Removing it makes that capability unreachable via auto-invocation.',
+				'NEVER rephrase a trigger in a way that changes the core verb or noun (e.g., \'how many skills installed\' must not become \'skill count\'). The original phrasing matches how users naturally speak.',
+				'STEP 4 - VERIFY: Cross-check the shortened description against the skill\'s routing table or capability list. Every documented capability must still have at least one semantically matching phrase in the description. If any capability lost coverage, restore its trigger phrase and find different savings.'
+			]
+		})
 	} else {
 		results.push(result('description', 'max_length', 'pass', `Description: ${desc.length} chars (max 1024)`))
 	}