happyskills 0.7.3 → 0.9.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-03-10
+
+### Added
+- Add `validate` command to check a skill against all rules from the agentskills.io spec in one pass — validates SKILL.md frontmatter (name, description, optional fields, line count), skill.json (name, version, description, keywords, dependencies, systemDependencies), and cross-file consistency (name match, executable code detection); supports `--json` and `-g` flags (alias: `v`)
+- Add SKILL.md frontmatter validation warnings to `publish` and `convert` commands — warn about missing `name` or `description` fields before publishing
+
+### Changed
+- Change `init` scaffolding to generate SKILL.md with proper YAML frontmatter (`name` and `description` fields) instead of a bare markdown heading
+
+## [0.8.0] - 2026-03-08
+
+### Added
+- Add `refresh` command to check all installed skills for updates and upgrade outdated ones in a single step (alias: `r`); supports `-y`, `-g`, and `--json` flags
+
+### Changed
+- Change `check` command to use a single batch API call (`POST /repos:check-updates`) instead of N sequential ref lookups, significantly reducing latency for projects with many skills
+
+### Fixed
+- Fix `publish` not writing the commit SHA to `skills-lock.json` after publishing, causing first-publish detection to rely on stale lock data
+
 ## [0.7.3] - 2026-03-08
 
 ### Fixed

package/package.json

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

@@ -46,4 +46,10 @@ const get_repo = (owner, repo) => catch_errors(`Get repo ${owner}/${repo} failed
 	return data
 })
 
-module.exports = { search, resolve_dependencies, clone, push, get_refs, get_repo }
+const check_updates = (skills) => catch_errors('Check updates failed', async () => {
+	const [errors, data] = await client.post('/repos:check-updates', { skills })
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+module.exports = { search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates }

package/src/commands/check.js

@@ -1,7 +1,7 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const repos_api = require('../api/repos')
-const { satisfies, gt } = require('../utils/semver')
+const { gt } = require('../utils/semver')
 const { print_help, print_table, print_json, print_info, print_success, print_hint, code } = require('../ui/output')
 const { green, yellow, red } = require('../ui/colors')
 const { exit_with_error } = require('../utils/errors')
@@ -57,29 +57,26 @@ const run = (args) => catch_errors('Check failed', async () => {
 		return
 	}
 
+	const skill_names = to_check.map(([name]) => name)
+	const [batch_err, batch_data] = await repos_api.check_updates(skill_names)
+
 	const results = []
-	for (const [name, data] of to_check) {
-		const [owner, repo] = name.split('/')
-		const [errors, refs] = await repos_api.get_refs(owner, repo)
-		if (errors) {
+	if (batch_err) {
+		for (const [name, data] of to_check) {
 			results.push({ skill: name, installed: data.version, latest: 'error', status: 'error' })
-			continue
 		}
-
-		const versions = (refs || [])
-			.map(r => r.name?.replace('refs/tags/v', ''))
-			.filter(Boolean)
-
-		const latest = versions.sort((a, b) => gt(a, b) ? -1 : 1)[0]
-
-		if (!latest) {
-			results.push({ skill: name, installed: data.version, latest: '-', status: 'unknown' })
-		} else if (latest === data.version) {
-			results.push({ skill: name, installed: data.version, latest, status: 'up-to-date' })
-		} else if (gt(latest, data.version)) {
-			results.push({ skill: name, installed: data.version, latest, status: 'outdated' })
-		} else {
-			results.push({ skill: name, installed: data.version, latest, status: 'up-to-date' })
+	} else {
+		for (const [name, data] of to_check) {
+			const info = batch_data?.results?.[name]
+			if (!info || !info.latest_version) {
+				results.push({ skill: name, installed: data.version, latest: '-', status: 'unknown' })
+			} else if (info.latest_version === data.version) {
+				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date' })
+			} else if (gt(info.latest_version, data.version)) {
+				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated' })
+			} else {
+				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date' })
+			}
 		}
 	}
 

package/src/commands/convert.js

@@ -13,7 +13,7 @@ const { hash_directory } = require('../lock/integrity')
 const { skills_dir, find_project_root, lock_root } = require('../config/paths')
 const { file_exists } = require('../utils/fs')
 const { create_spinner } = require('../ui/spinner')
-const { print_help, print_success, print_error, print_info, print_label, print_json } = require('../ui/output')
+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')
 const { EXIT_CODES, SKILL_MD } = require('../constants')
 
@@ -99,6 +99,25 @@ const run = (args) => catch_errors('Convert failed', async () => {
 		? args.flags.keywords.split(',').map(k => k.trim()).filter(Boolean)
 		: fm_keywords
 
+	// Warn about missing frontmatter fields that affect auto-invocation
+	const frontmatter_warnings = []
+	if (!frontmatter) {
+		frontmatter_warnings.push('SKILL.md has no YAML frontmatter (---). Without frontmatter, Claude cannot auto-invoke this skill. Add a frontmatter block with name and description fields.')
+	} else {
+		if (!frontmatter.name) {
+			frontmatter_warnings.push('SKILL.md frontmatter is missing "name". Add name: <skill-name> to the frontmatter.')
+		}
+		if (!frontmatter.description) {
+			frontmatter_warnings.push('SKILL.md frontmatter is missing "description". The description is the #1 factor for Claude auto-invocation quality. Without it, the skill will not be auto-invoked.')
+		}
+	}
+
+	if (frontmatter_warnings.length > 0) {
+		for (const warning of frontmatter_warnings) {
+			print_warn(warning)
+		}
+	}
+
 	const spinner = create_spinner('Resolving workspace...')
 
 	const [ws_err, workspaces] = await workspaces_api.list_workspaces()
@@ -160,12 +179,14 @@ const run = (args) => catch_errors('Convert failed', async () => {
 	pub_spinner.succeed(`Converted ${full_name}@${version}`)
 
 	if (args.flags.json) {
-		print_json({ data: {
+		const json_data = {
 			skill: full_name,
 			version,
 			workspace: workspace.slug,
 			description: description || ''
-		} })
+		}
+		if (frontmatter_warnings.length > 0) json_data.warnings = frontmatter_warnings
+		print_json({ data: json_data })
 		return
 	}
 

package/src/commands/init.js

@@ -24,11 +24,12 @@ Examples:
   happyskills init
   happyskills init my-deploy-skill`
 
-const create_skill_md = (name) => `# ${name}
+const create_skill_md = (name) => `---
+name: ${name}
+description: Describe what this skill does and when to invoke it
+---
 
-## Description
-
-Describe what this skill does for the AI agent.
+# ${name}
 
 ## Instructions
 

package/src/commands/publish.js

@@ -1,3 +1,5 @@
+const fs = require('fs')
+const path = require('path')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_manifest } = require('../manifest/reader')
 const { write_manifest } = require('../manifest/writer')
