happyskills 0.40.0 → 0.41.0

package/CHANGELOG.md

@@ -7,6 +7,13 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.40.0",
+	"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/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/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/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', () => {