happyskills 0.39.1 → 0.41.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.41.0] - 2026-05-04
+
+### Added
+- Add `versions` command — list every published version of a skill, newest first. Useful for deciding which version to install when the latest is not always the right pick. Supports `--limit <n>` and `--json`. Backed by the existing `GET /repos/:owner/:repo/refs` endpoint, so the same access rules apply (public skills require no auth; private/workspace skills require read access).
+- Add `changelog` command — print a skill's `CHANGELOG.md` as it exists at the latest version, or at a specific version with `--version <ver>`. Useful for reasoning about when a feature shipped before pinning to an older release. Falls back to a synthesized changelog built from registry release messages when the skill has no `CHANGELOG.md`. Supports `--json`. Resolves the file via `GET /tree?ref=...` + `GET /blob/:sha`, both of which enforce read access server-side.
+- Add 250-char description soft-cap warning to `validate` for `SKILL.md`. Above the soft cap, the warning recommends decomposing the skill into a focused family or applying the AUDIT/LOSSLESS/LOSSY compression procedure — flags mega-skill descriptions before they hit the registry.
+
+## [0.40.0] - 2026-05-03
+
+### Added
+- Propagate the fork relationship to the server on the first `publish` after `happyskills fork`. The CLI now reads `manifest.forked_from.repo` (an `owner/name` string written by the fork command), splits it into `{ workspace, name }`, and includes it in the push payload across all three transport modes: direct push, archive upload, and per-file presigned upload. The API resolves the parent and persists `repos.forked_from`, which feeds the duplicate-detection heuristic (forks-of-active-parents are ineligible to be elected source-of-truth, and the publish-time `duplicates` warning is suppressed when the only match is the fork's parent). Subsequent publishes of an existing repo are unaffected — the field is honored only on the create-repo path. Requires API ≥ 2.4.0.
+
+### Fixed
+- Fix `publish` crashing with a `ReferenceError`/TDZ on `visibility` when validation runs before the spinner update — the `const visibility = args.flags.public ? 'public' : 'private'` declaration was below its first use. Move the declaration ahead of all reads.
+- Fix `validate_manifest` rejecting kit names like `_kit-foo` ("Invalid name … Must start with a letter or number"). Kits are required by `init --kit` and `validate_skill_json` to start with `_kit-`, so the leading-character rule is now carved out for `manifest.type === 'kit'` via a separate `KIT_NAME_PATTERN`. Bumping a kit no longer fails its own pre-publish manifest validation.
+
 ## [0.39.1] - 2026-05-01
 
 ### Fixed

package/package.json

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

@@ -13,7 +13,7 @@ const estimate_payload_size = (files) => {
 	return size
 }
 
-const archive_push = (owner, repo, { version, message, files, visibility, base_commit, force, parent_shas, source_dir }, on_progress) =>
+const archive_push = (owner, repo, { version, message, files, visibility, base_commit, force, parent_shas, forked_from, source_dir }, on_progress) =>
 	catch_errors('Archive push failed', async () => {
 		const file_meta = files.map(f => ({ path: f.path, sha: f.sha, size: f.size }))
 
@@ -28,6 +28,7 @@ const archive_push = (owner, repo, { version, message, files, visibility, base_c
 				archive: true, archive_sha: archive.sha, archive_size: archive.size
 			}
 			if (parent_shas) init_body.parent_shas = parent_shas
+			if (forked_from) init_body.forked_from = forked_from
 			const [init_err, init_data] = await initiate_upload(owner, repo, init_body)
 			if (init_err) throw e('Upload initiation failed', init_err)
 
@@ -44,6 +45,7 @@ const archive_push = (owner, repo, { version, message, files, visibility, base_c
 				version, message, files: file_meta, base_commit, force
 			}
 			if (parent_shas) complete_body.parent_shas = parent_shas
+			if (forked_from) complete_body.forked_from = forked_from
 			const [complete_err, complete_data] = await complete_upload(owner, repo, complete_body)
 			if (complete_err) throw e('Upload completion failed', complete_err)
 
@@ -62,7 +64,7 @@ const archive_push = (owner, repo, { version, message, files, visibility, base_c
 		}
 	})
 
-const smart_push = (owner, repo, { version, message, files, visibility, base_commit, force, parent_shas, source_dir }, on_progress) =>
+const smart_push = (owner, repo, { version, message, files, visibility, base_commit, force, parent_shas, forked_from, source_dir }, on_progress) =>
 	catch_errors('Smart push failed', async () => {
 		const payload_size = estimate_payload_size(files)
 
@@ -70,6 +72,7 @@ const smart_push = (owner, repo, { version, message, files, visibility, base_com
 			// Small payload — use direct push
 			const body = { version, message, files, visibility, base_commit, force }
 			if (parent_shas) body.parent_shas = parent_shas
+			if (forked_from) body.forked_from = forked_from
 			const [err, data] = await repos_api.push(owner, repo, body)
 			if (err) throw e('Direct push failed', err)
 			return data
@@ -77,7 +80,7 @@ const smart_push = (owner, repo, { version, message, files, visibility, base_com
 
 		// Large payload — prefer archive upload if source_dir is available
 		if (source_dir) {
-			return await archive_push(owner, repo, { version, message, files, visibility, base_commit, force, parent_shas, source_dir }, on_progress)
+			return await archive_push(owner, repo, { version, message, files, visibility, base_commit, force, parent_shas, forked_from, source_dir }, on_progress)
 		}
 
 		// Fallback: per-file presigned upload
@@ -86,6 +89,7 @@ const smart_push = (owner, repo, { version, message, files, visibility, base_com
 		// Step 1: Initiate
 		const init_body = { version, message, files: file_meta, visibility, base_commit, force }
 		if (parent_shas) init_body.parent_shas = parent_shas
+		if (forked_from) init_body.forked_from = forked_from
 		const [init_err, init_data] = await initiate_upload(owner, repo, init_body)
 		if (init_err) throw e('Upload initiation failed', init_err)
 
@@ -111,6 +115,7 @@ const smart_push = (owner, repo, { version, message, files, visibility, base_com
 		// Step 3: Complete
 		const complete_body = { upload_id, version, message, files: file_meta, base_commit, force }
 		if (parent_shas) complete_body.parent_shas = parent_shas
+		if (forked_from) complete_body.forked_from = forked_from
 		const [complete_err, complete_data] = await complete_upload(owner, repo, complete_body)
 		if (complete_err) throw e('Upload completion failed', complete_err)
 

package/src/api/repos.js

@@ -80,6 +80,13 @@ const get_blob = (owner, repo, sha) => catch_errors(`Get blob ${owner}/${repo}/$
 	return data
 })
 
+const get_tree = (owner, repo, ref) => catch_errors(`Get tree for ${owner}/${repo} failed`, async () => {
+	const qs = ref ? `?ref=${encodeURIComponent(ref)}` : ''
+	const [errors, data] = await client.get(`/repos/${owner}/${repo}/tree${qs}`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
 const semantic_search = (query, options = {}) => catch_errors('Semantic search failed', async () => {
 	const body = {
 		q: query,
@@ -98,4 +105,4 @@ const semantic_search = (query, options = {}) => catch_errors('Semantic search f
 	return data
 })
 
-module.exports = { search, semantic_search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates, del_repo, patch_repo, compare, get_blob }
+module.exports = { search, semantic_search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates, del_repo, patch_repo, compare, get_blob, get_tree }

package/src/commands/changelog.js

@@ -0,0 +1,125 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { get_refs, get_tree, get_blob } = require('../api/repos')
+const { print_help, print_json, print_info } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+const { extract_version, sort_refs } = require('./versions')
+
+const HELP_TEXT = `Usage: happyskills changelog <owner/name> [options]
+
+Print a skill's CHANGELOG.md as it exists at the latest version (or at a
+specific version with --version).
+
+If the skill has no CHANGELOG.md file, a synthesized changelog is generated
+from the registry's release messages.
+
+Arguments:
+  owner/name        Skill identifier (e.g., acme/deploy-aws)
+
+Options:
+  --version <ver>   Read the changelog at this specific version (default: latest)
+  --json            Output as JSON
+
+Examples:
+  happyskills changelog acme/deploy-aws
+  happyskills changelog acme/deploy-aws --version 1.2.0
+  happyskills changelog acme/deploy-aws --json`
+
+const CHANGELOG_FILENAMES = ['CHANGELOG.md', 'changelog.md', 'CHANGELOG', 'Changelog.md']
+
+const find_changelog_entry = (entries) => {
+	if (!Array.isArray(entries)) return null
+	for (const name of CHANGELOG_FILENAMES) {
+		const hit = entries.find(e => e.path === name)
+		if (hit) return hit
+	}
+	return null
+}
+
+const synthesize_from_refs = (refs, skill) => {
+	const sorted = sort_refs(refs)
+	const lines = [`# Changelog — ${skill}`, '']
+	lines.push('_This skill has no CHANGELOG.md file. The entries below are synthesized from registry release messages._', '')
+	for (const r of sorted) {
+		const version = extract_version(r.name)
+		const date = r.created_at ? r.created_at.slice(0, 10) : ''
+		lines.push(`## ${version}${date ? ` — ${date}` : ''}`)
+		lines.push('')
+		lines.push(r.message || '_(no release message)_')
+		lines.push('')
+	}
+	return lines.join('\n')
+}
+
+const normalize_ref = (version_str) => {
+	if (!version_str) return null
+	if (version_str.startsWith('refs/')) return version_str
+	return `refs/tags/v${version_str.replace(/^v/, '')}`
+}
+
+const run = (args) => catch_errors('Changelog failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const skill = args._[0]
+	if (!skill) {
+		throw new UsageError('Please specify a skill (e.g., happyskills changelog acme/deploy-aws).')
+	}
+	if (!skill.includes('/')) {
+		throw new UsageError('Skill must be in owner/name format (e.g., acme/deploy-aws).')
+	}
+
+	const [owner, name] = skill.split('/')
+	const requested_version = args.flags.version && args.flags.version !== true
+		? String(args.flags.version)
+		: null
+	const requested_ref = normalize_ref(requested_version)
+
+	const [tree_err, tree] = await get_tree(owner, name, requested_ref)
+	if (tree_err) throw tree_err[tree_err.length - 1]
+
+	const resolved_ref = tree.ref
+	const resolved_version = extract_version(resolved_ref)
+	const resolved_commit = tree.commit
+
+	const entry = find_changelog_entry(tree.entries)
+
+	let content
+	let synthesized = false
+
+	if (entry) {
+		const [blob_err, blob] = await get_blob(owner, name, entry.sha)
+		if (blob_err) throw blob_err[blob_err.length - 1]
+		content = Buffer.from(blob.content || '', 'base64').toString('utf8')
+	} else {
+		const [refs_err, refs] = await get_refs(owner, name)
+		if (refs_err) throw refs_err[refs_err.length - 1]
+		content = synthesize_from_refs(refs, skill)
+		synthesized = true
+	}
+
+	if (args.flags.json) {
+		print_json({
+			data: {
+				skill,
+				version: resolved_version,
+				ref: resolved_ref,
+				commit: resolved_commit,
+				synthesized,
+				content
+			}
+		})
+		return
+	}
+
+	if (synthesized) {
+		print_info(`No CHANGELOG.md in ${skill}@${resolved_version} — showing release messages from the registry.`)
+		process.stdout.write('\n')
+	}
+	process.stdout.write(content)
+	if (!content.endsWith('\n')) process.stdout.write('\n')
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run, find_changelog_entry, synthesize_from_refs, normalize_ref }

package/src/commands/changelog.test.js

@@ -0,0 +1,69 @@
+'use strict'
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const { find_changelog_entry, synthesize_from_refs, normalize_ref } = require('./changelog')
+
+describe('changelog — find_changelog_entry', () => {
+	it('finds CHANGELOG.md (canonical case)', () => {
+		const entries = [
+			{ path: 'SKILL.md', sha: 'a' },
+			{ path: 'CHANGELOG.md', sha: 'b' }
+		]
+		assert.strictEqual(find_changelog_entry(entries).sha, 'b')
+	})
+
+	it('falls back to lowercase variant', () => {
+		const entries = [{ path: 'changelog.md', sha: 'c' }]
+		assert.strictEqual(find_changelog_entry(entries).sha, 'c')
+	})
+
+	it('returns null when no changelog file present', () => {
+		const entries = [{ path: 'SKILL.md', sha: 'a' }]
+		assert.strictEqual(find_changelog_entry(entries), null)
+	})
+
+	it('handles non-array input safely', () => {
+		assert.strictEqual(find_changelog_entry(null), null)
+	})
+})
+
+describe('changelog — normalize_ref', () => {
+	it('returns null for empty input', () => {
+		assert.strictEqual(normalize_ref(null), null)
+		assert.strictEqual(normalize_ref(''), null)
+	})
+
+	it('passes through full refs', () => {
+		assert.strictEqual(normalize_ref('refs/tags/v1.2.0'), 'refs/tags/v1.2.0')
+	})
+
+	it('wraps plain semver into a tag ref', () => {
+		assert.strictEqual(normalize_ref('1.2.0'), 'refs/tags/v1.2.0')
+	})
+
+	it('strips leading v before re-wrapping', () => {
+		assert.strictEqual(normalize_ref('v1.2.0'), 'refs/tags/v1.2.0')
+	})
+})
+
+describe('changelog — synthesize_from_refs', () => {
+	it('produces sections newest first with version + date headings', () => {
+		const refs = [
+			{ name: 'refs/tags/v1.0.0', created_at: '2026-01-01T00:00:00Z', message: 'Initial release' },
+			{ name: 'refs/tags/v1.1.0', created_at: '2026-02-01T00:00:00Z', message: 'Add feature X' }
+		]
+		const out = synthesize_from_refs(refs, 'acme/foo')
+		assert.ok(out.includes('# Changelog — acme/foo'))
+		assert.ok(out.includes('## 1.1.0 — 2026-02-01'))
+		assert.ok(out.includes('Add feature X'))
+		const idx_new = out.indexOf('## 1.1.0')
+		const idx_old = out.indexOf('## 1.0.0')
+		assert.ok(idx_new < idx_old, 'newest version should come first')
+	})
+
+	it('falls back to placeholder when message is empty', () => {
+		const refs = [{ name: 'refs/tags/v1.0.0', created_at: null, message: null }]
+		const out = synthesize_from_refs(refs, 'acme/foo')
+		assert.ok(out.includes('_(no release message)_'))
+	})
+})

package/src/commands/publish.js

@@ -135,6 +135,8 @@ const run = (args) => catch_errors('Publish failed', async () => {
 
 	const spinner = create_spinner('Preparing to publish...')
 
+	const visibility = args.flags.public ? 'public' : 'private'
+
 	let owner = args.flags.workspace
 	if (!owner) {
 		const [, resolved_owner] = await resolve_skill_owner(skill_name)
@@ -221,7 +223,6 @@ const run = (args) => catch_errors('Publish failed', async () => {
 			spinner.update(`Uploading files (${completed}/${total})...`)
 		}
 	}
-	const visibility = args.flags.public ? 'public' : 'private'
 	const push_options = {
 		version: manifest.version,
 		message: `Release ${manifest.version}`,
@@ -234,6 +235,15 @@ const run = (args) => catch_errors('Publish failed', async () => {
 	if (merge_parents && !force) {
 		push_options.parent_shas = merge_parents
 	}
+
+	// Propagate fork relationship to the server on the first publish.
+	// Only the create-repo path uses this; existing repos already have forked_from set.
+	if (manifest.forked_from && typeof manifest.forked_from.repo === 'string' && manifest.forked_from.repo.includes('/')) {
+		const [parent_workspace, parent_name] = manifest.forked_from.repo.split('/')
+		if (parent_workspace && parent_name) {
+			push_options.forked_from = { workspace: parent_workspace, name: parent_name }
+		}
+	}
 	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]

package/src/commands/publish.test.js

@@ -0,0 +1,21 @@
+const { describe, it } = require('node:test')
+const assert = require('node:assert')
+const fs = require('node:fs')
+const path = require('node:path')
+
+describe('publish.js — Bug 1 regression: visibility temporal-dead-zone', () => {
+	const src = fs.readFileSync(path.join(__dirname, 'publish.js'), 'utf8')
+
+	it('declares `visibility` before passing it to validate_dependencies', () => {
+		const decl_idx = src.search(/const\s+visibility\s*=\s*args\.flags\.public/)
+		const use_idx = src.search(/validate_dependencies\([\s\S]*?visibility/)
+		assert.notStrictEqual(decl_idx, -1, '`const visibility = args.flags.public ? ...` declaration not found')
+		assert.notStrictEqual(use_idx, -1, '`validate_dependencies(... visibility ...)` call not found')
+		assert.ok(
+			decl_idx < use_idx,
+			`visibility must be declared (idx ${decl_idx}) before it is read inside validate_dependencies (idx ${use_idx}). ` +
+			'The current ordering causes `ReferenceError: Cannot access \'visibility\' before initialization` ' +
+			'whenever skill.json declares one or more dependencies.'
+		)
+	})
+})

package/src/commands/versions.js

@@ -0,0 +1,92 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { get_refs } = require('../api/repos')
+const { print_help, print_table, print_json, print_info } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills versions <owner/name> [options]
+
+List all published versions of a skill, newest first.
+
+Arguments:
+  owner/name        Skill identifier (e.g., acme/deploy-aws)
+
+Options:
+  --limit <n>       Limit the number of versions shown (default: all)
+  --json            Output as JSON
+
+Examples:
+  happyskills versions acme/deploy-aws
+  happyskills versions acme/deploy-aws --limit 20
+  happyskills versions acme/deploy-aws --json`
+
+const extract_version = (ref_name) => {
+	const m = (ref_name || '').match(/^refs\/tags\/v?(.+)$/)
+	return m ? m[1] : ref_name
+}
+
+const sort_refs = (refs) => {
+	const copy = [...(refs || [])]
+	copy.sort((a, b) => {
+		const ta = a.created_at ? Date.parse(a.created_at) : 0
+		const tb = b.created_at ? Date.parse(b.created_at) : 0
+		return tb - ta
+	})
+	return copy
+}
+
+const run = (args) => catch_errors('Versions failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const skill = args._[0]
+	if (!skill) {
+		throw new UsageError('Please specify a skill (e.g., happyskills versions acme/deploy-aws).')
+	}
+	if (!skill.includes('/')) {
+		throw new UsageError('Skill must be in owner/name format (e.g., acme/deploy-aws).')
+	}
+
+	const limit = args.flags.limit ? parseInt(args.flags.limit, 10) : null
+	if (args.flags.limit && (Number.isNaN(limit) || limit < 1)) {
+		throw new UsageError('--limit must be a positive integer.')
+	}
+
+	const [owner, name] = skill.split('/')
+
+	const [errors, refs] = await get_refs(owner, name)
+	if (errors) throw errors[errors.length - 1]
+
+	const sorted = sort_refs(refs)
+	const limited = limit ? sorted.slice(0, limit) : sorted
+
+	const versions = limited.map(r => ({
+		version: extract_version(r.name),
+		ref: r.name,
+		commit: r.sha,
+		message: r.message || '',
+		published_at: r.created_at || null
+	}))
+
+	if (args.flags.json) {
+		print_json({ data: { skill, count: versions.length, versions } })
+		return
+	}
+
+	if (versions.length === 0) {
+		print_info(`No versions published for ${skill}.`)
+		return
+	}
+
+	const rows = versions.map(v => [
+		v.version,
+		v.published_at ? v.published_at.slice(0, 10) : '-',
+		(v.commit || '').slice(0, 7),
+		v.message
+	])
+	print_table(['VERSION', 'PUBLISHED', 'COMMIT', 'MESSAGE'], rows)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run, extract_version, sort_refs }

package/src/commands/versions.test.js

@@ -0,0 +1,53 @@
+'use strict'
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const { extract_version, sort_refs } = require('./versions')
+
+describe('versions — extract_version', () => {
+	it('strips refs/tags/v prefix', () => {
+		assert.strictEqual(extract_version('refs/tags/v1.2.0'), '1.2.0')
+	})
+
+	it('handles refs without leading v', () => {
+		assert.strictEqual(extract_version('refs/tags/1.2.0'), '1.2.0')
+	})
+
+	it('returns the input when not a tag ref', () => {
+		assert.strictEqual(extract_version('main'), 'main')
+	})
+
+	it('returns input for null/undefined safely', () => {
+		assert.strictEqual(extract_version(''), '')
+	})
+})
+
+describe('versions — sort_refs', () => {
+	it('sorts newest first by created_at', () => {
+		const refs = [
+			{ name: 'refs/tags/v1.0.0', created_at: '2026-01-01T00:00:00Z' },
+			{ name: 'refs/tags/v1.2.0', created_at: '2026-03-01T00:00:00Z' },
+			{ name: 'refs/tags/v1.1.0', created_at: '2026-02-01T00:00:00Z' }
+		]
+		const sorted = sort_refs(refs)
+		assert.deepStrictEqual(sorted.map(r => r.name), [
+			'refs/tags/v1.2.0',
+			'refs/tags/v1.1.0',
+			'refs/tags/v1.0.0'
+		])
+	})
+
+	it('handles empty/null input', () => {
+		assert.deepStrictEqual(sort_refs([]), [])
+		assert.deepStrictEqual(sort_refs(null), [])
+	})
+
+	it('does not mutate input array', () => {
+		const refs = [
+			{ name: 'a', created_at: '2026-01-01T00:00:00Z' },
+			{ name: 'b', created_at: '2026-02-01T00:00:00Z' }
+		]
+		const original = [...refs]
+		sort_refs(refs)
+		assert.deepStrictEqual(refs, original)
+	})
+})

package/src/constants.js

@@ -70,7 +70,9 @@ const COMMANDS = [
 	'groups',
 	'access',
 	'enable',
-	'disable'
+	'disable',
+	'versions',
+	'changelog'
 ]
 
 module.exports = {

package/src/index.js

@@ -91,6 +91,8 @@ Commands:
   visibility <owner/skill> Check or set visibility (alias: vis)
   list                     List installed skills (alias: ls)
   search <query>           Search the registry (alias: s)
+  versions <owner/skill>   List all published versions of a skill
+  changelog <owner/skill>  Print a skill's CHANGELOG.md
   check [owner/skill]      Check for available updates
   status [owner/skill]     Show divergence status (alias: st)
   pull <owner/skill>       Pull remote changes and merge

package/src/integration/cli.test.js

@@ -947,3 +947,68 @@ describe('list — enabled column', () => {
 		}
 	})
 })
+
+// ─── versions / changelog commands ────────────────────────────────────────────
+
+describe('CLI — versions command', () => {
+	it('versions --help exits 0 and shows usage', () => {
+		const { stdout, code } = run(['versions', '--help'])
+		assert.strictEqual(code, 0)
+		assert.ok(stdout.includes('Arguments:'))
+		assert.ok(stdout.includes('Options:'))
+		assert.ok(stdout.includes('--limit'))
+	})
+
+	it('versions without arguments exits with usage error', () => {
+		const { code, stderr } = run(['versions'])
+		assert.strictEqual(code, 2)
+		assert.ok(stderr.includes('specify a skill'))
+	})
+
+	it('versions with no slash exits with usage error', () => {
+		const { code, stderr } = run(['versions', 'deploy-aws'])
+		assert.strictEqual(code, 2)
+		assert.ok(stderr.includes('owner/name format'))
+	})
+
+	it('versions with bad --limit exits with usage error', () => {
+		const { code, stderr } = run(['versions', 'acme/deploy-aws', '--limit', 'abc'])
+		assert.strictEqual(code, 2)
+		assert.ok(stderr.toLowerCase().includes('limit'))
+	})
+
+	it('versions acme/deploy-aws --json fails with NETWORK_ERROR (no server)', () => {
+		const { stdout, code } = run(['versions', 'acme/deploy-aws', '--json'])
+		assert.strictEqual(code, 4)
+		const out = parse_json_output(stdout, 'versions --json network failure')
+		assert.strictEqual(out.error.code, 'NETWORK_ERROR')
+	})
+})
+
+describe('CLI — changelog command', () => {
+	it('changelog --help exits 0 and shows usage', () => {
+		const { stdout, code } = run(['changelog', '--help'])
+		assert.strictEqual(code, 0)
+		assert.ok(stdout.includes('Arguments:'))
+		assert.ok(stdout.includes('--version'))
+	})
+
+	it('changelog without arguments exits with usage error', () => {
+		const { code, stderr } = run(['changelog'])
+		assert.strictEqual(code, 2)
+		assert.ok(stderr.includes('specify a skill'))
+	})
+
+	it('changelog with no slash exits with usage error', () => {
+		const { code, stderr } = run(['changelog', 'deploy-aws'])
+		assert.strictEqual(code, 2)
+		assert.ok(stderr.includes('owner/name format'))
+	})
+
+	it('changelog acme/deploy-aws --json fails with NETWORK_ERROR (no server)', () => {
+		const { stdout, code } = run(['changelog', 'acme/deploy-aws', '--json'])
+		assert.strictEqual(code, 4)
+		const out = parse_json_output(stdout, 'changelog --json network failure')
+		assert.strictEqual(out.error.code, 'NETWORK_ERROR')
+	})
+})

package/src/manifest/validator.js

@@ -2,6 +2,9 @@ const { valid } = require('../utils/semver')
 
 const REQUIRED_FIELDS = ['name', 'version']
 const NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/
+// Kits are required to start with `_kit-` (enforced by `init --kit` and
+// validate_skill_json). Carve out the leading-character rule for them.
+const KIT_NAME_PATTERN = /^_kit-[a-z0-9][a-z0-9-]*$/
 
 const validate_manifest = (manifest) => {
 	const errors = []
@@ -12,7 +15,8 @@ const validate_manifest = (manifest) => {
 		}
 	}
 
-	if (manifest.name && !NAME_PATTERN.test(manifest.name)) {
+	const name_pattern = manifest.type === 'kit' ? KIT_NAME_PATTERN : NAME_PATTERN
+	if (manifest.name && !name_pattern.test(manifest.name)) {
 		errors.push(`Invalid name "${manifest.name}". Use lowercase letters, numbers, hyphens, and underscores. Must start with a letter or number.`)
 	}
 

package/src/manifest/validator.test.js

@@ -98,4 +98,26 @@ describe('validate_manifest', () => {
 		const result = validate_manifest({ name: 'my-skill', version: '1.0.0' })
 		assert.strictEqual(result.valid, true)
 	})
+
+	// Bug 2 regression — kit names start with `_kit-` (enforced by `init --kit` and
+	// `validate_skill_json` for type==='kit'). The shared `validate_manifest` used
+	// by `bump` must accept this convention or the standard release workflow breaks.
+	describe('kit name convention', () => {
+		it('accepts a kit name beginning with _kit- when type is "kit"', () => {
+			const result = validate_manifest({ name: '_kit-mykit', version: '1.0.0', type: 'kit' })
+			assert.strictEqual(result.valid, true, `expected valid, got errors: ${result.errors.join(', ')}`)
+		})
+
+		it('still rejects a non-kit manifest whose name starts with _', () => {
+			const result = validate_manifest({ name: '_oops', version: '1.0.0' })
+			assert.strictEqual(result.valid, false)
+			assert.ok(result.errors.some(e => e.includes('Invalid name')))
+		})
+
+		it('still rejects a non-kit manifest whose name starts with _ even if type=skill', () => {
+			const result = validate_manifest({ name: '_oops', version: '1.0.0', type: 'skill' })
+			assert.strictEqual(result.valid, false)
+			assert.ok(result.errors.some(e => e.includes('Invalid name')))
+		})
+	})
 })

package/src/validation/skill_md_rules.js

@@ -12,6 +12,9 @@ const FORBIDDEN_CHARS = {
 
 const NAME_PATTERN = /^[a-z][a-z0-9-]*$/
 const PLACEHOLDER_DESC = 'Describe what this skill does and when to invoke it'
+const DESC_SOFT_CAP = 250
+const DESC_TARGET_MIN = 80
+const DESC_TARGET_MAX = 180
 
 const result = (field, rule, severity, message, value) => ({
 	file: SKILL_MD, field, rule, severity, message, ...(value !== undefined ? { value } : {})
@@ -89,6 +92,20 @@ const validate_description = (fm) => {
 		})
 	} else {
 		results.push(result('description', 'max_length', 'pass', `Description: ${desc.length} chars (max 1024)`))
+
+		if (desc.length > DESC_SOFT_CAP) {
+			results.push({
+				...result('description', 'soft_cap', 'warning', `Description is ${desc.length} chars (target: ${DESC_TARGET_MIN}-${DESC_TARGET_MAX}, soft cap: ${DESC_SOFT_CAP}). Above ${DESC_SOFT_CAP} chars usually signals a mega-skill — apply the Suite Pattern to decompose it into a core skill plus focused satellites. Run "npx happyskills audit <name>" or ask your agent "audit this skill" — happyskills-design will walk you through the Suite Decomposition Workflow.`, desc),
+				recommendations: [
+					'CANONICAL — Apply the Suite Pattern: decompose the skill into a core entry-point skill plus satellite skills, each owning one orthogonal verb cluster, bundled via the core skill.json dependencies. This is the answer once a description crosses the soft cap. happyskills-design implements the Suite Decomposition Workflow end-to-end — invoke it with "audit this skill" or "decompose this mega-skill".',
+					'Alternative — Compress the description first (AUDIT/LOSSLESS/LOSSY procedure in happyskills-design references/skill-authoring.md). Buys time, but compression alone will not keep up as the API surface grows.',
+					'Alternative — Hybrid umbrella+satellites: keep one main skill for high-frequency operations, extract specialized domains into satellites.',
+					'For the canonical Suite Pattern reference (orthogonal verb ownership, the five-slot description grammar, failure modes, orthogonality test): happyskills-design references/suite-pattern.md, or docs/cli-skill.md in the HappySkills repo.'
+				]
+			})
+		} else {
+			results.push(result('description', 'soft_cap', 'pass', `Description: ${desc.length} chars (soft cap ${DESC_SOFT_CAP})`))
+		}
 	}
 
 	if (desc === PLACEHOLDER_DESC) {

package/src/validation/skill_md_rules.test.js

@@ -145,6 +145,40 @@ describe('validate_skill_md — description', () => {
 		const check = data.results.find(r => r.rule === 'no_forbidden_characters')
 		assert.strictEqual(check.severity, 'pass')
 	})
+
+	it('warns when description exceeds the 250-char soft cap (still under 1024 hard cap)', async () => {
+		const desc = 'a'.repeat(300)
+		write_skill_md(tmp, { name: 'my-skill', description: desc })
+		const [err, data] = await validate_skill_md(tmp, 'my-skill')
+		assert.ifError(err)
+		const max_length = data.results.find(r => r.field === 'description' && r.rule === 'max_length')
+		assert.strictEqual(max_length.severity, 'pass')
+		const soft_cap = data.results.find(r => r.field === 'description' && r.rule === 'soft_cap')
+		assert.strictEqual(soft_cap.severity, 'warning')
+		assert.ok(soft_cap.message.includes('300 chars'))
+		assert.ok(Array.isArray(soft_cap.recommendations))
+		assert.ok(soft_cap.recommendations.length > 0)
+	})
+
+	it('passes the soft cap when description is at or under 250 chars', async () => {
+		const desc = 'a'.repeat(250)
+		write_skill_md(tmp, { name: 'my-skill', description: desc })
+		const [err, data] = await validate_skill_md(tmp, 'my-skill')
+		assert.ifError(err)
+		const soft_cap = data.results.find(r => r.field === 'description' && r.rule === 'soft_cap')
+		assert.strictEqual(soft_cap.severity, 'pass')
+	})
+
+	it('does not emit a soft_cap warning when description is over the 1024 hard cap (max_length error dwarfs it)', async () => {
+		const desc = 'a'.repeat(1100)
+		write_skill_md(tmp, { name: 'my-skill', description: desc })
+		const [err, data] = await validate_skill_md(tmp, 'my-skill')
+		assert.ifError(err)
+		const max_length = data.results.find(r => r.field === 'description' && r.rule === 'max_length')
+		assert.strictEqual(max_length.severity, 'error')
+		const soft_cap = data.results.find(r => r.field === 'description' && r.rule === 'soft_cap')
+		assert.strictEqual(soft_cap, undefined)
+	})
 })
 
 describe('validate_skill_md — optional fields', () => {