happyskills 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-03-11
+
+### Added
+- Add `delete` command to permanently remove a skill from the registry — requires authentication, interactive confirmation (type full `owner/name`), and `-y`/`--yes` in JSON mode; alias `del`
+- Add `-g`/`--global` flag to `init` command for scaffolding skills in the global `~/.claude/skills/` directory
+
+### Changed
+- Change `init` to create skills in `.claude/skills/<name>/` instead of the current directory — name argument is now required; `.claude/skills/` is auto-created if missing
+
+## [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

package/package.json

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

@@ -52,4 +52,10 @@ const check_updates = (skills) => catch_errors('Check updates failed', async ()
 	return data
 })
 
-module.exports = { search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates }
+const del_repo = (owner, name) => catch_errors(`Failed to delete ${owner}/${name}`, async () => {
+	const [errors, data] = await client.del(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+module.exports = { search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates, del_repo }

package/src/commands/delete.js

@@ -0,0 +1,78 @@
+const readline = require('readline')
+const { error: { catch_errors } } = require('puffy-core')
+const { del_repo } = require('../api/repos')
+const { require_token } = require('../auth/token_store')
+const { print_help, print_json, print_success, print_warn } = require('../ui/output')
+const { exit_with_error, UsageError, CliError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills delete <owner/name> [options]
+
+Permanently delete a skill from the registry.
+
+Arguments:
+  owner/name        Skill to delete (e.g., acme/deploy-aws)
+
+Options:
+  -y, --yes         Skip confirmation prompt (required with --json)
+  --json            Output as JSON
+
+Aliases: del
+
+Examples:
+  happyskills delete acme/deploy-aws
+  happyskills delete acme/deploy-aws --json -y`
+
+const _ask_confirmation = (skill) => new Promise((resolve) => {
+	const rl = readline.createInterface({ input: process.stdin, output: process.stderr })
+	print_warn(`You are about to permanently delete "${skill}" from the registry.`)
+	print_warn('This action cannot be undone.')
+	rl.question(`\nType "${skill}" to confirm: `, (answer) => {
+		rl.close()
+		resolve(answer.trim() === skill)
+	})
+})
+
+const run = (args) => catch_errors('Delete 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 to delete (e.g., happyskills delete acme/deploy-aws).')
+	}
+
+	if (!skill.includes('/')) {
+		throw new UsageError('Skill must be in owner/name format (e.g., acme/deploy-aws).')
+	}
+
+	await require_token()
+
+	const [owner, name] = skill.split('/')
+
+	if (args.flags.json) {
+		if (!args.flags.yes) {
+			throw new CliError('Confirmation required. Use -y or --yes to confirm deletion in JSON mode.', EXIT_CODES.ERROR)
+		}
+	} else {
+		const confirmed = await _ask_confirmation(skill)
+		if (!confirmed) {
+			print_warn('Delete cancelled.')
+			return process.exit(EXIT_CODES.SUCCESS)
+		}
+	}
+
+	const [errors, result] = await del_repo(owner, name)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data: { deleted: true, skill, ...(result || {}) } })
+		return
+	}
+
+	print_success(`Deleted "${skill}" from the registry.`)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run }

package/src/commands/init.js

@@ -1,28 +1,30 @@
 const path = require('path')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { write_manifest } = require('../manifest/writer')
-const { write_file, file_exists } = require('../utils/fs')
+const { write_file, file_exists, ensure_dir } = require('../utils/fs')
 const { print_success, print_error, print_help, print_hint, print_json, code } = require('../ui/output')
-const { exit_with_error, CliError } = require('../utils/errors')
+const { exit_with_error, CliError, UsageError } = require('../utils/errors')
 const { SKILL_JSON, SKILL_MD, EXIT_CODES } = require('../constants')
+const { find_project_root, skills_dir } = require('../config/paths')
 
-const HELP_TEXT = `Usage: happyskills init [name]
+const HELP_TEXT = `Usage: happyskills init <name> [options]
 
-Scaffold a new skill in the current directory.
+Scaffold a new skill in .claude/skills/<name>/.
 
 Creates:
-  skill.json    Skill manifest (name, version, deps)
-  SKILL.md      Skill instructions for AI agents
+  .claude/skills/<name>/skill.json    Skill manifest (name, version, deps)
+  .claude/skills/<name>/SKILL.md      Skill instructions for AI agents
 
 Arguments:
-  name          Skill name (defaults to directory name)
+  name          Skill name (required, e.g., my-deploy-skill)
 
 Options:
+  -g, --global  Create in global skills (~/.claude/skills/)
   --json        Output as JSON
 
 Examples:
-  happyskills init
-  happyskills init my-deploy-skill`
+  happyskills init my-deploy-skill
+  happyskills init my-deploy-skill -g`
 
 const create_skill_md = (name) => `---
 name: ${name}
@@ -50,14 +52,24 @@ const run = (args) => catch_errors('Init failed', async () => {
 		return process.exit(EXIT_CODES.SUCCESS)
 	}
 
-	const dir = process.cwd()
-	const name = args._[0] || path.basename(dir)
+	const name = args._[0]
+	if (!name) {
+		throw new UsageError('Please specify a skill name (e.g., happyskills init my-deploy-skill).')
+	}
+
+	const is_global = args.flags.global || false
+	const project_root = find_project_root()
+	const base_skills_dir = skills_dir(is_global, project_root)
+	const dir = path.join(base_skills_dir, name)
 
 	const [, json_exists] = await file_exists(path.join(dir, SKILL_JSON))
 	if (json_exists) {
-		throw new CliError(`${SKILL_JSON} already exists in this directory.`, EXIT_CODES.ERROR)
+		throw new CliError(`${SKILL_JSON} already exists at ${dir}`, EXIT_CODES.ERROR)
 	}
 
+	const [dir_err] = await ensure_dir(dir)
+	if (dir_err) throw e('Failed to create skill directory', dir_err)
+
 	const manifest = create_manifest(name)
 	const [write_err] = await write_manifest(dir, manifest)
 	if (write_err) throw e('Failed to write manifest', write_err)
@@ -76,7 +88,7 @@ const run = (args) => catch_errors('Init failed', async () => {
 		return
 	}
 
-	print_success(`Initialized skill "${name}"`)
+	print_success(`Initialized skill "${name}" at ${dir}`)
 	console.log(`  ${SKILL_JSON}  — manifest`)
 	console.log(`  ${SKILL_MD}    — instructions`)
 	console.log()

package/src/commands/publish.js

@@ -1,9 +1,7 @@
-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')
-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')
@@ -15,11 +13,13 @@ 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 { 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')
-const { EXIT_CODES, SKILL_MD } = require('../constants')
+const { EXIT_CODES } = require('../constants')
 
 const HELP_TEXT = `Usage: happyskills publish <skill-name> [options]
 
@@ -85,34 +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)
-	}
-
-	// 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.')
-			}
+	// 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)
 		}
-	} catch {
-		frontmatter_warnings.push(`No ${SKILL_MD} found. The skill may not work correctly.`)
+		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)
 	}
 
-	if (frontmatter_warnings.length > 0) {
-		for (const warning of frontmatter_warnings) {
-			print_warn(warning)
-		}
+	for (const w of validation_warnings) {
+		print_warn(`${w.file || 'General'}${w.field ? ` (${w.field})` : ''}: ${w.message}`)
 	}
 
 	const spinner = create_spinner('Preparing to publish...')
@@ -199,7 +204,7 @@ const run = (args) => catch_errors('Publish failed', async () => {
 			commit: push_data?.commit || null,
 			bumped_from
 		}
-		if (frontmatter_warnings.length > 0) json_data.warnings = frontmatter_warnings
+		if (validation_warnings.length > 0) json_data.warnings = validation_warnings.map(w => w.message)
 		print_json({ data: json_data })
 		return
 	}

package/src/constants.js

@@ -29,13 +29,15 @@ const COMMAND_ALIASES = {
 	r: 'refresh',
 	up: 'update',
 	pub: 'publish',
-	v: 'validate'
+	v: 'validate',
+	del: 'delete'
 }
 
 const COMMANDS = [
 	'init',
 	'install',
 	'uninstall',
+	'delete',
 	'list',
 	'search',
 	'check',

package/src/index.js

@@ -87,6 +87,7 @@ Commands:
   init [name]              Scaffold SKILL.md + skill.json
   install [owner/skill]    Install skill + dependencies (alias: i, add)
   uninstall <owner/skill>  Remove skill + prune orphans (alias: rm, remove)
+  delete <owner/skill>     Delete skill from registry (alias: del)
   list                     List installed skills (alias: ls)
   search <query>           Search the registry (alias: s)
   check [owner/skill]      Check for available updates

package/src/integration/cli.test.js

@@ -315,9 +315,11 @@ describe('CLI — --json: success responses use { data } envelope', () => {
 	it('init --json error when skill.json already exists returns { error }', () => {
 		const tmp = make_tmp()
 		try {
-			// Create skill.json first
-			fs.writeFileSync(path.join(tmp, 'skill.json'), '{}')
-			const { stdout, code } = run(['init', '--json'], {}, { cwd: tmp })
+			// Create .claude/skills/test-skill/skill.json first
+			const skill_dir = path.join(tmp, '.claude', 'skills', 'test-skill')
+			fs.mkdirSync(skill_dir, { recursive: true })
+			fs.writeFileSync(path.join(skill_dir, 'skill.json'), '{}')
+			const { stdout, code } = run(['init', 'test-skill', '--json'], {}, { cwd: tmp })
 			assert.strictEqual(code, 1)
 			const out = parse_json_output(stdout, 'init --json duplicate')
 			assert.ok('error' in out)
@@ -606,3 +608,83 @@ describe('CLI — validate command', () => {
 		}
 	})
 })
+
+// ─── delete command ───────────────────────────────────────────────────────────
+
+describe('CLI — delete command', () => {
+	it('delete --help outputs correct help text and exits 0', () => {
+		const { stdout, code } = run(['delete', '--help'])
+		assert.strictEqual(code, 0)
+		assert.ok(stdout.includes('Arguments:'))
+		assert.ok(stdout.includes('Options:'))
+		assert.ok(stdout.includes('Examples:'))
+		assert.ok(stdout.includes('Aliases:'))
+	})
+
+	it('delete without arguments exits with code 2 (usage error)', () => {
+		const { code, stderr } = run(['delete'])
+		assert.strictEqual(code, 2)
+		assert.ok(stderr.includes('specify a skill'))
+	})
+
+	it('delete with no slash exits with code 2 and shows owner/name format message', () => {
+		const { code, stderr } = run(['delete', 'deploy-aws'])
+		assert.strictEqual(code, 2)
+		assert.ok(stderr.includes('owner/name format'))
+	})
+
+	it('del alias resolves to delete (shows correct --help)', () => {
+		const { stdout, code } = run(['del', '--help'])
+		assert.strictEqual(code, 0)
+		assert.ok(stdout.toLowerCase().includes('delete'))
+	})
+
+	it('delete acme/deploy-aws --json without -y exits with code 1 (confirmation required)', () => {
+		const tmp_xdg = make_tmp()
+		try {
+			const creds_dir = path.join(tmp_xdg, 'happyskills')
+			fs.mkdirSync(creds_dir, { recursive: true })
+			const payload = { email: 'test@example.com', 'cognito:username': 'testuser', sub: 'test-sub-123' }
+			const fake_jwt = `eyJhbGciOiJSUzI1NiJ9.${Buffer.from(JSON.stringify(payload)).toString('base64url')}.fakesig`
+			fs.writeFileSync(path.join(creds_dir, 'credentials.json'), JSON.stringify({
+				id_token: fake_jwt,
+				access_token: 'fake-access',
+				refresh_token: 'fake-refresh',
+				expires_in: 3600,
+				stored_at: new Date().toISOString()
+			}, null, '\t'))
+			const { stdout, code } = run(['delete', 'acme/deploy-aws', '--json'], { XDG_CONFIG_HOME: tmp_xdg })
+			assert.strictEqual(code, 1)
+			const out = parse_json_output(stdout, 'delete --json no -y')
+			assert.ok('error' in out)
+			assert.ok(out.error.message.toLowerCase().includes('confirmation'))
+		} finally {
+			fs.rmSync(tmp_xdg, { recursive: true, force: true })
+		}
+	})
+
+	it('delete acme/deploy-aws --json -y exits with code 4 (network error)', () => {
+		const tmp_xdg = make_tmp()
+		try {
+			const creds_dir = path.join(tmp_xdg, 'happyskills')
+			fs.mkdirSync(creds_dir, { recursive: true })
+			const payload = { email: 'test@example.com', 'cognito:username': 'testuser', sub: 'test-sub-123' }
+			const fake_jwt = `eyJhbGciOiJSUzI1NiJ9.${Buffer.from(JSON.stringify(payload)).toString('base64url')}.fakesig`
+			fs.writeFileSync(path.join(creds_dir, 'credentials.json'), JSON.stringify({
+				id_token: fake_jwt,
+				access_token: 'fake-access',
+				refresh_token: 'fake-refresh',
+				expires_in: 3600,
+				stored_at: new Date().toISOString()
+			}, null, '\t'))
+			const { stdout, code } = run(['delete', 'acme/deploy-aws', '--json', '-y'], { XDG_CONFIG_HOME: tmp_xdg })
+			assert.strictEqual(code, 4)
+			const out = parse_json_output(stdout, 'delete --json -y network failure')
+			assert.ok('error' in out)
+			assert.strictEqual(out.error.code, 'NETWORK_ERROR')
+			assert.strictEqual(out.error.exit_code, 4)
+		} finally {
+			fs.rmSync(tmp_xdg, { recursive: true, force: true })
+		}
+	})
+})