@@ -13,10 +15,11 @@ const { find_project_root } = require('../config/paths')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { write_lock, update_lock_skills } = require('../lock/writer')
 const { hash_directory } = require('../lock/integrity')
+const { parse_frontmatter } = require('../utils/skill_scanner')
 const { create_spinner } = require('../ui/spinner')
 const { print_help, print_success, print_error, print_warn, print_hint, print_json, code } = require('../ui/output')
 const { exit_with_error, UsageError, CliError } = require('../utils/errors')
-const { EXIT_CODES } = require('../constants')
+const { EXIT_CODES, SKILL_MD } = require('../constants')
 
 const HELP_TEXT = `Usage: happyskills publish <skill-name> [options]
 
@@ -87,6 +90,31 @@ const run = (args) => catch_errors('Publish failed', async () => {
 		throw new CliError(`Invalid skill.json: ${validation.errors.join(', ')}`, EXIT_CODES.ERROR)
 	}
 
+	// Validate SKILL.md frontmatter — warn about missing name/description
+	const frontmatter_warnings = []
+	try {
+		const skill_md_content = await fs.promises.readFile(path.join(dir, SKILL_MD), 'utf-8')
+		const frontmatter = parse_frontmatter(skill_md_content)
+		if (!frontmatter) {
+			frontmatter_warnings.push('SKILL.md has no YAML frontmatter (---). Without frontmatter, Claude cannot auto-invoke this skill.')
+		} else {
+			if (!frontmatter.name) {
+				frontmatter_warnings.push('SKILL.md frontmatter is missing "name". Add name: <skill-name> to the frontmatter.')
+			}
+			if (!frontmatter.description) {
+				frontmatter_warnings.push('SKILL.md frontmatter is missing "description". The description is the #1 factor for Claude auto-invocation quality. Without it, the skill will not be auto-invoked.')
+			}
+		}
+	} catch {
+		frontmatter_warnings.push(`No ${SKILL_MD} found. The skill may not work correctly.`)
+	}
+
+	if (frontmatter_warnings.length > 0) {
+		for (const warning of frontmatter_warnings) {
+			print_warn(warning)
+		}
+	}
+
 	const spinner = create_spinner('Preparing to publish...')
 
 	let owner = args.flags.workspace
@@ -164,13 +192,15 @@ const run = (args) => catch_errors('Publish failed', async () => {
 	}
 
 	if (args.flags.json) {
-		print_json({ data: {
+		const json_data = {
 			skill: full_name,
 			version: manifest.version,
 			ref: push_data?.ref || `refs/tags/v${manifest.version}`,
 			commit: push_data?.commit || null,
 			bumped_from
-		} })
+		}
+		if (frontmatter_warnings.length > 0) json_data.warnings = frontmatter_warnings
+		print_json({ data: json_data })
 		return
 	}
 

package/src/commands/refresh.js

@@ -0,0 +1,170 @@
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { install } = require('../engine/installer')
+const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const repos_api = require('../api/repos')
+const { gt } = require('../utils/semver')
+const { print_help, print_table, print_json, print_info, print_success, code } = require('../ui/output')
+const { green, yellow, red } = require('../ui/colors')
+const { create_spinner } = require('../ui/spinner')
+const { exit_with_error } = require('../utils/errors')
+const { find_project_root, lock_root } = require('../config/paths')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills refresh [options]
+
+Check all installed skills for updates and upgrade outdated ones.
+
+Options:
+  -g, --global      Refresh globally installed skills
+  -y, --yes         Skip confirmation prompts
+  --json            Output as JSON
+
+Aliases: r
+
+Examples:
+  happyskills refresh
+  happyskills refresh -y
+  happyskills refresh -g -y --json`
+
+const confirm_prompt = (question) => new Promise((resolve) => {
+	const readline = require('readline')
+	const rl = readline.createInterface({ input: process.stdin, output: process.stderr })
+	rl.question(question, (answer) => {
+		rl.close()
+		resolve(answer.trim().toLowerCase())
+	})
+})
+
+const run = (args) => catch_errors('Refresh failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const is_global = args.flags.global || false
+	const auto_yes = args.flags.yes || false
+	const project_root = find_project_root()
+	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
+	const skills = get_all_locked_skills(lock_data)
+	const entries = Object.entries(skills)
+
+	const to_check = entries.filter(([, data]) => data.requested_by?.includes('__root__'))
+
+	if (to_check.length === 0) {
+		if (args.flags.json) {
+			print_json({ data: { results: [], outdated_count: 0, up_to_date_count: 0, updated: [], already_up_to_date: [], errors: [] } })
+			return
+		}
+		print_info('No skills installed.')
+		return
+	}
+
+	// 1. Check for updates
+	const spinner = !args.flags.json ? create_spinner('Checking for updates…') : null
+	const skill_names = to_check.map(([name]) => name)
+	const [batch_err, batch_data] = await repos_api.check_updates(skill_names)
+
+	const results = []
+	if (batch_err) {
+		spinner?.fail('Failed to check for updates')
+		for (const [name, data] of to_check) {
+			results.push({ skill: name, installed: data.version, latest: 'error', status: 'error' })
+		}
+	} else {
+		spinner?.succeed('Checked for updates')
+		for (const [name, data] of to_check) {
+			const info = batch_data?.results?.[name]
+			if (!info || !info.latest_version) {
+				results.push({ skill: name, installed: data.version, latest: '-', status: 'unknown' })
+			} else if (info.latest_version === data.version) {
+				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date' })
+			} else if (gt(info.latest_version, data.version)) {
+				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated' })
+			} else {
+				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date' })
+			}
+		}
+	}
+
+	const outdated = results.filter(r => r.status === 'outdated')
+	const up_to_date = results.filter(r => r.status === 'up-to-date')
+
+	// 2. If nothing to update, report and exit
+	if (outdated.length === 0) {
+		if (args.flags.json) {
+			print_json({ data: { results, outdated_count: 0, up_to_date_count: up_to_date.length, updated: [], already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })), errors: [] } })
+			return
+		}
+		print_table(['Skill', 'Installed', 'Latest', 'Status'], results.map(r => [
+			r.skill, r.installed, r.latest, green(r.status)
+		]))
+		console.log()
+		print_success('All skills are up to date.')
+		return
+	}
+
+	// 3. Show results table (non-json)
+	if (!args.flags.json) {
+		const status_colors = { 'up-to-date': green, 'outdated': yellow, 'error': red, 'unknown': (s) => s }
+		print_table(['Skill', 'Installed', 'Latest', 'Status'], results.map(r => [
+			r.skill, r.installed, r.latest, (status_colors[r.status] || ((s) => s))(r.status)
+		]))
+		console.log()
+		print_info(`${outdated.length} skill(s) can be updated.`)
+	}
+
+	// 4. Confirm update
+	const should_update = auto_yes || !process.stdin.isTTY
+	if (!should_update && !args.flags.json) {
+		const answer = await confirm_prompt(`\nUpdate ${outdated.length} skill(s)? [y/N] `)
+		if (answer !== 'y' && answer !== 'yes') {
+			print_info('Skipped.')
+			return
+		}
+	}
+
+	// 5. Update outdated skills
+	const options = { global: is_global, fresh: true, project_root }
+	const updated = []
+	const update_errors = []
+
+	for (const r of outdated) {
+		const update_spinner = !args.flags.json ? create_spinner(`Updating ${r.skill}…`) : null
+		const [errors, result] = await install(r.skill, options)
+		if (errors) {
+			update_spinner?.fail(`Failed to update ${r.skill}`)
+			update_errors.push({ skill: r.skill, message: errors[errors.length - 1]?.message || 'Unknown error' })
+		} else if (!result.no_op) {
+			update_spinner?.succeed(`Updated ${r.skill} ${r.installed} → ${result.version}`)
+			updated.push({ skill: r.skill, from: r.installed, to: result.version })
+		} else {
+			update_spinner?.succeed(`${r.skill} already up to date`)
+		}
+	}
+
+	// 6. Output results
+	if (args.flags.json) {
+		print_json({
+			data: {
+				results,
+				outdated_count: outdated.length,
+				up_to_date_count: up_to_date.length,
+				updated,
+				already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })),
+				errors: update_errors
+			}
+		})
+		return
+	}
+
+	if (updated.length > 0) {
+		console.log()
+		print_success(`Updated ${updated.length} skill(s).`)
+	}
+	if (update_errors.length > 0) {
+		console.log()
+		print_info(`${update_errors.length} skill(s) failed to update. Run ${code('happyskills check')} for details.`)
+	}
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run }

