happyskills 0.35.5 → 0.36.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.36.0] - 2026-04-17
+
+### Added
+- Add 6 dependency validation rules to `validate` command: `dep-self-reference` (skill depends on itself), `dep-exists` (all declared deps exist in registry), `dep-visibility-direct` (public skill's direct deps must be public), `dep-visibility-transitive` (full transitive tree visibility check), `dep-visibility-workspace` (warning for workspace-scoped deps on public skills), `dep-circular` (DFS cycle detection on the full dependency tree). Registry checks run when authenticated; local-only checks run otherwise with an info message suggesting login.
+- Add `extract_root_cause()` and `format_error_chain()` utilities in `utils/errors.js` for cleaner error diagnostics across all commands
+
+### Changed
+- Replace ad-hoc dependency existence check in `publish` with the new validation rules — dependency visibility errors now block publish with clear, actionable messages
+- Change `install` resolver to return `{ packages, skipped }` instead of a flat packages array. Installer prints categorized warnings for skipped deps after install: access-denied suggests `happyskills login`, not-found lists missing skill names. `skipped_deps` is included in the result object and JSON output.
+- Show root cause in `install` error messages (e.g. "Access denied: nicolasdao/init-mission") instead of the generic wrapper ("Install failed"). JSON mode error output now includes a `details` array with the full error chain.
+
+### Fixed
+- Fix `search --workspace <slug>` triggering AuthError when not logged in — only `--mine` and `--personal` flags require authentication; `--workspace` returns public skills without auth
+
 ## [0.35.5] - 2026-04-11
 
 ### Fixed

package/package.json

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

@@ -10,7 +10,7 @@ const search = (query, options = {}) => catch_errors('Search failed', async () =
 	if (options.workspace) params.set('workspace', options.workspace)
 	if (options.tags) params.set('tags', options.tags)
 	if (options.type) params.set('type', options.type)
-	const needs_auth = (options.scope && options.scope !== 'public') || options.workspace
+	const needs_auth = options.scope && options.scope !== 'public'
 	const [errors, data] = await client.get(`/repos/search?${params}`, { auth: needs_auth || false })
 	if (errors) throw errors[errors.length - 1]
 	return data

package/src/commands/install.js

@@ -107,7 +107,8 @@ const run = (args) => catch_errors('Install failed', async () => {
 		const version = flag_version || inline_version
 		const [errors, result] = await install(skill, { ...base_options, version })
 		if (errors) {
-			const msg = errors[0]?.message || errors.message || String(errors)
+			const chain = errors?.map ? errors.map(x => x?.message).filter(Boolean) : [errors?.message || String(errors)]
+			const msg = chain[chain.length - 1] || chain[0] || 'Unknown error'
 			print_warn(`Failed to install ${skill}: ${msg}`)
 			failures.push({ skill, error: msg })
 		} else {
@@ -116,7 +117,8 @@ const run = (args) => catch_errors('Install failed', async () => {
 	}
 
 	if (results.length === 0 && failures.length > 0) {
-		throw new Error(`All ${failures.length} install(s) failed.`)
+		const detail = failures.map(f => `${f.skill}: ${f.error}`).join('; ')
+		throw new Error(detail)
 	}
 
 	if (args.flags.json) {
@@ -125,6 +127,7 @@ const run = (args) => catch_errors('Install failed', async () => {
 			version: result.version,
 			installed: result.installed || [],
 			skipped: result.skipped || [],
+			skipped_deps: result.skipped_deps || [],
 			warnings: result.warnings || [],
 			forced: result.forced || []
 		}))

package/src/commands/publish.js

@@ -18,6 +18,7 @@ const { validate_skill_json } = require('../validation/skill_json_rules')
 const { validate_cross } = require('../validation/cross_rules')
 const { validate_no_conflict_markers } = require('../validation/conflict_marker_rules')
 const { validate_file_sizes } = require('../validation/file_size_rules')
+const { validate_dependencies } = require('../validation/dependency_rules')
 const { create_spinner } = require('../ui/spinner')
 const { print_help, print_success, print_error, print_warn, print_hint, print_json, code, summarize_warnings } = require('../ui/output')
 const { exit_with_error, UsageError, CliError } = require('../utils/errors')
@@ -144,21 +145,46 @@ const run = (args) => catch_errors('Publish failed', async () => {
 
 	if (manifest.dependencies && Object.keys(manifest.dependencies).length > 0) {
 		spinner.update('Checking dependencies...')
-		const dep_entries = Object.keys(manifest.dependencies)
-		const dep_results = await Promise.all(dep_entries.map(async (dep) => {
-			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, { auth: true })
-			return { dep, missing: !!err }
-		}))
-		const missing = dep_results.filter(r => r.missing)
-		if (missing.length > 0) {
-			spinner.fail('Dependency check failed')
-			for (const { dep } of missing) {
-				print_warn(`Dependency "${dep}" not found in the registry.`)
+		const full_name = `${workspace.slug}/${manifest.name}`
+		const [dep_err, dep_results] = await validate_dependencies(dir, manifest, {
+			registry: true,
+			visibility,
+			full_name
+		})
+		if (!dep_err && dep_results) {
+			const dep_errors = dep_results.filter(r => r.severity === 'error')
+			const dep_warnings = dep_results.filter(r => r.severity === 'warning')
+
+			if (dep_errors.length > 0) {
+				spinner.fail('Dependency check failed')
+				if (is_json_mode()) {
+					const structured = dep_errors.map(({ severity, ...rest }) => rest)
+					print_json({
+						error: {
+							code: 'DEPENDENCY_VALIDATION_FAILED',
+							message: `${dep_errors.length} dependency error(s) found. Fix these issues and try again.`,
+							exit_code: EXIT_CODES.ERROR,
+							validation_errors: structured
+						}
+					})
+					return process.exit(EXIT_CODES.ERROR)
+				}
+				for (const r of dep_errors) {
+					print_error(r.message)
+				}
+				return process.exit(EXIT_CODES.ERROR)
 			}
+
+			if (dep_warnings.length > 0 && !is_json_mode()) {
+				for (const r of dep_warnings) {
+					print_warn(r.message)
+				}
+			}
+
+			// Accumulate dep warnings for JSON output
+			validation_warnings.push(...dep_warnings)
 		}
+		spinner.update('Preparing to publish...')
 	}
 
 	// Read base_commit and merge_parents from lock file for divergence check

package/src/commands/search.js

@@ -236,7 +236,7 @@ const run = (args) => catch_errors('Search failed', async () => {
 
 	const scope = mine ? 'mine' : personal ? 'personal' : undefined
 
-	if (has_scope_flag) {
+	if (mine || personal) {
 		const [, token_data] = await load_token()
 		if (!token_data) {
 			throw new AuthError('Authentication required. Run `happyskills login` first.')

package/src/commands/validate.js

@@ -6,9 +6,12 @@ const { validate_cross } = require('../validation/cross_rules')
 const { validate_no_conflict_markers } = require('../validation/conflict_marker_rules')
 const { validate_file_sizes } = require('../validation/file_size_rules')
 const { validate_changelog_version } = require('../validation/changelog_rules')
+const { validate_dependencies } = require('../validation/dependency_rules')
 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 { skills_dir, find_project_root, lock_root } = require('../config/paths')
+const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { load_token } = require('../auth/token_store')
+const { print_help, print_json, print_info } = 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, SKILL_JSON, SKILL_TYPES } = require('../constants')
@@ -154,7 +157,47 @@ const run = (args) => catch_errors('Validate failed', async () => {
 	const [cl_err, cl_results] = await validate_changelog_version(skill_dir, json_data.manifest)
 	if (cl_err) throw cl_err
 
-	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results, ...size_results, ...cl_results]
+	// Dependency validation — registry checks when authenticated
+	let dep_results = []
+	const manifest = json_data.manifest || {}
+	if (manifest.dependencies && Object.keys(manifest.dependencies).length > 0) {
+		const [, token_data] = await load_token()
+		const has_registry = !!token_data
+
+		// Resolve the full owner/name for registry lookups
+		let full_name = null
+		let visibility = 'private'
+		if (has_registry) {
+			const project_root = find_project_root()
+			const [, lock_data] = await read_lock(lock_root(is_global, project_root))
+			if (lock_data) {
+				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))
+				if (lock_key) full_name = lock_key
+			}
+			// Try to get visibility from registry if we have the full name
+			if (full_name) {
+				const repos_api = require('../api/repos')
+				const [owner, name] = full_name.split('/')
+				const [, repo_data] = await repos_api.get_repo(owner, name, { auth: true })
+				if (repo_data) visibility = repo_data.visibility || 'private'
+			}
+		}
+
+		const [dep_err, dep_result] = await validate_dependencies(skill_dir, manifest, {
+			registry: has_registry,
+			visibility,
+			full_name
+		})
+		if (!dep_err && dep_result) dep_results = dep_result
+
+		if (!has_registry && !args.flags.json) {
+			print_info('Dependency registry checks skipped (not logged in). Log in for full validation.')
+		}
+	}
+
+	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results, ...size_results, ...cl_results, ...dep_results]
 	const type_label = is_kit ? ' [kit]' : ''
 
 	if (args.flags.json) {

package/src/engine/installer.js

@@ -73,14 +73,17 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 	const spinner = create_spinner(`Resolving dependencies for ${skill}...`)
 
 	let packages
+	let skipped_deps = []
 	if (force) {
 		const [errors, result] = await resolve_with_force(skill, version || 'latest', {})
 		if (errors) { spinner.fail('Resolution failed'); throw e('Resolution failed', errors) }
-		packages = result
+		packages = result.packages
+		skipped_deps = result.skipped || []
 	} else {
 		const [errors, result] = await resolve(skill, version || 'latest', {})
 		if (errors) { spinner.fail('Resolution failed'); throw e('Resolution failed', errors) }
-		packages = result
+		packages = result.packages
+		skipped_deps = result.skipped || []
 	}
 
 	// Filter out packages already installed at the resolved version (handles @latest efficiently)
@@ -270,6 +273,29 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 			}
 		}
 
+		// Warn about skipped dependencies (access-denied, not found, etc.)
+		if (skipped_deps.length > 0) {
+			const access_denied = skipped_deps.filter(s => s.reason === 'access_denied')
+			const not_found = skipped_deps.filter(s => s.reason === 'not_found')
+			const other = skipped_deps.filter(s => s.reason !== 'access_denied' && s.reason !== 'not_found')
+			if (access_denied.length > 0) {
+				print_warn(`${access_denied.length} dependenc${access_denied.length === 1 ? 'y' : 'ies'} skipped (private, requires login):`)
+				for (const s of access_denied) {
+					print_warn(`  ${s.skill} (required by ${s.required_by})`)
+				}
+				print_info(`Log in to install: happyskills login`)
+			}
+			if (not_found.length > 0) {
+				print_warn(`${not_found.length} dependenc${not_found.length === 1 ? 'y' : 'ies'} skipped (not found in registry):`)
+				for (const s of not_found) {
+					print_warn(`  ${s.skill} (required by ${s.required_by})`)
+				}
+			}
+			for (const s of other) {
+				print_warn(`Skipped ${s.skill}: ${s.message}`)
+			}
+		}
+
 		const installed_set = new Set(packages_to_install.map(p => p.skill))
 		const installed = packages_to_install.map(p => ({ skill: p.skill, version: p.version }))
 		const skipped = packages.filter(p => !installed_set.has(p.skill)).map(p => ({ skill: p.skill, version: p.version, reason: 'already installed' }))
@@ -277,7 +303,7 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 		const forced = forced_pkgs.map(p => ({ skill: p.skill, version: p.version }))
 
 		const linked_agents = agents.map(a => a.id)
-		return { skill, version: packages[0]?.version, no_op: false, installed, skipped, warnings, forced, packages: packages_to_install.length, linked_agents }
+		return { skill, version: packages[0]?.version, no_op: false, installed, skipped, skipped_deps, warnings, forced, packages: packages_to_install.length, linked_agents }
 	} catch (err) {
 		await remove_dir(temp_dir)
 		throw err

package/src/engine/resolver.js

@@ -12,7 +12,7 @@ const resolve = (skill, version, installed = {}) => catch_errors('Dependency res
 		throw new Error(`Dependency conflicts detected:\n${conflict_msg}\n\nUse --force to install anyway (takes highest version).`)
 	}
 
-	return result.packages || []
+	return { packages: result.packages || [], skipped: result.skipped || [] }
 })
 
 const resolve_with_force = (skill, version, installed = {}) => catch_errors('Forced resolution failed', async () => {
@@ -30,7 +30,7 @@ const resolve_with_force = (skill, version, installed = {}) => catch_errors('For
 		}
 	}
 
-	return packages
+	return { packages, skipped: result.skipped || [] }
 })
 
 module.exports = { resolve, resolve_with_force }

package/src/utils/errors.js

@@ -49,15 +49,32 @@ const is_usage_error = (err) => {
 	return false
 }
 
+const extract_root_cause = (err) => {
+	if (!Array.isArray(err)) return err?.message || 'An unexpected error occurred'
+	// Walk the error array to find the deepest, most specific message.
+	// catch_errors wraps errors outermost-first: [outermost, ..., root_cause].
+	// We prefer the last error (root cause) for the user-facing message,
+	// but fall back to the first CliError if one exists.
+	const messages = err.map(x => x?.message).filter(Boolean)
+	if (messages.length === 0) return 'An unexpected error occurred'
+	// The last message is typically the root cause (deepest in the chain)
+	return messages[messages.length - 1]
+}
+
+const format_error_chain = (err) => {
+	if (!Array.isArray(err)) return [err?.stack || err?.message || String(err)]
+	return err.map(x => x?.stack || x?.message || String(x)).filter(Boolean)
+}
+
 const get_error_info = (err) => {
 	let target = err
 	if (Array.isArray(err)) {
-		target = err.find(e => e instanceof CliError) || err[0]
+		target = err.find(e => e instanceof CliError) || err[err.length - 1] || err[0]
 	}
 
 	let code = 'ERROR'
 	let exit_code = EXIT_CODES.ERROR
-	const message = target?.message || 'An unexpected error occurred'
+	const message = extract_root_cause(err)
 
 	if (target instanceof UsageError) {
 		code = 'USAGE_ERROR'; exit_code = EXIT_CODES.USAGE
@@ -80,7 +97,10 @@ const exit_with_error = (err) => {
 
 	if (is_json_mode()) {
 		const { code, message, exit_code } = get_error_info(err)
-		console.log(JSON.stringify({ error: { code, message, exit_code } }, null, 2))
+		const chain = format_error_chain(err)
+		const json_err = { code, message, exit_code }
+		if (chain.length > 1) json_err.details = chain
+		console.log(JSON.stringify({ error: json_err }, null, 2))
 		process.exit(exit_code)
 		return
 	}
@@ -89,33 +109,11 @@ const exit_with_error = (err) => {
 	const { write_error_log } = require('./logger')
 
 	const log_path = is_usage_error(err) ? null : write_error_log(err)
+	const { message, exit_code } = get_error_info(err)
 
-	if (err instanceof CliError) {
-		print_error(err.message)
-		print_log_hint(log_path)
-		process.exit(err.exit_code)
-		return
-	}
-
-	if (Array.isArray(err)) {
-		for (const e of err) {
-			if (e instanceof CliError) {
-				print_error(e.message)
-				print_log_hint(log_path)
-				process.exit(e.exit_code)
-				return
-			}
-		}
-		print_error(err[0]?.message || 'An unexpected error occurred')
-		print_log_hint(log_path)
-		process.exit(EXIT_CODES.ERROR)
-		return
-	}
-
-	const message = err.message || 'An unexpected error occurred'
 	print_error(message)
 	print_log_hint(log_path)
-	process.exit(EXIT_CODES.ERROR)
+	process.exit(exit_code)
 }
 
 module.exports = { CliError, UsageError, AuthError, NetworkError, ApiError, exit_with_error }

package/src/validation/dependency_rules.js

@@ -0,0 +1,309 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { SKILL_JSON } = require('../constants')
+
+const RESULT_FILE = SKILL_JSON
+
+const result = (field, rule, severity, message, value) => ({
+	file: RESULT_FILE, field, rule, severity, message, ...(value !== undefined ? { value } : {})
+})
+
+// ---------------------------------------------------------------------------
+// Local rules (no API needed)
+// ---------------------------------------------------------------------------
+
+const check_self_reference = (manifest) => {
+	const results = []
+	const deps = manifest.dependencies || {}
+	const dep_names = Object.keys(deps)
+
+	if (dep_names.length === 0) {
+		results.push(result('dependencies', 'dep-self-reference', 'pass', 'No dependencies declared'))
+		return results
+	}
+
+	for (const dep of dep_names) {
+		const dep_short = dep.includes('/') ? dep.split('/')[1] : dep
+		if (dep_short === manifest.name || dep === manifest.name) {
+			results.push(result('dependencies', 'dep-self-reference', 'error',
+				`Skill depends on itself: "${dep}". Remove this self-reference from dependencies.`, dep))
+		}
+	}
+
+	if (!results.some(r => r.rule === 'dep-self-reference' && r.severity === 'error')) {
+		results.push(result('dependencies', 'dep-self-reference', 'pass', 'No self-references in dependencies'))
+	}
+
+	return results
+}
+
+// ---------------------------------------------------------------------------
+// Registry rules (require API access)
+// ---------------------------------------------------------------------------
+
+const check_deps_exist = async (manifest, repos_api) => {
+	const results = []
+	const deps = manifest.dependencies || {}
+	const dep_names = Object.keys(deps)
+
+	if (dep_names.length === 0) return results
+
+	const checks = await Promise.all(dep_names.map(async (dep) => {
+		const parts = dep.split('/')
+		if (parts.length !== 2) return { dep, error: `Invalid dependency format: "${dep}". Must be owner/name.` }
+		const [owner, name] = parts
+		const [err] = await repos_api.get_repo(owner, name, { auth: true })
+		return { dep, error: err ? `Dependency "${dep}" not found in the registry.` : null }
+	}))
+
+	for (const { dep, error } of checks) {
+		if (error) {
+			results.push(result('dependencies', 'dep-exists', 'error', error, dep))
+		} else {
+			results.push(result('dependencies', 'dep-exists', 'pass', `Dependency "${dep}" exists`, dep))
+		}
+	}
+
+	return results
+}
+
+const check_visibility_direct = async (manifest, visibility, repos_api) => {
+	const results = []
+	const deps = manifest.dependencies || {}
+	const dep_names = Object.keys(deps)
+
+	if (dep_names.length === 0 || visibility !== 'public') return results
+
+	const checks = await Promise.all(dep_names.map(async (dep) => {
+		const parts = dep.split('/')
+		if (parts.length !== 2) return { dep, visibility: null, error: true }
+		const [owner, name] = parts
+		const [err, repo] = await repos_api.get_repo(owner, name, { auth: true })
+		if (err) return { dep, visibility: null, error: true }
+		return { dep, visibility: repo.visibility, error: false }
+	}))
+
+	for (const check of checks) {
+		if (check.error) continue // already reported by dep-exists
+
+		if (check.visibility === 'private') {
+			results.push(result('dependencies', 'dep-visibility-direct', 'error',
+				`Visibility mismatch: this skill is public but depends on "${check.dep}" which is private. ` +
+				`Unauthenticated users will not be able to install this skill. ` +
+				`To fix: make "${check.dep}" public, or remove it from dependencies.`,
+				check.dep))
+		} else if (check.visibility === 'workspace') {
+			results.push(result('dependencies', 'dep-visibility-workspace', 'warning',
+				`Visibility concern: this skill is public but depends on "${check.dep}" which is workspace-scoped. ` +
+				`Only workspace members will be able to install this skill. ` +
+				`To fix: make "${check.dep}" public for full availability.`,
+				check.dep))
+		} else {
+			results.push(result('dependencies', 'dep-visibility-direct', 'pass',
+				`Dependency "${check.dep}" is public`, check.dep))
+		}
+	}
+
+	return results
+}
+
+const check_visibility_transitive = async (manifest, visibility, repos_api) => {
+	const results = []
+	const deps = manifest.dependencies || {}
+
+	if (Object.keys(deps).length === 0 || visibility !== 'public') return results
+
+	// Use resolve-dependencies to get the full transitive tree
+	const skill_name = manifest._full_name
+	if (!skill_name) return results // can't check without full name
+
+	const [err, data] = await repos_api.resolve_dependencies(skill_name, manifest.version || 'latest', {})
+	if (err) {
+		results.push(result('dependencies', 'dep-visibility-transitive', 'warning',
+			'Could not resolve full dependency tree to check transitive visibility. ' +
+			'Run this check again when connected to the registry.'))
+		return results
+	}
+
+	const packages = data.packages || []
+	const skipped = data.skipped || []
+
+	// Check transitive packages returned by the server for non-public visibility
+	const direct_deps = new Set(Object.keys(deps))
+	for (const pkg of packages) {
+		if (pkg.skill === skill_name) continue // skip self
+		if (direct_deps.has(pkg.skill)) continue // already checked by dep-visibility-direct
+		if (pkg.visibility && pkg.visibility !== 'public') {
+			const chain = _build_chain_from_packages(skill_name, pkg.skill, packages)
+			const chain_str = chain.join(' → ')
+			results.push(result('dependencies', 'dep-visibility-transitive', 'error',
+				`Visibility mismatch in dependency tree: "${pkg.skill}" is ${pkg.visibility}. ` +
+				`Chain: ${chain_str}. ` +
+				`Unauthenticated users will not be able to install this skill. ` +
+				`To fix: make "${pkg.skill}" public, or remove it from "${chain[chain.length - 2]}"'s dependencies.`,
+				pkg.skill))
+		}
+	}
+
+	// Skipped deps (access denied, not found) are also visibility issues
+	for (const s of skipped) {
+		if (s.reason === 'access_denied') {
+			results.push(result('dependencies', 'dep-visibility-transitive', 'error',
+				`Visibility mismatch in dependency tree: "${s.skill}" is ${s.visibility || 'private'} ` +
+				`(required by ${s.required_by}). ` +
+				`Unauthenticated users will not be able to install this skill. ` +
+				`To fix: make "${s.skill}" public, or remove it from "${s.required_by}"'s dependencies.`,
+				s.skill))
+		} else if (s.reason === 'not_found') {
+			results.push(result('dependencies', 'dep-visibility-transitive', 'error',
+				`Missing dependency in tree: "${s.skill}" not found in registry ` +
+				`(required by ${s.required_by}).`,
+				s.skill))
+		}
+	}
+
+	if (!results.some(r => r.rule === 'dep-visibility-transitive' && r.severity !== 'pass')) {
+		results.push(result('dependencies', 'dep-visibility-transitive', 'pass',
+			'All transitive dependencies are public'))
+	}
+
+	return results
+}
+
+const check_circular = async (manifest, repos_api) => {
+	const results = []
+	const deps = manifest.dependencies || {}
+
+	if (Object.keys(deps).length === 0) return results
+
+	const skill_name = manifest._full_name
+	if (!skill_name) return results
+
+	const [err, data] = await repos_api.resolve_dependencies(skill_name, manifest.version || 'latest', {})
+	if (err) return results
+
+	const packages = data.packages || []
+
+	// Build adjacency map from declared dependencies
+	const adj = {}
+	for (const pkg of packages) {
+		adj[pkg.skill] = Object.keys(pkg.dependencies || {})
+	}
+
+	// DFS cycle detection
+	const WHITE = 0, GRAY = 1, BLACK = 2
+	const color = {}
+	const parent = {}
+	const cycles = []
+
+	const dfs = (node, path_so_far) => {
+		color[node] = GRAY
+		for (const neighbor of (adj[node] || [])) {
+			if (color[neighbor] === GRAY) {
+				// Found a cycle — extract it
+				const cycle_start = path_so_far.indexOf(neighbor)
+				if (cycle_start >= 0) {
+					cycles.push([...path_so_far.slice(cycle_start), neighbor])
+				} else {
+					cycles.push([node, neighbor])
+				}
+			} else if ((color[neighbor] || WHITE) === WHITE) {
+				dfs(neighbor, [...path_so_far, neighbor])
+			}
+		}
+		color[node] = BLACK
+	}
+
+	for (const node of Object.keys(adj)) {
+		if ((color[node] || WHITE) === WHITE) {
+			dfs(node, [node])
+		}
+	}
+
+	if (cycles.length > 0) {
+		for (const cycle of cycles) {
+			results.push(result('dependencies', 'dep-circular', 'error',
+				`Circular dependency detected: ${cycle.join(' → ')}. ` +
+				`Remove one direction of the dependency to break the cycle.`,
+				cycle))
+		}
+	} else {
+		results.push(result('dependencies', 'dep-circular', 'pass',
+			'No circular dependencies detected'))
+	}
+
+	return results
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const _build_chain_from_packages = (root, target, packages) => {
+	const adj = {}
+	for (const pkg of packages) {
+		adj[pkg.skill] = Object.keys(pkg.dependencies || {})
+	}
+
+	const queue = [[root]]
+	const seen = new Set([root])
+	while (queue.length) {
+		const path = queue.shift()
+		const node = path[path.length - 1]
+		if (node === target) return path
+		for (const child of (adj[node] || [])) {
+			if (!seen.has(child)) {
+				seen.add(child)
+				queue.push([...path, child])
+			}
+		}
+	}
+	return [root, target]
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate dependency rules.
+ *
+ * @param {string} dir - Skill directory path
+ * @param {object} manifest - Parsed skill.json
+ * @param {object} [options]
+ * @param {boolean}     [options.registry]  - Whether to run registry checks (default: false)
+ * @param {string}      [options.visibility] - Skill's target visibility ('public'|'private'|'workspace')
+ * @param {string}      [options.full_name]  - Full "owner/name" for registry lookups
+ * @param {object}      [options.repos_api]  - API module override (for testing)
+ */
+const validate_dependencies = (dir, manifest, options = {}) =>
+	catch_errors('Dependency validation failed', async () => {
+		const { registry = false, visibility = 'private', full_name, repos_api: api_override } = options
+		const all_results = []
+
+		// Always run local checks
+		all_results.push(...check_self_reference(manifest))
+
+		if (!registry) {
+			return all_results
+		}
+
+		// Registry checks require the API
+		const repos_api = api_override || require('../api/repos')
+		const enriched = { ...manifest, _full_name: full_name }
+
+		const [exist_results, vis_direct_results, vis_trans_results, circ_results] = await Promise.all([
+			check_deps_exist(enriched, repos_api),
+			check_visibility_direct(enriched, visibility, repos_api),
+			check_visibility_transitive(enriched, visibility, repos_api),
+			check_circular(enriched, repos_api)
+		])
+
+		all_results.push(...exist_results)
+		all_results.push(...vis_direct_results)
+		all_results.push(...vis_trans_results)
+		all_results.push(...circ_results)
+
+		return all_results
+	})
+
+module.exports = { validate_dependencies }

package/src/validation/dependency_rules.test.js

@@ -0,0 +1,231 @@
+'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_dependencies } = require('./dependency_rules')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-validate-deps-'))
+
+let tmp
+beforeEach(() => { tmp = make_tmp() })
+afterEach(() => { fs.rmSync(tmp, { recursive: true, force: true }) })
+
+// ---------------------------------------------------------------------------
+// Local rules (no registry)
+// ---------------------------------------------------------------------------
+
+describe('dep-self-reference', () => {
+	it('passes when no dependencies', async () => {
+		const manifest = { name: 'my-skill', version: '1.0.0' }
+		const [err, results] = await validate_dependencies(tmp, manifest)
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'dep-self-reference')
+		assert.strictEqual(check.severity, 'pass')
+	})
+
+	it('passes when dependencies do not include self', async () => {
+		const manifest = { name: 'my-skill', version: '1.0.0', dependencies: { 'acme/other': '*' } }
+		const [err, results] = await validate_dependencies(tmp, manifest)
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'dep-self-reference')
+		assert.strictEqual(check.severity, 'pass')
+	})
+
+	it('errors when skill depends on itself (short name match)', async () => {
+		const manifest = { name: 'my-skill', version: '1.0.0', dependencies: { 'acme/my-skill': '*' } }
+		const [err, results] = await validate_dependencies(tmp, manifest)
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'dep-self-reference' && r.severity === 'error')
+		assert.ok(check, 'should find self-reference error')
+		assert.ok(check.message.includes('depends on itself'))
+	})
+})
+
+// ---------------------------------------------------------------------------
+// Registry rules (mocked API)
+// ---------------------------------------------------------------------------
+
+const make_mock_api = (repos = {}, resolve_result = null) => ({
+	get_repo: async (owner, name, opts) => {
+		const key = `${owner}/${name}`
+		if (repos[key]) return [null, repos[key]]
+		return [new Error(`Not found: ${key}`), null]
+	},
+	resolve_dependencies: async (skill, version, installed) => {
+		if (resolve_result) return [null, resolve_result]
+		return [new Error('Not implemented'), null]
+	}
+})
+
+describe('dep-exists (registry)', () => {
+	it('passes when all deps exist', async () => {
+		const manifest = { name: 'my-skill', version: '1.0.0', dependencies: { 'acme/auth': '*' } }
+		const api = make_mock_api({ 'acme/auth': { visibility: 'public' } })
+		const [err, results] = await validate_dependencies(tmp, manifest, { registry: true, repos_api: api })
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'dep-exists' && r.value === 'acme/auth')
+		assert.strictEqual(check.severity, 'pass')
+	})
+
+	it('errors when dep is missing', async () => {
+		const manifest = { name: 'my-skill', version: '1.0.0', dependencies: { 'acme/missing': '*' } }
+		const api = make_mock_api({})
+		const [err, results] = await validate_dependencies(tmp, manifest, { registry: true, repos_api: api })
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'dep-exists' && r.value === 'acme/missing')
+		assert.strictEqual(check.severity, 'error')
+		assert.ok(check.message.includes('not found'))
+	})
+})
+
+describe('dep-visibility-direct (registry)', () => {
+	it('errors when public skill depends on private dep', async () => {
+		const manifest = { name: 'my-skill', version: '1.0.0', dependencies: { 'acme/secret': '*' } }
+		const api = make_mock_api({ 'acme/secret': { visibility: 'private' } })
+		const [err, results] = await validate_dependencies(tmp, manifest, { registry: true, visibility: 'public', repos_api: api })
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'dep-visibility-direct' && r.severity === 'error')
+		assert.ok(check, 'should find visibility error')
+		assert.ok(check.message.includes('Visibility mismatch'))
+		assert.ok(check.message.includes('private'))
+	})
+
+	it('warns when public skill depends on workspace-scoped dep', async () => {
+		const manifest = { name: 'my-skill', version: '1.0.0', dependencies: { 'acme/internal': '*' } }
+		const api = make_mock_api({ 'acme/internal': { visibility: 'workspace' } })
+		const [err, results] = await validate_dependencies(tmp, manifest, { registry: true, visibility: 'public', repos_api: api })
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'dep-visibility-workspace')
+		assert.strictEqual(check.severity, 'warning')
+	})
+
+	it('passes when public skill has all public deps', async () => {
+		const manifest = { name: 'my-skill', version: '1.0.0', dependencies: { 'acme/auth': '*' } }
+		const api = make_mock_api({ 'acme/auth': { visibility: 'public' } })
+		const [err, results] = await validate_dependencies(tmp, manifest, { registry: true, visibility: 'public', repos_api: api })
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'dep-visibility-direct')
+		assert.strictEqual(check.severity, 'pass')
+	})
+
+	it('skips visibility check for private skills', async () => {
+		const manifest = { name: 'my-skill', version: '1.0.0', dependencies: { 'acme/secret': '*' } }
+		const api = make_mock_api({ 'acme/secret': { visibility: 'private' } })
+		const [err, results] = await validate_dependencies(tmp, manifest, { registry: true, visibility: 'private', repos_api: api })
+		assert.ifError(err)
+		const vis_results = results.filter(r => r.rule === 'dep-visibility-direct' || r.rule === 'dep-visibility-workspace')
+		assert.strictEqual(vis_results.length, 0)
+	})
+})
+
+describe('dep-circular (registry)', () => {
+	it('detects a simple cycle A → B → A', async () => {
+		const manifest = { name: 'my-skill', version: '1.0.0', dependencies: { 'acme/b': '*' } }
+		const resolve_result = {
+			packages: [
+				{ skill: 'acme/a', version: '1.0.0', dependencies: { 'acme/b': '*' } },
+				{ skill: 'acme/b', version: '1.0.0', dependencies: { 'acme/a': '*' } }
+			],
+			skipped: []
+		}
+		const api = make_mock_api({ 'acme/b': { visibility: 'public' } }, resolve_result)
+		const [err, results] = await validate_dependencies(tmp, manifest, {
+			registry: true, full_name: 'acme/a', repos_api: api
+		})
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'dep-circular' && r.severity === 'error')
+		assert.ok(check, 'should detect cycle')
+		assert.ok(check.message.includes('Circular dependency'))
+	})
+
+	it('passes when no cycles', async () => {
+		const manifest = { name: 'my-skill', version: '1.0.0', dependencies: { 'acme/b': '*' } }
+		const resolve_result = {
+			packages: [
+				{ skill: 'acme/a', version: '1.0.0', dependencies: { 'acme/b': '*' } },
+				{ skill: 'acme/b', version: '1.0.0', dependencies: {} }
+			],
+			skipped: []
+		}
+		const api = make_mock_api({ 'acme/b': { visibility: 'public' } }, resolve_result)
+		const [err, results] = await validate_dependencies(tmp, manifest, {
+			registry: true, full_name: 'acme/a', repos_api: api
+		})
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'dep-circular')
+		assert.strictEqual(check.severity, 'pass')
+	})
+})
+
+describe('dep-visibility-transitive (registry)', () => {
+	it('errors when transitive dep is private', async () => {
+		const manifest = { name: 'my-skill', version: '1.0.0', dependencies: { 'acme/b': '*' } }
+		const resolve_result = {
+			packages: [
+				{ skill: 'acme/a', version: '1.0.0', visibility: 'public', dependencies: { 'acme/b': '*' } },
+				{ skill: 'acme/b', version: '1.0.0', visibility: 'public', dependencies: { 'acme/c': '*' } },
+				{ skill: 'acme/c', version: '1.0.0', visibility: 'private', dependencies: {} }
+			],
+			skipped: []
+		}
+		const api = make_mock_api(
+			{ 'acme/b': { visibility: 'public' } },
+			resolve_result
+		)
+		const [err, results] = await validate_dependencies(tmp, manifest, {
+			registry: true, visibility: 'public', full_name: 'acme/a', repos_api: api
+		})
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'dep-visibility-transitive' && r.severity === 'error')
+		assert.ok(check, 'should find transitive visibility error')
+		assert.ok(check.message.includes('acme/c'))
+		assert.ok(check.message.includes('private'))
+	})
+
+	it('reports skipped (access-denied) deps as visibility errors', async () => {
+		const manifest = { name: 'my-skill', version: '1.0.0', dependencies: { 'acme/b': '*' } }
+		const resolve_result = {
+			packages: [
+				{ skill: 'acme/a', version: '1.0.0', visibility: 'public', dependencies: { 'acme/b': '*' } },
+				{ skill: 'acme/b', version: '1.0.0', visibility: 'public', dependencies: { 'acme/secret': '*' } }
+			],
+			skipped: [
+				{ skill: 'acme/secret', reason: 'access_denied', message: 'Access denied', required_by: 'acme/b', visibility: 'private' }
+			]
+		}
+		const api = make_mock_api(
+			{ 'acme/b': { visibility: 'public' } },
+			resolve_result
+		)
+		const [err, results] = await validate_dependencies(tmp, manifest, {
+			registry: true, visibility: 'public', full_name: 'acme/a', repos_api: api
+		})
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'dep-visibility-transitive' && r.severity === 'error' && r.value === 'acme/secret')
+		assert.ok(check, 'should report skipped dep as visibility error')
+	})
+
+	it('passes when all transitive deps are public', async () => {
+		const manifest = { name: 'my-skill', version: '1.0.0', dependencies: { 'acme/b': '*' } }
+		const resolve_result = {
+			packages: [
+				{ skill: 'acme/a', version: '1.0.0', visibility: 'public', dependencies: { 'acme/b': '*' } },
+				{ skill: 'acme/b', version: '1.0.0', visibility: 'public', dependencies: {} }
+			],
+			skipped: []
+		}
+		const api = make_mock_api(
+			{ 'acme/b': { visibility: 'public' } },
+			resolve_result
+		)
+		const [err, results] = await validate_dependencies(tmp, manifest, {
+			registry: true, visibility: 'public', full_name: 'acme/a', repos_api: api
+		})
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'dep-visibility-transitive')
+		assert.strictEqual(check.severity, 'pass')
+	})
+})