happyskills 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-03-10
+
+### Changed
+- Change `publish` to run full skill validation (SKILL.md + skill.json + cross-file rules) before publishing, blocking on errors with structured `VALIDATION_FAILED` output in JSON mode — replaces the previous ad-hoc manifest validation and frontmatter warnings
+
+## [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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.8.0",
+	"version": "0.9.1",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/commands/convert.js

@@ -13,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,7 +1,7 @@
+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')
-const { validate_manifest } = require('../manifest/validator')
 const { require_token } = require('../auth/token_store')
 const repos_api = require('../api/repos')
 const workspaces_api = require('../api/workspaces')
@@ -13,6 +13,9 @@ 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 { 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 { 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')
@@ -82,9 +85,39 @@ const run = (args) => catch_errors('Publish failed', async () => {
 		if (write_err) throw e('Failed to update manifest version', write_err)
 	}
 
-	const validation = validate_manifest(manifest)
-	if (!validation.valid) {
-		throw new CliError(`Invalid skill.json: ${validation.errors.join(', ')}`, EXIT_CODES.ERROR)
+	// Run full validation — block on errors, show warnings
+	const dir_name = path.basename(dir)
+	const [md_err, md_data] = await validate_skill_md(dir, dir_name)
+	if (md_err) throw md_err
+	const [json_err, json_data] = await validate_skill_json(dir)
+	if (json_err) throw json_err
+	const [cross_err, cross_results] = await validate_cross(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]
+	const validation_errors = all_results.filter(r => r.severity === 'error')
+	const validation_warnings = all_results.filter(r => r.severity === 'warning')
+
+	if (validation_errors.length > 0) {
+		const { is_json_mode } = require('../state')
+		if (is_json_mode()) {
+			const structured_errors = validation_errors.map(({ severity, ...rest }) => rest)
+			print_json({
+				error: {
+					code: 'VALIDATION_FAILED',
+					message: `Skill failed validation with ${validation_errors.length} error(s). Fix these issues and try again.`,
+					exit_code: EXIT_CODES.ERROR,
+					validation_errors: structured_errors
+				}
+			})
+			return process.exit(EXIT_CODES.ERROR)
+		}
+		const error_msgs = validation_errors.map(r => `${r.file || 'General'}${r.field ? ` (${r.field})` : ''}: ${r.message}`)
+		throw new CliError(`Skill failed validation with ${validation_errors.length} error(s):\n  ${error_msgs.join('\n  ')}\n\nRun \`happyskills validate ${skill_name}\` for full details.`, EXIT_CODES.ERROR)
+	}
+
+	for (const w of validation_warnings) {
+		print_warn(`${w.file || 'General'}${w.field ? ` (${w.field})` : ''}: ${w.message}`)
 	}
 
 	const spinner = create_spinner('Preparing to publish...')
@@ -164,13 +197,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 (validation_warnings.length > 0) json_data.warnings = validation_warnings.map(w => w.message)
+		print_json({ data: json_data })
 		return
 	}
 

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

@@ -28,7 +28,8 @@ const COMMAND_ALIASES = {
 	s: 'search',
 	r: 'refresh',
 	up: 'update',
-	pub: 'publish'
+	pub: 'publish',
+	v: 'validate'
 }
 
 const COMMANDS = [
@@ -48,6 +49,7 @@ const COMMANDS = [
 	'whoami',
 	'fork',
 	'setup',
+	'validate',
 	'self-update'
 ]
 

package/src/index.js

@@ -93,6 +93,7 @@ Commands:
   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

package/src/integration/cli.test.js

@@ -92,7 +92,7 @@ describe('CLI — global flags', () => {
 
 	it('--help lists all expected commands', () => {
 		const { stdout } = run(['--help'])
-		const expected_commands = ['install', 'uninstall', 'list', 'search', 'check', 'refresh', 'update', 'publish', 'fork', 'login', 'logout', 'whoami', 'init', 'setup', 'self-update']
+		const expected_commands = ['install', 'uninstall', 'list', 'search', 'check', 'refresh', 'update', 'publish', 'validate', 'fork', 'login', 'logout', 'whoami', 'init', 'setup', 'self-update']
 		for (const cmd of expected_commands) {
 			assert.ok(stdout.includes(cmd), `help output should mention "${cmd}"`)
 		}
@@ -165,6 +165,9 @@ describe('CLI — command --help', () => {
 		['refresh',   'Aliases:'],
 		['update',    'Aliases:'],
 		['publish',   'Aliases:'],
+		['validate',  'Arguments:'],
+		['validate',  'Aliases:'],
+		['validate',  'Examples:'],
 		['fork',      'Arguments:'],
 		['init',          'Examples:'],
 		['setup',         'Options:'],
@@ -199,6 +202,7 @@ describe('CLI — command aliases', () => {
 		['r',      'refresh'],
 		['up',     'update'],
 		['pub',    'publish'],
+		['v',      'validate'],
 	]
 
 	for (const [alias, canonical] of alias_cases) {
@@ -478,3 +482,127 @@ describe('CLI — self-update command', () => {
 		assert.strictEqual(out.error.exit_code, 4)
 	})
 })
+
+// ─── validate command ─────────────────────────────────────────────────────────
+
+describe('CLI — validate command', () => {
+	it('validate --help exits 0 and shows usage', () => {
+		const { stdout, code } = run(['validate', '--help'])
+		assert.strictEqual(code, 0)
+		assert.ok(stdout.includes('Arguments:'))
+		assert.ok(stdout.includes('Aliases:'))
+		assert.ok(stdout.includes('Examples:'))
+	})
+
+	it('v alias resolves to validate (shows correct --help)', () => {
+		const { stdout, code } = run(['v', '--help'])
+		assert.strictEqual(code, 0)
+		assert.ok(stdout.toLowerCase().includes('validate'))
+	})
+
+	it('exits 2 when no skill name is given', () => {
+		const { stderr, code } = run(['validate'])
+		assert.strictEqual(code, 2)
+		assert.ok(stderr.includes('Skill name required'))
+	})
+
+	it('exits 2 when skill does not exist', () => {
+		const tmp = make_tmp()
+		try {
+			const { code } = run(['validate', 'nonexistent'], {}, { cwd: tmp })
+			assert.strictEqual(code, 2)
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+
+	it('exits 2 (JSON) when skill does not exist', () => {
+		const tmp = make_tmp()
+		try {
+			const { stdout, code } = run(['validate', 'nonexistent', '--json'], {}, { cwd: tmp })
+			assert.strictEqual(code, 2)
+			const out = parse_json_output(stdout, 'validate nonexistent --json')
+			assert.ok('error' in out)
+			assert.strictEqual(out.error.code, 'USAGE_ERROR')
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+
+	it('exits 0 for a valid skill and reports all checks passed', () => {
+		const tmp = make_tmp()
+		const skill_dir = path.join(tmp, '.claude', 'skills', 'test-skill')
+		fs.mkdirSync(skill_dir, { recursive: true })
+		fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), '---\nname: test-skill\ndescription: A valid test skill for unit testing\n---\n\n# Test Skill\n')
+		fs.writeFileSync(path.join(skill_dir, 'skill.json'), JSON.stringify({
+			name: 'test-skill', version: '1.0.0', description: 'A test skill',
+			keywords: ['testing']
+		}, null, '\t'))
+		try {
+			const { stdout, code } = run(['validate', 'test-skill'], {}, { cwd: tmp })
+			assert.strictEqual(code, 0)
+			assert.ok(stdout.includes('test-skill'))
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+
+	it('exits 1 for an invalid skill', () => {
+		const tmp = make_tmp()
+		const skill_dir = path.join(tmp, '.claude', 'skills', 'bad-skill')
+		fs.mkdirSync(skill_dir, { recursive: true })
+		fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), '---\nname: bad-skill\n---\n')
+		fs.writeFileSync(path.join(skill_dir, 'skill.json'), JSON.stringify({ name: 'bad-skill' }, null, '\t'))
+		try {
+			const { code } = run(['validate', 'bad-skill'], {}, { cwd: tmp })
+			assert.strictEqual(code, 1)
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+
+	it('--json returns correct schema for a valid skill', () => {
+		const tmp = make_tmp()
+		const skill_dir = path.join(tmp, '.claude', 'skills', 'test-skill')
+		fs.mkdirSync(skill_dir, { recursive: true })
+		fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), '---\nname: test-skill\ndescription: A valid test skill for unit testing\n---\n\n# Test\n')
+		fs.writeFileSync(path.join(skill_dir, 'skill.json'), JSON.stringify({
+			name: 'test-skill', version: '1.0.0', description: 'A test skill',
+			keywords: ['testing']
+		}, null, '\t'))
+		try {
+			const { stdout, code } = run(['validate', 'test-skill', '--json'], {}, { cwd: tmp })
+			assert.strictEqual(code, 0)
+			const out = parse_json_output(stdout, 'validate --json valid skill')
+			assert.ok('data' in out)
+			assert.strictEqual(out.data.skill, 'test-skill')
+			assert.strictEqual(out.data.valid, true)
+			assert.ok(Array.isArray(out.data.errors))
+			assert.ok(Array.isArray(out.data.warnings))
+			assert.strictEqual(typeof out.data.checks_passed, 'number')
+			assert.strictEqual(typeof out.data.checks_failed, 'number')
+			assert.strictEqual(typeof out.data.checks_warned, 'number')
+			assert.strictEqual(out.data.checks_failed, 0)
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+
+	it('--json returns errors for an invalid skill', () => {
+		const tmp = make_tmp()
+		const skill_dir = path.join(tmp, '.claude', 'skills', 'bad-skill')
+		fs.mkdirSync(skill_dir, { recursive: true })
+		fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), '---\nname: bad-skill\n---\n')
+		fs.writeFileSync(path.join(skill_dir, 'skill.json'), JSON.stringify({ name: 'bad-skill' }, null, '\t'))
+		try {
+			const { stdout, code } = run(['validate', 'bad-skill', '--json'], {}, { cwd: tmp })
+			assert.strictEqual(code, 1)
+			const out = parse_json_output(stdout, 'validate --json invalid skill')
+			assert.strictEqual(out.data.valid, false)
+			assert.ok(out.data.errors.length > 0)
+			assert.ok(out.data.checks_failed > 0)
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+})

package/src/validation/cross_rules.js

@@ -0,0 +1,76 @@
+const fs = require('fs')
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+
+const EXEC_LANGS = new Set(['python', 'bash', 'sh', 'javascript', 'js', 'typescript', 'ts', 'ruby', 'go', 'rust'])
+const SCRIPT_MARKERS = /^\s*(#!\/|import |from |require\(|def |class |function |const |let |var |export |module\.|package |fn |func |pub fn)/
+
+const result = (file, field, rule, severity, message, value) => ({
+	file, field, rule, severity, message, ...(value !== undefined ? { value } : {})
+})
+
+const scan_code_blocks = (content, file_label) => {
+	const results = []
+	const block_rx = /```(\w+)?\n([\s\S]*?)```/g
+	let match
+
+	while ((match = block_rx.exec(content)) !== null) {
+		const lang = (match[1] || '').toLowerCase()
+		if (!EXEC_LANGS.has(lang)) continue
+
+		const body = match[2]
+		const lines = body.split('\n')
+		const line_count = lines.filter(l => l.trim()).length
+		const marker_count = lines.filter(l => SCRIPT_MARKERS.test(l)).length
+
+		if (marker_count >= 2 || line_count > 10) {
+			results.push(result(file_label, null, 'no_executable_code', 'warning',
+				`Found ${lang} code block (${line_count} lines) that looks like an executable script — consider moving to scripts/`,
+				lang
+			))
+		}
+	}
+
+	return results
+}
+
+const validate_cross = (skill_dir, frontmatter, manifest, skill_md_content) => catch_errors('Failed cross-file validation', async () => {
+	const results = []
+
+	// Name match
+	if (frontmatter && manifest) {
+		if (frontmatter.name !== manifest.name) {
+			results.push(result('Cross-file', 'name', 'name_match', 'warning',
+				`SKILL.md name "${frontmatter.name}" does not match skill.json name "${manifest.name}"`,
+				`${frontmatter.name} vs ${manifest.name}`
+			))
+		} else {
+			results.push(result('Cross-file', 'name', 'name_match', 'pass',
+				`Names match: "${frontmatter.name}"`
+			))
+		}
+	}
+
+	// Executable code in SKILL.md
+	if (skill_md_content) {
+		results.push(...scan_code_blocks(skill_md_content, 'SKILL.md'))
+	}
+
+	// Executable code in references/*.md
+	const refs_dir = path.join(skill_dir, 'references')
+	try {
+		const entries = await fs.promises.readdir(refs_dir, { withFileTypes: true })
+		for (const entry of entries) {
+			if (!entry.isFile() || !entry.name.endsWith('.md')) continue
+			const ref_path = path.join(refs_dir, entry.name)
+			const ref_content = await fs.promises.readFile(ref_path, 'utf-8')
+			results.push(...scan_code_blocks(ref_content, `references/${entry.name}`))
+		}
+	} catch {
+		// No references dir — that's fine
+	}
+
+	return results
+})
+
+module.exports = { validate_cross }

package/src/validation/cross_rules.test.js

@@ -0,0 +1,88 @@
+'use strict'
+const { describe, it, beforeEach, afterEach } = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const { validate_cross } = require('./cross_rules')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-validate-cross-'))
+
+let tmp
+beforeEach(() => { tmp = make_tmp() })
+afterEach(() => { fs.rmSync(tmp, { recursive: true, force: true }) })
+
+describe('validate_cross — name match', () => {
+	it('passes when names match', async () => {
+		const [err, results] = await validate_cross(tmp, { name: 'my-skill' }, { name: 'my-skill' }, '')
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'name_match')
+		assert.strictEqual(check.severity, 'pass')
+	})
+
+	it('warns when names differ', async () => {
+		const [err, results] = await validate_cross(tmp, { name: 'skill-a' }, { name: 'skill-b' }, '')
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'name_match')
+		assert.strictEqual(check.severity, 'warning')
+		assert.ok(check.message.includes('skill-a'))
+		assert.ok(check.message.includes('skill-b'))
+	})
+
+	it('skips name match when frontmatter is null', async () => {
+		const [err, results] = await validate_cross(tmp, null, { name: 'my-skill' }, '')
+		assert.ifError(err)
+		assert.ok(!results.some(r => r.rule === 'name_match'))
+	})
+
+	it('skips name match when manifest is null', async () => {
+		const [err, results] = await validate_cross(tmp, { name: 'my-skill' }, null, '')
+		assert.ifError(err)
+		assert.ok(!results.some(r => r.rule === 'name_match'))
+	})
+})
+
+describe('validate_cross — executable code detection', () => {
+	it('warns for a long python code block in SKILL.md', async () => {
+		const code_block = '```python\nimport os\nimport sys\n' + 'print("hello")\n'.repeat(10) + '```'
+		const [err, results] = await validate_cross(tmp, { name: 'x' }, { name: 'x' }, code_block)
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'no_executable_code')
+		assert.strictEqual(check.severity, 'warning')
+		assert.ok(check.message.includes('python'))
+	})
+
+	it('does not flag short documentation code blocks', async () => {
+		const code_block = '```python\nprint("hello")\n```'
+		const [err, results] = await validate_cross(tmp, { name: 'x' }, { name: 'x' }, code_block)
+		assert.ifError(err)
+		assert.ok(!results.some(r => r.rule === 'no_executable_code'))
+	})
+
+	it('does not flag non-executable language blocks', async () => {
+		const code_block = '```yaml\nname: test\nversion: 1.0.0\n```'
+		const [err, results] = await validate_cross(tmp, { name: 'x' }, { name: 'x' }, code_block)
+		assert.ifError(err)
+		assert.ok(!results.some(r => r.rule === 'no_executable_code'))
+	})
+
+	it('warns for executable code in references/*.md', async () => {
+		const refs_dir = path.join(tmp, 'references')
+		fs.mkdirSync(refs_dir)
+		const code = '```bash\n#!/bin/bash\nimport os\nset -e\necho "deploy"\n' + 'echo "step"\n'.repeat(8) + '```'
+		fs.writeFileSync(path.join(refs_dir, 'deploy.md'), code)
+
+		const [err, results] = await validate_cross(tmp, { name: 'x' }, { name: 'x' }, '')
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'no_executable_code' && r.file === 'references/deploy.md')
+		assert.strictEqual(check.severity, 'warning')
+	})
+
+	it('does not error when references dir is missing', async () => {
+		const [err, results] = await validate_cross(tmp, { name: 'x' }, { name: 'x' }, '')
+		assert.ifError(err)
+		// Should not throw or produce error results — just no code block warnings
+		assert.ok(!results.some(r => r.severity === 'error'))
+	})
+})