package/src/commands/validate.js

@@ -0,0 +1,148 @@
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+const { validate_skill_md } = require('../validation/skill_md_rules')
+const { validate_skill_json } = require('../validation/skill_json_rules')
+const { validate_cross } = require('../validation/cross_rules')
+const { file_exists } = require('../utils/fs')
+const { skills_dir, find_project_root } = require('../config/paths')
+const { print_help, print_json } = require('../ui/output')
+const { bold, green, yellow, red, dim } = require('../ui/colors')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES, SKILL_MD } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills validate <skill-name> [options]
+
+Validate a skill against all rules from the agentskills.io spec.
+
+Arguments:
+  skill-name             Name of the skill to validate
+
+Options:
+  -g, --global           Look in global skills (~/.claude/skills/)
+  --json                 Output as JSON
+
+Aliases: v
+
+Examples:
+  happyskills validate my-skill
+  happyskills validate deploy-aws -g
+  happyskills v my-skill --json`
+
+const resolve_validate_dir = async (skill_name, is_global) => {
+	const project_root = find_project_root()
+	const base = skills_dir(is_global, project_root)
+	const dir = path.join(base, skill_name)
+
+	// Check if directory exists (don't require skill.json — that's what validate checks)
+	const md_path = path.join(dir, SKILL_MD)
+	const json_path = path.join(dir, 'skill.json')
+
+	const [, md_exists] = await file_exists(md_path)
+	const [, json_exists] = await file_exists(json_path)
+
+	if (!md_exists && !json_exists) {
+		throw new UsageError(`Skill "${skill_name}" not found at ${dir}`)
+	}
+
+	return dir
+}
+
+const format_human = (skill_name, all_results) => {
+	console.log(`\nValidating skill "${bold(skill_name)}"...\n`)
+
+	const groups = {}
+	for (const r of all_results) {
+		const key = r.file || 'General'
+		if (!groups[key]) groups[key] = []
+		groups[key].push(r)
+	}
+
+	for (const [file, items] of Object.entries(groups)) {
+		console.log(`  ${bold(file)}`)
+		for (const item of items) {
+			if (item.severity === 'pass') {
+				console.log(`  ${green('✓')} ${item.message}`)
+			} else if (item.severity === 'warning') {
+				console.log(`  ${yellow('⚠')} ${item.message}`)
+			} else {
+				console.log(`  ${red('✗')} ${item.message}`)
+			}
+		}
+		console.log()
+	}
+
+	const errors = all_results.filter(r => r.severity === 'error')
+	const warnings = all_results.filter(r => r.severity === 'warning')
+	const passed = all_results.filter(r => r.severity === 'pass')
+
+	const parts = []
+	if (warnings.length > 0) parts.push(yellow(`${warnings.length} warning${warnings.length === 1 ? '' : 's'}`))
+	if (errors.length > 0) parts.push(red(`${errors.length} error${errors.length === 1 ? '' : 's'}`))
+	if (errors.length === 0 && warnings.length === 0) parts.push(green('all checks passed'))
+
+	console.log(dim(`${passed.length} passed, `) + parts.join(', '))
+}
+
+const format_json = (skill_name, all_results) => {
+	const errors = all_results.filter(r => r.severity === 'error').map(({ severity, ...rest }) => rest)
+	const warnings = all_results.filter(r => r.severity === 'warning').map(({ severity, ...rest }) => rest)
+	const passed = all_results.filter(r => r.severity === 'pass')
+	const failed = all_results.filter(r => r.severity === 'error')
+	const warned = all_results.filter(r => r.severity === 'warning')
+
+	print_json({
+		data: {
+			skill: skill_name,
+			valid: failed.length === 0,
+			errors,
+			warnings,
+			checks_passed: passed.length,
+			checks_failed: failed.length,
+			checks_warned: warned.length
+		}
+	})
+}
+
+const run = (args) => catch_errors('Validate failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const skill_name = args._[0]
+	if (!skill_name) {
+		throw new UsageError('Skill name required. Usage: happyskills validate <skill-name>')
+	}
+
+	const is_global = !!args.flags.global
+	const skill_dir = await resolve_validate_dir(skill_name, is_global)
+	const dir_name = path.basename(skill_dir)
+
+	// Run all rule modules
+	const [md_err, md_data] = await validate_skill_md(skill_dir, dir_name)
+	if (md_err) throw md_err
+
+	const [json_err, json_data] = await validate_skill_json(skill_dir)
+	if (json_err) throw json_err
+
+	const [cross_err, cross_results] = await validate_cross(
+		skill_dir,
+		md_data.frontmatter,
+		json_data.manifest,
+		md_data.content
+	)
+	if (cross_err) throw cross_err
+
+	const all_results = [...md_data.results, ...json_data.results, ...cross_results]
+
+	if (args.flags.json) {
+		format_json(skill_name, all_results)
+	} else {
+		format_human(skill_name, all_results)
+	}
+
+	const has_errors = all_results.some(r => r.severity === 'error')
+	process.exit(has_errors ? EXIT_CODES.ERROR : EXIT_CODES.SUCCESS)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run }

package/src/constants.js

@@ -26,8 +26,10 @@ const COMMAND_ALIASES = {
 	remove: 'uninstall',
 	ls: 'list',
 	s: 'search',
+	r: 'refresh',
 	up: 'update',
-	pub: 'publish'
+	pub: 'publish',
+	v: 'validate'
 }
 
 const COMMANDS = [
@@ -37,6 +39,7 @@ const COMMANDS = [
 	'list',
 	'search',
 	'check',
+	'refresh',
 	'update',
 	'bump',
 	'publish',
@@ -46,6 +49,7 @@ const COMMANDS = [
 	'whoami',
 	'fork',
 	'setup',
+	'validate',
 	'self-update'
 ]
 

package/src/index.js

@@ -90,8 +90,10 @@ Commands:
   list                     List installed skills (alias: ls)
   search <query>           Search the registry (alias: s)
   check [owner/skill]      Check for available updates
+  refresh                  Check + update all outdated skills (alias: r)
   update [owner/skill]     Upgrade to latest versions (alias: up)
   publish                  Push skill to registry (alias: pub)
+  validate <skill-name>    Validate skill against all rules (alias: v)
   fork <owner/skill>       Fork a skill to your workspace
   setup                    Install the HappySkills CLI skill globally
   self-update              Upgrade happyskills CLI to latest version