happyskills 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ 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
+- Add merge commit support to `pull` and `publish` — when `pull` auto-merges local and remote changes without conflicts, the lock file stores `merge_parents` (the old base and remote head). On `publish`, these are sent as `parent_shas` to create a two-parent merge commit, preserving DAG history. Conflicts fall back to rebase semantics (single-parent commit). `merge_parents` is cleared after publish, on fast-forward, or when conflicts exist.
+
 ## [0.23.0] - 2026-03-30
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.23.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/api/push.js

@@ -12,13 +12,15 @@ const estimate_payload_size = (files) => {
 	return size
 }
 
-const smart_push = (owner, repo, { version, message, files, visibility, base_commit, force }, on_progress) =>
+const smart_push = (owner, repo, { version, message, files, visibility, base_commit, force, parent_shas }, on_progress) =>
 	catch_errors('Smart push failed', async () => {
 		const payload_size = estimate_payload_size(files)
 
 		if (payload_size < DIRECT_PUSH_THRESHOLD) {
 			// Small payload — use direct push
-			const [err, data] = await repos_api.push(owner, repo, { version, message, files, visibility, base_commit, force })
+			const body = { version, message, files, visibility, base_commit, force }
+			if (parent_shas) body.parent_shas = parent_shas
+			const [err, data] = await repos_api.push(owner, repo, body)
 			if (err) throw e('Direct push failed', err)
 			return data
 		}
@@ -27,9 +29,9 @@ const smart_push = (owner, repo, { version, message, files, visibility, base_com
 		const file_meta = files.map(f => ({ path: f.path, sha: f.sha, size: f.size }))
 
 		// Step 1: Initiate
-		const [init_err, init_data] = await initiate_upload(owner, repo, {
-			version, message, files: file_meta, visibility, base_commit, force
-		})
+		const init_body = { version, message, files: file_meta, visibility, base_commit, force }
+		if (parent_shas) init_body.parent_shas = parent_shas
+		const [init_err, init_data] = await initiate_upload(owner, repo, init_body)
 		if (init_err) throw e('Upload initiation failed', init_err)
 
 		const { upload_id, presigned_urls } = init_data
@@ -52,9 +54,9 @@ const smart_push = (owner, repo, { version, message, files, visibility, base_com
 		if (upload_err) throw e('File uploads failed', upload_err)
 
 		// Step 3: Complete
-		const [complete_err, complete_data] = await complete_upload(owner, repo, {
-			upload_id, version, message, files: file_meta, base_commit, force
-		})
+		const complete_body = { upload_id, version, message, files: file_meta, base_commit, force }
+		if (parent_shas) complete_body.parent_shas = parent_shas
+		const [complete_err, complete_data] = await complete_upload(owner, repo, complete_body)
 		if (complete_err) throw e('Upload completion failed', complete_err)
 
 		return complete_data

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/commands/publish.js

@@ -158,17 +158,19 @@ const run = (args) => catch_errors('Publish failed', async () => {
 		}
 	}
 
-	// Read base_commit from lock file for divergence check
+	// Read base_commit and merge_parents from lock file for divergence check
 	const full_name_pre = `${workspace.slug}/${manifest.name}`
 	const project_root = find_project_root()
 	const [lock_err, lock_data] = await read_lock(project_root)
 	let base_commit = null
+	let merge_parents = null
 	if (!lock_err && lock_data) {
 		const all_skills = get_all_locked_skills(lock_data)
 		const suffix = `/${skill_name}`
 		const lock_key = Object.keys(all_skills).find(k => k.endsWith(suffix))
 		if (lock_key && all_skills[lock_key]) {
 			base_commit = all_skills[lock_key].base_commit || null
+			merge_parents = all_skills[lock_key].merge_parents || null
 		}
 	}
 
@@ -187,14 +189,18 @@ const run = (args) => catch_errors('Publish failed', async () => {
 		spinner.update(`Uploading files (${completed}/${total})...`)
 	}
 	const visibility = args.flags.public ? 'public' : 'private'
-	const [push_err, push_data] = await smart_push(workspace.slug, manifest.name, {
+	const push_options = {
 		version: manifest.version,
 		message: `Release ${manifest.version}`,
 		files: skill_files,
 		visibility,
 		base_commit: force ? null : base_commit,
 		force
-	}, on_progress)
+	}
+	if (merge_parents && !force) {
+		push_options.parent_shas = merge_parents
+	}
+	const [push_err, push_data] = await smart_push(workspace.slug, manifest.name, push_options, on_progress)
 	if (push_err) {
 		const last = push_err[push_err.length - 1]
 		if (last?.message?.includes('diverged') || last?.message?.includes('DIVERGED')) {
@@ -226,6 +232,8 @@ const run = (args) => catch_errors('Publish failed', async () => {
 				base_integrity: (!hash_err && integrity) ? integrity : null
 			}
 			if (!hash_err && integrity) updated_entry.integrity = integrity
+			delete updated_entry.merge_parents
+			delete updated_entry.conflict_files
 			const updated_skills = update_lock_skills(lock_data, { [lock_key]: updated_entry })
 			await write_lock(project_root, updated_skills)
 		} else {

package/src/commands/pull.js

@@ -205,6 +205,8 @@ const run = (args) => catch_errors('Pull failed', async () => {
 			version: cmp_data.head_version || lock_entry.version,
 			ref: clone_data.ref || lock_entry.ref
 		}
+		delete updated_entry.merge_parents
+		delete updated_entry.conflict_files
 		const merged_skills = update_lock_skills(lock_data, { [skill_name]: updated_entry })
 		const [wl_err] = await write_lock(lock_root(is_global, project_root), merged_skills)
 		if (wl_err) { spinner.fail('Failed to write lock file'); throw wl_err[0] }
@@ -440,8 +442,10 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	}
 	if (conflict_files.length > 0) {
 		updated_entry.conflict_files = conflict_files
+		delete updated_entry.merge_parents // Conflicts → rebase fallback
 	} else {
 		delete updated_entry.conflict_files
+		updated_entry.merge_parents = [lock_entry.base_commit, cmp_data.head_commit]
 	}
 	const merged_skills = update_lock_skills(lock_data, { [skill_name]: updated_entry })
 	const [wl_err] = await write_lock(lock_root(is_global, project_root), merged_skills)

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)`))
 	}