happyskills 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-03-11
+
+### Added
+- Add `--kit` flag to `init` command for scaffolding kits — generates `skill.json` with `type: "kit"` and `SKILL.md` without frontmatter
+- Add `--type` flag to `search` command to filter results by type (`skill` or `kit`)
+- Add `[kit]` badge to `list` and `search` table output for kit-type entries
+- Add `type` field to `list` and `search` JSON output
+- Add `type` field to lock file entries written by the installer (read from the downloaded package's `skill.json`)
+- Add `validate_type` rule to skill.json validation — warns if `type` is absent, errors if invalid
+- Add kit-specific validation: kits skip SKILL.md frontmatter checks, line count warnings, name match, and code block scanning
+- Add kit-specific warning when a kit has no dependencies
+
+## [0.10.1] - 2026-03-11
+
+### Fixed
+- Fix `publish` and `convert` dependency/registry checks returning 403 for private skills by passing authenticated requests to `get_repo`
+- Fix `publish` failing with "Could not determine owner" on first publish when no lock entry exists — owner resolution is now soft, falling back to workspace selection
+- Fix `publish` not creating a lock entry on first publish — a new entry with `requested_by: ['__root__']` is now auto-created after a successful push
+- Fix `convert` overwriting enriched `skill.json` fields (authors, license, repository, dependencies, etc.) — now merges with the existing manifest, preserving fields set during post-init enrichment
+
 ## [0.10.0] - 2026-03-11
 
 ### Added

package/package.json

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

@@ -40,8 +40,8 @@ const get_refs = (owner, repo) => catch_errors(`Get refs for ${owner}/${repo} fa
 	return data
 })
 
-const get_repo = (owner, repo) => catch_errors(`Get repo ${owner}/${repo} failed`, async () => {
-	const [errors, data] = await client.get(`/repos/${owner}/${repo}`, { auth: false })
+const get_repo = (owner, repo, options = {}) => catch_errors(`Get repo ${owner}/${repo} failed`, async () => {
+	const [errors, data] = await client.get(`/repos/${owner}/${repo}`, { auth: options.auth || false })
 	if (errors) throw errors[errors.length - 1]
 	return data
 })

package/src/commands/convert.js

@@ -6,6 +6,7 @@ const { require_token } = require('../auth/token_store')
 const repos_api = require('../api/repos')
 const workspaces_api = require('../api/workspaces')
 const { parse_frontmatter } = require('../utils/skill_scanner')
+const { read_manifest } = require('../manifest/reader')
 const { write_manifest } = require('../manifest/writer')
 const { read_lock } = require('../lock/reader')
 const { write_lock, update_lock_skills } = require('../lock/writer')
@@ -95,7 +96,7 @@ const run = (args) => catch_errors('Convert failed', async () => {
 	const fm_keywords = frontmatter?.keywords
 		? frontmatter.keywords.split(',').map(k => k.trim()).filter(Boolean)
 		: []
-	const keywords = args.flags.keywords
+	const display_keywords = args.flags.keywords
 		? args.flags.keywords.split(',').map(k => k.trim()).filter(Boolean)
 		: fm_keywords
 
@@ -126,7 +127,7 @@ const run = (args) => catch_errors('Convert failed', async () => {
 	const workspace = choose_workspace(workspaces, args.flags.workspace)
 
 	spinner.update('Checking registry...')
-	const [repo_err] = await repos_api.get_repo(workspace.slug, skill_name)
+	const [repo_err] = await repos_api.get_repo(workspace.slug, skill_name, { auth: true })
 	if (!repo_err) {
 		spinner.stop()
 		throw new CliError(`Skill "${workspace.slug}/${skill_name}" already exists in the registry. Use \`happyskills publish\` instead to push a new version.`, EXIT_CODES.ERROR)
@@ -140,7 +141,7 @@ const run = (args) => catch_errors('Convert failed', async () => {
 		console.error(`  Workspace:   ${workspace.slug}`)
 		console.error(`  Version:     ${version}`)
 		console.error(`  Description: ${description || '(none)'}`)
-		console.error(`  Keywords:    ${keywords.length ? keywords.join(', ') : '(none)'}`)
+		console.error(`  Keywords:    ${display_keywords.length ? display_keywords.join(', ') : '(none)'}`)
 		console.error('')
 		const answer = await confirm('Convert this skill to a managed package? [y/N] ')
 		if (answer !== 'y' && answer !== 'yes') {
@@ -151,7 +152,19 @@ const run = (args) => catch_errors('Convert failed', async () => {
 
 	const pub_spinner = create_spinner('Writing skill.json...')
 
-	const manifest = { name: skill_name, version, description, keywords }
+	const [, existing_manifest] = await read_manifest(skill_dir)
+	const merged_version = args.flags.version || (existing_manifest?.version) || '1.0.0'
+	const merged_description = (existing_manifest?.description) || description
+	const merged_keywords = args.flags.keywords
+		? args.flags.keywords.split(',').map(k => k.trim()).filter(Boolean)
+		: (existing_manifest?.keywords?.length ? existing_manifest.keywords : fm_keywords)
+	const manifest = {
+		...(existing_manifest || {}),
+		name: skill_name,
+		version: merged_version,
+		description: merged_description,
+		keywords: merged_keywords
+	}
 	const [manifest_err] = await write_manifest(skill_dir, manifest)
 	if (manifest_err) { pub_spinner.fail('Failed to write skill.json'); throw e('Failed to write skill.json', manifest_err) }
 
@@ -163,12 +176,12 @@ const run = (args) => catch_errors('Convert failed', async () => {
 	const full_name = `${workspace.slug}/${skill_name}`
 	const updates = {
 		[full_name]: {
-			version,
+			version: merged_version,
 			ref: null,
 			commit: null,
 			integrity: integrity || null,
 			requested_by: ['__root__'],
-			dependencies: {}
+			dependencies: manifest.dependencies || {}
 		}
 	}
 
@@ -176,14 +189,14 @@ const run = (args) => catch_errors('Convert failed', async () => {
 	const [lock_err] = await write_lock(lock_dir, new_skills)
 	if (lock_err) { pub_spinner.fail('Failed to write lock file'); throw e('Lock write failed', lock_err) }
 
-	pub_spinner.succeed(`Converted ${full_name}@${version}`)
+	pub_spinner.succeed(`Converted ${full_name}@${merged_version}`)
 
 	if (args.flags.json) {
 		const json_data = {
 			skill: full_name,
-			version,
+			version: merged_version,
 			workspace: workspace.slug,
-			description: description || ''
+			description: merged_description || ''
 		}
 		if (frontmatter_warnings.length > 0) json_data.warnings = frontmatter_warnings
 		print_json({ data: json_data })

package/src/commands/init.js

@@ -4,7 +4,7 @@ const { write_manifest } = require('../manifest/writer')
 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, UsageError } = require('../utils/errors')
-const { SKILL_JSON, SKILL_MD, EXIT_CODES } = require('../constants')
+const { SKILL_JSON, SKILL_MD, EXIT_CODES, SKILL_TYPES } = require('../constants')
 const { find_project_root, skills_dir } = require('../config/paths')
 
 const HELP_TEXT = `Usage: happyskills init <name> [options]
@@ -20,11 +20,13 @@ Arguments:
 
 Options:
   -g, --global  Create in global skills (~/.claude/skills/)
+  --kit         Initialize as a kit (collection of skills)
   --json        Output as JSON
 
 Examples:
   happyskills init my-deploy-skill
-  happyskills init my-deploy-skill -g`
+  happyskills init my-deploy-skill -g
+  happyskills init my-kit --kit`
 
 const create_skill_md = (name) => `---
 name: ${name}
@@ -38,11 +40,25 @@ description: Describe what this skill does and when to invoke it
 Provide step-by-step instructions for the AI agent to follow.
 `
 
-const create_manifest = (name) => ({
+const create_kit_md = (name) => `# ${name}
+
+This is a kit — a curated collection of skills installed together in one command.
+
+## What's Included
+
+Add the skills this kit bundles and why they work well together.
+
+## When to Use
+
+Describe the project type or workflow this kit is designed for.
+`
+
+const create_manifest = (name, is_kit = false) => ({
 	name,
 	version: '0.1.0',
 	description: '',
 	keywords: [],
+	...(is_kit ? { type: SKILL_TYPES.KIT } : {}),
 	dependencies: {}
 })
 
@@ -58,6 +74,7 @@ const run = (args) => catch_errors('Init failed', async () => {
 	}
 
 	const is_global = args.flags.global || false
+	const is_kit = args.flags.kit || 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)
@@ -70,7 +87,7 @@ const run = (args) => catch_errors('Init failed', async () => {
 	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 manifest = create_manifest(name, is_kit)
 	const [write_err] = await write_manifest(dir, manifest)
 	if (write_err) throw e('Failed to write manifest', write_err)
 
@@ -78,19 +95,22 @@ const run = (args) => catch_errors('Init failed', async () => {
 
 	const [, md_exists] = await file_exists(path.join(dir, SKILL_MD))
 	if (!md_exists) {
-		const [md_err] = await write_file(path.join(dir, SKILL_MD), create_skill_md(name))
+		const md_content = is_kit ? create_kit_md(name) : create_skill_md(name)
+		const [md_err] = await write_file(path.join(dir, SKILL_MD), md_content)
 		if (md_err) throw e('Failed to write SKILL.md', md_err)
 		files_created.push(SKILL_MD)
 	}
 
+	const label = is_kit ? 'kit' : 'skill'
+
 	if (args.flags.json) {
-		print_json({ data: { name, files_created, directory: dir } })
+		print_json({ data: { name, type: is_kit ? SKILL_TYPES.KIT : SKILL_TYPES.SKILL, files_created, directory: dir } })
 		return
 	}
 
-	print_success(`Initialized skill "${name}" at ${dir}`)
+	print_success(`Initialized ${label} "${name}" at ${dir}`)
 	console.log(`  ${SKILL_JSON}  — manifest`)
-	console.log(`  ${SKILL_MD}    — instructions`)
+	console.log(`  ${SKILL_MD}    — ${is_kit ? 'kit description' : 'instructions'}`)
 	console.log()
 	print_hint(`Edit these files, then run ${code('happyskills publish')} to share.`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })

package/src/commands/list.js

@@ -1,11 +1,11 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { skills_dir, skill_install_dir, find_project_root, lock_root } = require('../config/paths')
-const { file_exists } = require('../utils/fs')
+const { file_exists, read_json } = require('../utils/fs')
 const { scan_skills_dir } = require('../utils/skill_scanner')
 const { print_help, print_table, print_json, print_info } = require('../ui/output')
 const { exit_with_error } = require('../utils/errors')
-const { EXIT_CODES } = require('../constants')
+const { EXIT_CODES, SKILL_JSON, SKILL_TYPES } = require('../constants')
 
 const HELP_TEXT = `Usage: happyskills list [options]
 
@@ -49,6 +49,15 @@ const run = (args) => catch_errors('List failed', async () => {
 		return
 	}
 
+	// Resolve type for each managed entry from lock data or skill.json on disk
+	const resolve_type = async (name, data) => {
+		if (data.type) return data.type
+		const dir = skill_install_dir(base_dir, name.split('/')[1])
+		const json_path = require('path').join(dir, SKILL_JSON)
+		const [, manifest] = await read_json(json_path)
+		return manifest?.type || SKILL_TYPES.SKILL
+	}
+
 	if (args.flags.json) {
 		const skills_map = {}
 		for (const [name, data] of managed_entries) {
@@ -56,7 +65,8 @@ const run = (args) => catch_errors('List failed', async () => {
 			const [, exists] = await file_exists(dir)
 			const status = exists ? 'installed' : 'missing'
 			const source = data.requested_by?.includes('__root__') ? 'direct' : 'dep'
-			skills_map[name] = { version: data.version, source, status }
+			const type = await resolve_type(name, data)
+			skills_map[name] = { version: data.version, type, source, status }
 		}
 		const external = external_skills.map(s => ({ name: s.name, description: s.description || '' }))
 		print_json({ data: { skills: skills_map, external } })
@@ -69,7 +79,9 @@ const run = (args) => catch_errors('List failed', async () => {
 		const [, exists] = await file_exists(dir)
 		const status = exists ? 'installed' : 'missing'
 		const source = data.requested_by?.includes('__root__') ? 'direct' : 'dep'
-		rows.push([name, data.version, source, status])
+		const type = await resolve_type(name, data)
+		const display_name = type === SKILL_TYPES.KIT ? `${name} [kit]` : name
+		rows.push([display_name, data.version, source, status])
 	}
 
 	for (const s of external_skills) {

package/src/commands/publish.js

@@ -86,12 +86,13 @@ const run = (args) => catch_errors('Publish failed', async () => {
 	}
 
 	// Run full validation — block on errors, show warnings
+	const skill_type = manifest.type
 	const dir_name = path.basename(dir)
-	const [md_err, md_data] = await validate_skill_md(dir, dir_name)
+	const [md_err, md_data] = await validate_skill_md(dir, dir_name, skill_type)
 	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)
+	const [cross_err, cross_results] = await validate_cross(dir, md_data.frontmatter, json_data.manifest, md_data.content, skill_type)
 	if (cross_err) throw cross_err
 
 	const all_results = [...md_data.results, ...json_data.results, ...cross_results]
@@ -124,12 +125,8 @@ const run = (args) => catch_errors('Publish failed', async () => {
 
 	let owner = args.flags.workspace
 	if (!owner) {
-		const [owner_err, resolved_owner] = await resolve_skill_owner(skill_name)
-		if (owner_err) {
-			spinner.fail('Could not determine owner')
-			throw e('Could not determine skill owner from lock file. Use --workspace <slug> to specify.', owner_err)
-		}
-		owner = resolved_owner
+		const [, resolved_owner] = await resolve_skill_owner(skill_name)
+		if (resolved_owner) owner = resolved_owner
 	}
 
 	const [ws_err, workspaces] = await workspaces_api.list_workspaces()
@@ -144,7 +141,7 @@ const run = (args) => catch_errors('Publish failed', async () => {
 			const parts = dep.split('/')
 			if (parts.length !== 2) return { dep, missing: true }
 			const [dep_owner, dep_name] = parts
-			const [err] = await repos_api.get_repo(dep_owner, dep_name)
+			const [err] = await repos_api.get_repo(dep_owner, dep_name, { auth: true })
 			return { dep, missing: !!err }
 		}))
 		const missing = dep_results.filter(r => r.missing)
@@ -182,8 +179,8 @@ const run = (args) => catch_errors('Publish failed', async () => {
 		const all_skills = get_all_locked_skills(lock_data)
 		const suffix = `/${skill_name}`
 		const lock_key = Object.keys(all_skills).find(k => k.endsWith(suffix))
+		const [hash_err, integrity] = await hash_directory(dir)
 		if (lock_key && all_skills[lock_key]) {
-			const [hash_err, integrity] = await hash_directory(dir)
 			const updated_entry = {
 				...all_skills[lock_key],
 				version: manifest.version,
@@ -193,6 +190,17 @@ const run = (args) => catch_errors('Publish failed', async () => {
 			if (!hash_err && integrity) updated_entry.integrity = integrity
 			const updated_skills = update_lock_skills(lock_data, { [lock_key]: updated_entry })
 			await write_lock(project_root, updated_skills)
+		} else {
+			const new_entry = {
+				version: manifest.version,
+				ref: push_data?.ref || `refs/tags/v${manifest.version}`,
+				commit: push_data?.commit || null,
+				integrity: (!hash_err && integrity) ? integrity : null,
+				requested_by: ['__root__'],
+				dependencies: manifest.dependencies || {}
+			}
+			const updated_skills = update_lock_skills(lock_data, { [full_name]: new_entry })
+			await write_lock(project_root, updated_skills)
 		}
 	}
 

package/src/commands/search.js

@@ -2,7 +2,7 @@ const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const repos_api = require('../api/repos')
 const { print_help, print_table, print_json, print_info } = require('../ui/output')
 const { exit_with_error, UsageError, AuthError } = require('../utils/errors')
-const { EXIT_CODES } = require('../constants')
+const { EXIT_CODES, VALID_SKILL_TYPES } = require('../constants')
 const { load_token } = require('../auth/token_store')
 
 const HELP_TEXT = `Usage: happyskills search [query] [options]
@@ -17,6 +17,7 @@ Options:
   --mine                  Search across all your workspaces
   --personal              Search only your personal workspace
   --tags <tags>           Filter by tags (comma-separated)
+  --type <type>           Filter by type (skill, kit)
   --json                  Output as JSON
 
 Aliases: s
@@ -25,6 +26,7 @@ Examples:
   happyskills search deploy
   happyskills search --mine
   happyskills search deploy --workspace acme
+  happyskills search --type kit
   happyskills s --personal --json`
 
 const run = (args) => catch_errors('Search failed', async () => {
@@ -34,13 +36,17 @@ const run = (args) => catch_errors('Search failed', async () => {
 	}
 
 	const query = args._.join(' ') || null
-	const { mine, personal, workspace, tags } = args.flags
+	const { mine, personal, workspace, tags, type } = args.flags
 	const has_scope_flag = mine || personal || workspace
 
-	if (!query && !has_scope_flag && !tags) {
+	if (!query && !has_scope_flag && !tags && !type) {
 		throw new UsageError('Please provide a search query or use --mine, --personal, or --workspace.')
 	}
 
+	if (type && !VALID_SKILL_TYPES.includes(type)) {
+		throw new UsageError(`--type must be one of: ${VALID_SKILL_TYPES.join(', ')}`)
+	}
+
 	const scope = mine ? 'mine' : personal ? 'personal' : undefined
 
 	if (has_scope_flag) {
@@ -54,6 +60,7 @@ const run = (args) => catch_errors('Search failed', async () => {
 	if (scope) options.scope = scope
 	if (workspace) options.workspace = workspace
 	if (tags) options.tags = tags
+	if (type) options.type = type
 
 	const [errors, results] = await repos_api.search(query, options)
 	if (errors) throw e('Search failed', errors)
@@ -74,6 +81,7 @@ const run = (args) => catch_errors('Search failed', async () => {
 	if (args.flags.json) {
 		const mapped = items.map(item => ({
 			skill: `${item.owner || item.workspace_slug}/${item.name}`,
+			type: item.type || 'skill',
 			description: item.description || '',
 			version: item.latest_version || item.version || '-',
 			visibility: item.visibility || 'public'
@@ -82,11 +90,16 @@ const run = (args) => catch_errors('Search failed', async () => {
 		return
 	}
 
-	const rows = items.map(item => [
-		`${item.owner || item.workspace_slug}/${item.name}`,
-		item.description || '',
-		item.latest_version || item.version || '-'
-	])
+	const rows = items.map(item => {
+		const item_type = item.type || 'skill'
+		const name = `${item.owner || item.workspace_slug}/${item.name}`
+		const display_name = item_type === 'kit' ? `${name} [kit]` : name
+		return [
+			display_name,
+			item.description || '',
+			item.latest_version || item.version || '-'
+		]
+	})
 
 	print_table(['Skill', 'Description', 'Version'], rows)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })

package/src/commands/validate.js

@@ -3,12 +3,12 @@ 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 { file_exists, read_json } = 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 { EXIT_CODES, SKILL_MD, SKILL_JSON, SKILL_TYPES } = require('../constants')
 
 const HELP_TEXT = `Usage: happyskills validate <skill-name> [options]
 
@@ -118,8 +118,19 @@ const run = (args) => catch_errors('Validate failed', async () => {
 	const skill_dir = await resolve_validate_dir(skill_name, is_global)
 	const dir_name = path.basename(skill_dir)
 
+	// Read skill_type from skill.json if it exists
+	let skill_type
+	const json_path = path.join(skill_dir, SKILL_JSON)
+	const [, json_exists] = await file_exists(json_path)
+	if (json_exists) {
+		const [, raw_manifest] = await read_json(json_path)
+		if (raw_manifest) skill_type = raw_manifest.type
+	}
+
+	const is_kit = skill_type === SKILL_TYPES.KIT
+
 	// Run all rule modules
-	const [md_err, md_data] = await validate_skill_md(skill_dir, dir_name)
+	const [md_err, md_data] = await validate_skill_md(skill_dir, dir_name, skill_type)
 	if (md_err) throw md_err
 
 	const [json_err, json_data] = await validate_skill_json(skill_dir)
@@ -129,16 +140,18 @@ const run = (args) => catch_errors('Validate failed', async () => {
 		skill_dir,
 		md_data.frontmatter,
 		json_data.manifest,
-		md_data.content
+		md_data.content,
+		skill_type
 	)
 	if (cross_err) throw cross_err
 
 	const all_results = [...md_data.results, ...json_data.results, ...cross_results]
+	const type_label = is_kit ? ' [kit]' : ''
 
 	if (args.flags.json) {
 		format_json(skill_name, all_results)
 	} else {
-		format_human(skill_name, all_results)
+		format_human(skill_name + type_label, all_results)
 	}
 
 	const has_errors = all_results.some(r => r.severity === 'error')

package/src/constants.js

@@ -12,6 +12,9 @@ const EXIT_CODES = {
 	NETWORK: 4
 }
 
+const SKILL_TYPES = { SKILL: 'skill', KIT: 'kit' }
+const VALID_SKILL_TYPES = ['skill', 'kit']
+
 const LOCK_VERSION = 1
 
 const SKILL_JSON = 'skill.json'
@@ -59,6 +62,8 @@ module.exports = {
 	API_URL,
 	CLI_VERSION,
 	EXIT_CODES,
+	SKILL_TYPES,
+	VALID_SKILL_TYPES,
 	LOCK_VERSION,
 	SKILL_JSON,
 	SKILL_MD,

package/src/engine/installer.js

@@ -9,7 +9,8 @@ const { hash_directory, verify_integrity } = require('../lock/integrity')
 const { read_lock, get_locked_skill } = require('../lock/reader')
 const { write_lock, update_lock_skills } = require('../lock/writer')
 const { skills_dir, tmp_dir, skill_install_dir, lock_root } = require('../config/paths')
-const { ensure_dir, remove_dir, file_exists } = require('../utils/fs')
+const { ensure_dir, remove_dir, file_exists, read_json } = require('../utils/fs')
+const { SKILL_JSON } = require('../constants')
 const { create_spinner } = require('../ui/spinner')
 const { print_success, print_warn } = require('../ui/output')
 
@@ -137,6 +138,12 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 			const final_dir = skill_install_dir(base_dir, name)
 			const [, integrity] = await hash_directory(final_dir)
 
+			// Read type from the installed package's skill.json
+			let pkg_type
+			const pkg_json_path = path.join(final_dir, SKILL_JSON)
+			const [, pkg_manifest] = await read_json(pkg_json_path)
+			if (pkg_manifest?.type) pkg_type = pkg_manifest.type
+
 			updates[pkg.skill] = {
 				version: pkg.version,
 				ref: pkg.ref,
@@ -144,6 +151,7 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 				integrity: integrity || null,
 				requested_by: pkg.skill === skill ? ['__root__'] : [skill],
 				dependencies: pkg.dependencies || {},
+				...(pkg_type ? { type: pkg_type } : {}),
 				...(pkg.forced ? { forced: true } : {})
 			}
 		}

package/src/validation/cross_rules.js

@@ -1,6 +1,7 @@
 const fs = require('fs')
 const path = require('path')
 const { error: { catch_errors } } = require('puffy-core')
+const { SKILL_TYPES } = require('../constants')
 
 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)/
@@ -34,9 +35,13 @@ const scan_code_blocks = (content, file_label) => {
 	return results
 }
 
-const validate_cross = (skill_dir, frontmatter, manifest, skill_md_content) => catch_errors('Failed cross-file validation', async () => {
+const validate_cross = (skill_dir, frontmatter, manifest, skill_md_content, skill_type) => catch_errors('Failed cross-file validation', async () => {
 	const results = []
 
+	if (skill_type === SKILL_TYPES.KIT) {
+		return results
+	}
+
 	// Name match
 	if (frontmatter && manifest) {
 		if (frontmatter.name !== manifest.name) {

package/src/validation/cross_rules.test.js

@@ -43,6 +43,28 @@ describe('validate_cross — name match', () => {
 	})
 })
 
+describe('validate_cross — kit type', () => {
+	it('skips all checks for kit type', async () => {
+		const [err, results] = await validate_cross(tmp, { name: 'skill-a' }, { name: 'skill-b' }, '```python\nimport os\nimport sys\n' + 'print("hello")\n'.repeat(10) + '```', 'kit')
+		assert.ifError(err)
+		assert.strictEqual(results.length, 0)
+	})
+
+	it('still runs checks when skill_type is undefined', 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')
+	})
+
+	it('still runs checks when skill_type is "skill"', async () => {
+		const [err, results] = await validate_cross(tmp, { name: 'skill-a' }, { name: 'skill-b' }, '', 'skill')
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'name_match')
+		assert.strictEqual(check.severity, 'warning')
+	})
+})
+
 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) + '```'

package/src/validation/skill_json_rules.js

@@ -2,7 +2,7 @@ const path = require('path')
 const { error: { catch_errors } } = require('puffy-core')
 const { file_exists, read_file } = require('../utils/fs')
 const { valid } = require('../utils/semver')
-const { SKILL_JSON } = require('../constants')
+const { SKILL_JSON, VALID_SKILL_TYPES, SKILL_TYPES } = require('../constants')
 
 const NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/
 const CANONICAL_SLUGS = ['deployment', 'database', 'security', 'ai', 'api', 'monitoring', 'testing', 'devops', 'cloud', 'analytics']
@@ -93,6 +93,24 @@ const validate_keywords = (manifest) => {
 	return results
 }
 
+const validate_type = (manifest) => {
+	const results = []
+	const type = manifest.type
+
+	if (type === undefined) {
+		results.push(result('type', 'present', 'warning', 'type field is recommended (defaults to "skill")'))
+		return results
+	}
+
+	if (!VALID_SKILL_TYPES.includes(type)) {
+		results.push(result('type', 'valid_value', 'error', `type must be one of: ${VALID_SKILL_TYPES.join(', ')} — got "${type}"`, type))
+	} else {
+		results.push(result('type', 'valid_value', 'pass', `type: "${type}"`, type))
+	}
+
+	return results
+}
+
 const validate_dependencies = (manifest) => {
 	const results = []
 	const deps = manifest.dependencies
@@ -191,11 +209,20 @@ const validate_skill_json = (skill_dir) => catch_errors('Failed to validate skil
 
 	results.push(...validate_name(manifest))
 	results.push(...validate_version(manifest))
+	results.push(...validate_type(manifest))
 	results.push(...validate_description(manifest))
 	results.push(...validate_keywords(manifest))
 	results.push(...validate_dependencies(manifest))
 	results.push(...validate_system_dependencies(manifest))
 
+	const is_kit = manifest.type === SKILL_TYPES.KIT
+	if (is_kit) {
+		const deps = manifest.dependencies
+		if (!deps || Object.keys(deps).length === 0) {
+			results.push(result('dependencies', 'kit_has_deps', 'warning', 'Kit has no dependencies — a kit typically bundles one or more skills'))
+		}
+	}
+
 	return { results, manifest }
 })
 

package/src/validation/skill_json_rules.test.js

@@ -187,6 +187,74 @@ describe('validate_skill_json — dependencies', () => {
 	})
 })
 
+describe('validate_skill_json — type', () => {
+	it('warns when type is missing', async () => {
+		write_json(tmp, { name: 'my-skill', version: '1.0.0' })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'type' && r.rule === 'present')
+		assert.strictEqual(check.severity, 'warning')
+	})
+
+	it('passes for type "skill"', async () => {
+		write_json(tmp, { name: 'my-skill', version: '1.0.0', type: 'skill' })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'type' && r.rule === 'valid_value')
+		assert.strictEqual(check.severity, 'pass')
+	})
+
+	it('passes for type "kit"', async () => {
+		write_json(tmp, { name: 'my-kit', version: '1.0.0', type: 'kit' })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'type' && r.rule === 'valid_value')
+		assert.strictEqual(check.severity, 'pass')
+	})
+
+	it('errors for invalid type value', async () => {
+		write_json(tmp, { name: 'my-skill', version: '1.0.0', type: 'plugin' })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'type' && r.rule === 'valid_value')
+		assert.strictEqual(check.severity, 'error')
+		assert.ok(check.message.includes('plugin'))
+	})
+})
+
+describe('validate_skill_json — kit dependencies', () => {
+	it('warns when kit has no dependencies', async () => {
+		write_json(tmp, { name: 'my-kit', version: '1.0.0', type: 'kit' })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.rule === 'kit_has_deps')
+		assert.strictEqual(check.severity, 'warning')
+		assert.ok(check.message.includes('no dependencies'))
+	})
+
+	it('warns when kit has empty dependencies object', async () => {
+		write_json(tmp, { name: 'my-kit', version: '1.0.0', type: 'kit', dependencies: {} })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.rule === 'kit_has_deps')
+		assert.strictEqual(check.severity, 'warning')
+	})
+
+	it('does not warn when kit has dependencies', async () => {
+		write_json(tmp, { name: 'my-kit', version: '1.0.0', type: 'kit', dependencies: { 'acme/deploy': '^1.0.0' } })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		assert.ok(!data.results.some(r => r.rule === 'kit_has_deps'))
+	})
+
+	it('does not produce kit_has_deps warning for regular skills', async () => {
+		write_json(tmp, { name: 'my-skill', version: '1.0.0', type: 'skill' })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		assert.ok(!data.results.some(r => r.rule === 'kit_has_deps'))
+	})
+})
+
 describe('validate_skill_json — systemDependencies', () => {
 	it('errors when systemDependencies is an array', async () => {
 		write_json(tmp, { name: 'my-skill', version: '1.0.0', systemDependencies: [] })

package/src/validation/skill_md_rules.js

@@ -2,7 +2,7 @@ const path = require('path')
 const { error: { catch_errors } } = require('puffy-core')
 const { file_exists, read_file } = require('../utils/fs')
 const { parse_frontmatter } = require('../utils/skill_scanner')
-const { SKILL_MD } = require('../constants')
+const { SKILL_MD, SKILL_TYPES } = require('../constants')
 
 const FORBIDDEN_CHARS = {
 	';': 'semicolon', ':': 'colon', '#': 'hash', '{': 'left brace', '}': 'right brace',
@@ -130,9 +130,10 @@ const validate_optional_fields = (fm) => {
 	return results
 }
 
-const validate_skill_md = (skill_dir, dir_name) => catch_errors('Failed to validate SKILL.md', async () => {
+const validate_skill_md = (skill_dir, dir_name, skill_type) => catch_errors('Failed to validate SKILL.md', async () => {
 	const results = []
 	const md_path = path.join(skill_dir, SKILL_MD)
+	const is_kit = skill_type === SKILL_TYPES.KIT
 
 	const [, exists] = await file_exists(md_path)
 	if (!exists) {
@@ -143,6 +144,11 @@ const validate_skill_md = (skill_dir, dir_name) => catch_errors('Failed to valid
 	results.push(result(null, 'exists', 'pass', 'SKILL.md exists'))
 
 	const [, content] = await read_file(md_path)
+
+	if (is_kit) {
+		return { results, frontmatter: null, content }
+	}
+
 	const fm = parse_frontmatter(content)
 
 	if (!fm) {

package/src/validation/skill_md_rules.test.js

@@ -181,6 +181,43 @@ describe('validate_skill_md — optional fields', () => {
 	})
 })
 
+describe('validate_skill_md — kit type', () => {
+	it('errors when SKILL.md is missing for a kit', async () => {
+		const [err, data] = await validate_skill_md(tmp, 'my-kit', 'kit')
+		assert.ifError(err)
+		const check = data.results.find(r => r.rule === 'exists')
+		assert.strictEqual(check.severity, 'error')
+	})
+
+	it('passes when SKILL.md exists for a kit (no frontmatter required)', async () => {
+		fs.writeFileSync(path.join(tmp, 'SKILL.md'), '# My Kit\n\nThis is a kit.')
+		const [err, data] = await validate_skill_md(tmp, 'my-kit', 'kit')
+		assert.ifError(err)
+		const exists_check = data.results.find(r => r.rule === 'exists')
+		assert.strictEqual(exists_check.severity, 'pass')
+		assert.strictEqual(data.frontmatter, null)
+		assert.ok(data.content.includes('My Kit'))
+	})
+
+	it('skips all frontmatter validation for kits', async () => {
+		fs.writeFileSync(path.join(tmp, 'SKILL.md'), '# My Kit\n\nNo frontmatter here.')
+		const [err, data] = await validate_skill_md(tmp, 'my-kit', 'kit')
+		assert.ifError(err)
+		// Should have no frontmatter, name, or description results
+		assert.ok(!data.results.some(r => r.rule === 'frontmatter'))
+		assert.ok(!data.results.some(r => r.field === 'name'))
+		assert.ok(!data.results.some(r => r.field === 'description'))
+	})
+
+	it('skips line count validation for kits', async () => {
+		const long_content = '# My Kit\n' + 'line\n'.repeat(600)
+		fs.writeFileSync(path.join(tmp, 'SKILL.md'), long_content)
+		const [err, data] = await validate_skill_md(tmp, 'my-kit', 'kit')
+		assert.ifError(err)
+		assert.ok(!data.results.some(r => r.rule === 'line_count'))
+	})
+})
+
 describe('validate_skill_md — line count', () => {
 	it('errors when file exceeds 500 lines', async () => {
 		const lines = '---\nname: my-skill\ndescription: Does things\n---\n' + 'line\n'.repeat(500)