happyskills 1.16.1 → 1.17.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.17.0] - 2026-07-05
+
+### Added
+
+- Add consumer-side per-skill configuration via a project-root `skills-config.json` (a committed sibling of `skills-lock.json`, keyed by `owner/name`). A skill author declares optional `config` (typed, defaulted non-secret tunables) and `env` (an environment-variable contract, with `required: true` as the activation gate and `secret: true` for credentials) blocks in `skill.json`; the consumer's overrides and an `envFile` pointer live in `skills-config.json`. Secret **values** are never written to any committed file.
+- Add `happyskills skills-config get <owner/name>` — a deterministic resolver that deep-merges the project `skills-config.json`, the global `~/.agents/skills-config.json`, and the skill's author defaults (project wins) and returns the effective non-secret config, the `envFile` path (relative to the caller's cwd), and required-secret **names** plus a `secretsPresent` boolean — never a secret value. Resolves from a subdirectory by walking up to the nearest `skills-config.json`/`skills-lock.json` (stopping at a `.git` boundary); reads are CLI-preferred, plain-file-fallback.
+- Prompt for a configurable skill's declared `config`/`env` on `install` and `update` (interactive terminal only — `--json`, `--yes`, non-TTY, and lockfile/manifest reinstalls scaffold silently). Secrets are routed to a git-ignored `./secrets/<skill>.env` with a committed `.env.example` (names only) and a `.gitignore` entry; non-secret overrides are written to `skills-config.json`. `update` re-prompts only newly-required fields and leaves existing values untouched; any required-but-unset field is surfaced as a warning.
+- Validate the `skill.json` `config`/`env` schema in `happyskills validate` (unknown types, non-boolean `required`/`secret` flags, a secret carrying a committed default, an uncompilable `validate` regex, and case-only env-name collisions).
+
+## [1.16.3] - 2026-07-03
+
+### Fixed
+
+- `happyskills install` no longer reports a skill as "already installed" when its **declared dependency closure is not materialized on disk**. The pre-resolve skip check previously inspected only the requested skill's own directory + integrity, so a lock entry carrying a populated `dependencies` map whose skills were never installed (e.g. a kit entry written by `publish`, which records `manifest.dependencies` but installs nothing) would short-circuit every `install` — the missing transitive dependencies were never backfilled and the lock stayed permanently out of sync with `.agents/skills/`. The skip check now walks the locked dependency graph (cycle-safe, transitive) via `dependency_closure_satisfied` and only skips when every reachable dependency is both locked **and** present on disk; otherwise it declines the skip and re-resolves so the missing skills are installed. This makes `install` self-healing: re-running it repairs a partial lock without needing `--fresh`.
+
+## [1.16.2] - 2026-07-03
+
+### Changed
+
+- `happyskills init` and `happyskills fork` no longer scaffold a `keywords` field in the generated `skill.json`. `keywords` is a deprecated, platform-ignored manifest field — discovery labels are derived server-side from the skill's `description` + `SKILL.md` (the platform-owned taxonomy), so an author-supplied keyword list has no effect on search, ranking, or filtering. The scaffold previously emitted an empty `keywords: []`, which baited enrichment agents into populating a no-op field; omitting it removes the bait. The field remains accepted on publish for backward compatibility.
+- `happyskills update --all` now checks **every installed skill**, not just top-level (`__root__`) ones. Previously a bundled dependency — e.g. a HappySkills family satellite (`happyskills-design/publish/sync/search/help`) installed transitively under `happyskills` — was skipped by `--all` and only refreshed when its parent happened to be reinstalled, so a satellite that advanced on the registry while its parent didn't stayed stale even though `check` and the daily update nudge flagged it. `update --all` now mirrors `check` and the nudge and refreshes those drifted transitive skills directly. `update <owner/name>` and the `--all-scopes` per-scope behavior are unchanged.
+
 ## [1.16.1] - 2026-07-02
 
 ### Fixed

package/package.json

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

package/src/commands/fork.js

@@ -83,12 +83,14 @@ const run = (args) => catch_errors('Fork failed', async () => {
 	const [, original_manifest] = await read_manifest(dest)
 	const is_kit = (original_manifest?.type) === SKILL_TYPES.KIT
 	const forked_name = is_kit && !name.startsWith(KIT_PREFIX) ? `${KIT_PREFIX}${name}` : name
+	// No `keywords` field — it is a deprecated, platform-ignored skill.json field
+	// (docs/skill-format.md § 4.3). A fork starts clean; discovery labels are derived
+	// server-side from description + SKILL.md, not from an author-supplied keyword list.
 	const forked_manifest = {
 		name: forked_name,
 		version: '0.1.0',
 		type: is_kit ? SKILL_TYPES.KIT : SKILL_TYPES.SKILL,
 		description: '',
-		keywords: [],
 		forked_from: {
 			repo: skill,
 			version: latest_version,

package/src/commands/init.js

@@ -58,11 +58,15 @@ Add the skills this kit bundles and why they work well together.
 Describe the project type or workflow this kit is designed for.
 `
 
+// Note: no `keywords` field. It is a deprecated skill.json field (docs/skill-format.md
+// § 4.3) — the platform-owned taxonomy derives discovery labels server-side from the
+// skill's description + SKILL.md, so an author-supplied keyword list is ignored by
+// search, ranking, and filtering. Emitting an empty `keywords: []` here only baited the
+// enrichment agent into populating a field with no effect; omitting it removes the bait.
 const create_manifest = (name, is_kit = false) => ({
 	name,
 	version: '0.1.0',
 	description: '',
-	keywords: [],
 	type: is_kit ? SKILL_TYPES.KIT : SKILL_TYPES.SKILL,
 	dependencies: {}
 })
@@ -181,4 +185,4 @@ const schema = {
 	],
 }
 
-module.exports = { run, schema }
+module.exports = { run, schema, create_manifest }

package/src/commands/init.test.js

@@ -0,0 +1,29 @@
+'use strict'
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+
+const { create_manifest } = require('./init')
+
+// `keywords` is a deprecated skill.json field — not read by search, ranking, or
+// the platform-owned taxonomy (docs/skill-format.md § 4.3, docs/taxonomy.md § 1).
+// The scaffold must NOT emit an empty `keywords` key: a present-but-empty field is
+// bait that leads the enrichment agent to populate a field the platform ignores.
+describe('create_manifest', () => {
+	it('does not emit a keywords key for a skill scaffold', () => {
+		const manifest = create_manifest('my-skill')
+		assert.ok(!('keywords' in manifest), 'scaffold must not include the deprecated keywords field')
+	})
+
+	it('does not emit a keywords key for a kit scaffold', () => {
+		const manifest = create_manifest('_kit-my-kit', true)
+		assert.ok(!('keywords' in manifest), 'kit scaffold must not include the deprecated keywords field')
+	})
+
+	it('still emits the fields the enrichment workflow fills', () => {
+		const manifest = create_manifest('my-skill')
+		assert.strictEqual(manifest.name, 'my-skill')
+		assert.strictEqual(manifest.version, '0.1.0')
+		assert.strictEqual(manifest.description, '')
+		assert.deepStrictEqual(manifest.dependencies, {})
+	})
+})

package/src/commands/install.js

@@ -200,12 +200,18 @@ const run = (args) => catch_errors('Install failed', async () => {
 		}
 	}
 
+	// Prompt for skill config only on a direct, interactive install — never on --json,
+	// --yes, or a non-TTY invocation (spec 260704-01 §4.3.1 rule 4). The no-arg / lock /
+	// manifest reinstall paths use base_options (which omits prompt_config) so they never
+	// prompt (spec §6 #8).
+	const prompt_config = !!process.stdin.isTTY && !base_options.yes && !args.flags.json
+
 	const results = []
 	const failures = []
 	for (const { skill, version: inline_version } of parsed) {
 		const version = flag_version || inline_version
 		emit_analytics('install.started', { cli_version: CLI_VERSION })
-		const [errors, result] = await install(skill, { ...base_options, version })
+		const [errors, result] = await install(skill, { ...base_options, version, prompt_config })
 		if (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'

package/src/commands/skills-config.js

@@ -0,0 +1,140 @@
+'use strict'
+// happyskills skills-config get <owner/name> — spec 260704-01 Tier 3 §4.4.
+//
+// The deterministic resolver for consumer-side skill configuration. Reads the
+// project skills-config.json ⊕ global ~/.agents/skills-config.json ⊕ the installed
+// skill.json author defaults, deep-merges them (project winning), and returns the
+// resolved NON-secret config, the resolved envFile path, the names of required
+// secrets, and a present/absent boolean.
+//
+// It NEVER reads-and-returns a secret VALUE (§0 hard rule) — only names and a
+// boolean. The agent does the merge via this command so it never hand-parses or
+// hallucinates config; a CLI-less context falls back to reading the file directly
+// (see the canonical SKILL.md snippet in happyskills-design).
+
+const path = require('path')
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { EXIT_CODES } = require('../constants')
+const { print_help, print_info, print_table } = require('../ui/output')
+const { emit_envelope } = require('../ui/envelope')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { find_config_root } = require('../config/paths')
+const { resolve_skill_config } = require('../skills_config/resolve')
+
+// Emit envFile as a forward-slash path relative to the caller's cwd — usable directly by the
+// agent wherever it runs, and never an absolute local path (which would leak the home dir).
+const to_cwd_relative = (abs) => {
+	if (!abs) return null
+	const rel = path.relative(process.cwd(), abs).split(path.sep).join('/')
+	return rel.startsWith('.') ? rel : `./${rel}`
+}
+
+const HELP_TEXT = `Usage: happyskills skills-config get <owner/name> [options]
+
+Resolve the effective configuration for an installed skill. Deep-merges the
+project skills-config.json, the global ~/.agents/skills-config.json, and the
+skill's own author defaults (project winning) and reports the required secret
+names plus whether they are set — never the secret values themselves.
+
+Arguments:
+  owner/name        The skill to resolve (e.g. acme/slack-notify)
+
+Options:
+  --json            Output as JSON envelope (default for non-TTY callers)
+
+Examples:
+  happyskills skills-config get acme/slack-notify --json`
+
+const run = (args) => catch_errors('skills-config failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const subcommand = args._[0]
+	const key = args._[1]
+
+	if (subcommand !== 'get') {
+		throw new UsageError(`Unknown skills-config subcommand "${subcommand || ''}". Expected: get <owner/name>.`)
+	}
+	if (!key || !key.includes('/')) {
+		throw new UsageError(`Skill must be in owner/name format (e.g. acme/slack-notify). Got: ${key || '(none)'}`)
+	}
+
+	// Walk up to the nearest project marker so the command works from a subdirectory —
+	// the same root the CLI-less fallback resolves (spec 260704-01 §6 #7).
+	const project_root = find_config_root()
+	const [resolve_err, resolved] = await resolve_skill_config(key, { project_root })
+	if (resolve_err) throw e(`Failed to resolve config for ${key}`, resolve_err)
+
+	const env_file = to_cwd_relative(resolved.envFile)
+
+	const data = {
+		skill: key,
+		config: resolved.config,
+		envFile: env_file,
+		requiredSecrets: resolved.requiredSecrets,
+		secretsPresent: resolved.secretsPresent
+	}
+
+	const warnings = []
+	if (!resolved.manifestFound) {
+		warnings.push(`${key} is not installed — returning consumer overrides without author defaults.`)
+	}
+	if (resolved.requiredSecrets.length && !resolved.secretsPresent) {
+		warnings.push(`Required secret(s) not set: ${resolved.requiredSecrets.join(', ')}${env_file ? ` — set them in ${env_file}` : ''}.`)
+	}
+
+	if (args.flags.json) {
+		emit_envelope({
+			data,
+			next_step: { kind: 'continuation', action: 'present_to_user' },
+			warnings
+		})
+		return
+	}
+
+	print_info(`Resolved config for ${key}:`)
+	const rows = Object.entries(resolved.config).map(([k, v]) => [k, String(v)])
+	if (rows.length) print_table(['key', 'value'], rows)
+	else print_info('  (no config — using author defaults)')
+	if (env_file) print_info(`envFile: ${env_file}`)
+	if (resolved.requiredSecrets.length) {
+		print_info(`required secrets: ${resolved.requiredSecrets.join(', ')} — ${resolved.secretsPresent ? 'all set' : 'NOT all set'}`)
+	}
+	for (const w of warnings) print_info(`⚠ ${w}`)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+const schema = {
+	name:     'skills-config',
+	audience: 'consumer',
+	purpose:  'Resolve the effective configuration for an installed skill (project ⊕ global ⊕ author defaults), reporting required secret names and whether they are set — never secret values.',
+	mutation: false,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'subcommand', required: true, type: 'string', description: 'Currently only "get"' },
+			{ name: 'owner/name', required: true, type: 'string', description: 'The skill to resolve (owner/name)' }
+		],
+		flags: [
+			{ name: 'json', type: 'boolean', default: false, description: 'Output as JSON envelope' }
+		]
+	},
+	output: {
+		data_shape: {
+			skill:           'string',
+			config:          'object',
+			envFile:         'string|null',
+			requiredSecrets: 'string[]',
+			secretsPresent:  'boolean'
+		}
+	},
+	errors: [
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } }
+	],
+	examples: [
+		'happyskills skills-config get acme/slack-notify --json'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/update.js

@@ -25,7 +25,7 @@ Arguments:
   owner/skill       Update a specific skill (optional)
 
 Options:
-  --all             Update all installed root-level skills
+  --all             Update all installed skills (roots and their dependencies)
   --all-scopes      Update BOTH project-local and global skills (in that order),
                     reporting per-scope results. Overrides -g.
   --force           Re-install regardless of version. Also overwrites skills
@@ -66,6 +66,18 @@ const confirm_prompt = (question) => new Promise((resolve) => {
 	})
 })
 
+// Selects which locked skills `update` should consider. With an explicit target, only
+// that skill (if locked). For --all, EVERY installed skill — not just top-level
+// (__root__) ones — so a bundled family satellite installed as a transitive dependency
+// (e.g. happyskills-help under happyskills) is refreshed too. Without this, `update --all`
+// would report staleness (via check/the nudge) it could not resolve. Keeps --all
+// consistent with `check` and the passive drift nudge. A null value is a removed-skill
+// tombstone — skip it. Pure + exported for unit testing.
+const select_update_candidates = (skills, target_skill) =>
+	target_skill
+		? (skills && skills[target_skill] ? [[target_skill, skills[target_skill]]] : [])
+		: Object.entries(skills || {}).filter(([, d]) => d && typeof d === 'object')
+
 /**
  * Run the full update flow for ONE scope (project-local or global) and return
  * `{ scope, data }` — where `data` is exactly the JSON `data` payload that
@@ -89,12 +101,8 @@ const run_scope = (scope_is_global, ctx) => catch_errors('Update scope failed',
 	const skills = get_all_locked_skills(lock_data)
 	const base_dir = skills_dir(scope_is_global, project_root)
 
-	// Determine which skills to consider.
-	// For --all, only root-level skills (transitive deps come along through their parents).
-	// For a specific target, allow any locked skill.
-	const candidates = target_skill
-		? (skills[target_skill] ? [[target_skill, skills[target_skill]]] : [])
-		: Object.entries(skills).filter(([, data]) => data && data.requested_by?.includes('__root__'))
+	// Determine which skills to consider (see select_update_candidates).
+	const candidates = select_update_candidates(skills, target_skill)
 
 	if (candidates.length === 0) {
 		// A missing target is only a hard error in single-scope mode. Across
@@ -110,7 +118,10 @@ const run_scope = (scope_is_global, ctx) => catch_errors('Update scope failed',
 	// ─── --force path: skip the version check, re-install everything ─────────
 	if (force) {
 		print_header()
-		const options = { global: scope_is_global, fresh: true, force: true, agents: agents_flag || undefined, project_root }
+		// Reconcile skills-config.json on update: prompt only for newly-required fields
+		// absent from the existing entry, leaving other values untouched (spec 260704-01 §4.3.2).
+		const config_reconcile = { prompt_config: !!process.stdin.isTTY && !json_mode && !auto_yes, config_only_required: true }
+		const options = { global: scope_is_global, fresh: true, force: true, agents: agents_flag || undefined, project_root, ...config_reconcile }
 		const updated = []
 		for (const [name, data] of candidates) {
 			const before_version = data?.version || null
@@ -281,7 +292,8 @@ const run_scope = (scope_is_global, ctx) => catch_errors('Update scope failed',
 	}
 
 	// Install only the outdated, non-modified skills
-	const options = { global: scope_is_global, fresh: true, agents: agents_flag || undefined, project_root }
+	const config_reconcile = { prompt_config: !!process.stdin.isTTY && !json_mode && !auto_yes, config_only_required: true }
+	const options = { global: scope_is_global, fresh: true, agents: agents_flag || undefined, project_root, ...config_reconcile }
 	const updated = []
 	const update_errors = []
 
@@ -433,4 +445,4 @@ const schema = {
 	]
 }
 
-module.exports = { run, schema }
+module.exports = { run, schema, select_update_candidates }

package/src/commands/update.test.js

@@ -0,0 +1,36 @@
+const { test } = require('node:test')
+const assert = require('node:assert')
+
+const { select_update_candidates } = require('./update')
+
+// A normal-user family install: core is __root__, the bundled satellites are transitive
+// dependencies of core (requested_by: [core]). This is what a plain `happyskills setup`
+// produces — the case where the __root__-only filter used to hide the satellites.
+const FAMILY_LOCK = {
+	'happyskillsai/happyskills':      { version: '2.5.4', requested_by: ['__root__'] },
+	'happyskillsai/happyskills-help': { version: '0.8.2', requested_by: ['happyskillsai/happyskills'] },
+	'happyskillsai/happyskills-sync': { version: '0.6.3', requested_by: ['happyskillsai/happyskills'] },
+}
+
+test('update --all considers transitive family satellites, not just __root__ skills', () => {
+	// Coherence fix: `check` and the passive nudge already watch every installed skill;
+	// `update --all` must too, or it reports staleness it cannot resolve via the obvious verb.
+	const names = select_update_candidates(FAMILY_LOCK, undefined).map(([n]) => n)
+	assert.ok(names.includes('happyskillsai/happyskills-help'),
+		'`update --all` must be able to refresh a bundled satellite installed as a transitive dependency')
+	assert.ok(names.includes('happyskillsai/happyskills'), 'root skills are still included')
+})
+
+test('update <target> selects only that skill (root or transitive), or none if unlocked', () => {
+	assert.deepStrictEqual(
+		select_update_candidates(FAMILY_LOCK, 'happyskillsai/happyskills-help').map(([n]) => n),
+		['happyskillsai/happyskills-help'])
+	assert.deepStrictEqual(select_update_candidates(FAMILY_LOCK, 'acme/not-installed'), [])
+})
+
+test('select_update_candidates skips null (removed-skill) tombstones', () => {
+	const lock = { 'acme/root': { version: '1.0.0', requested_by: ['__root__'] }, 'acme/removed': null }
+	const names = select_update_candidates(lock, undefined).map(([n]) => n)
+	assert.ok(names.includes('acme/root'))
+	assert.ok(!names.includes('acme/removed'))
+})

package/src/config/paths.js

@@ -1,6 +1,7 @@
 const fs = require('fs')
 const path = require('path')
 const os = require('os')
+const { SKILLS_CONFIG_FILE, LOCK_FILE } = require('../constants')
 
 const home_dir = os.homedir()
 
@@ -44,10 +45,34 @@ const lock_root = (is_global, project_root) => {
 
 const lock_file_path = (project_root = process.cwd()) => path.join(project_root, 'skills-lock.json')
 
+// Consumer-side per-skill config (spec 260704-01). Sibling of skills-lock.json at the
+// project root; the global copy is co-located with the global lock root (~/.agents),
+// derived from lock_root so it tracks wherever the lock actually lives.
+const skills_config_file_path = (project_root = process.cwd()) => path.join(project_root, SKILLS_CONFIG_FILE)
+
+const global_skills_config_file_path = () => path.join(lock_root(true), SKILLS_CONFIG_FILE)
+
 const skill_install_dir = (base_skills_dir, name) => assert_within(base_skills_dir, path.join(base_skills_dir, name))
 
 const find_project_root = (start_dir = process.cwd()) => path.resolve(start_dir)
 
+// Config read-path root discovery (spec 260704-01 §6 #7). Unlike find_project_root (cwd-only,
+// used by install/publish/etc.), the config RESOLVER walks upward for the nearest project marker
+// — skills-config.json or skills-lock.json — stopping at a .git boundary, so `skills-config get`
+// finds the same root a CLI-less agent would via the canonical SKILL.md fallback. Falls back to
+// the start dir when no marker is found (preserving today's behavior for a bare directory).
+const find_config_root = (start_dir = process.cwd()) => {
+	let dir = path.resolve(start_dir)
+	// eslint-disable-next-line no-constant-condition
+	while (true) {
+		if (fs.existsSync(path.join(dir, SKILLS_CONFIG_FILE)) || fs.existsSync(path.join(dir, LOCK_FILE))) return dir
+		if (fs.existsSync(path.join(dir, '.git'))) return dir
+		const parent = path.dirname(dir)
+		if (parent === dir) return path.resolve(start_dir)
+		dir = parent
+	}
+}
+
 const agent_skills_dir = (agent, global = false, project_root) => {
 	if (global) return path.join(home_dir, agent.global_skills_dir)
 	return path.join(project_root || process.cwd(), agent.skills_dir)
@@ -70,8 +95,11 @@ module.exports = {
 	install_lock_path,
 	lock_root,
 	lock_file_path,
+	skills_config_file_path,
+	global_skills_config_file_path,
 	skill_install_dir,
 	find_project_root,
+	find_config_root,
 	agent_skills_dir,
 	agent_skill_install_dir,
 	assert_within

package/src/config/paths.test.js

@@ -144,6 +144,42 @@ describe('paths', () => {
 		})
 	})
 
+	// spec 260704-01 §6 #7 — the config read path walks up to the nearest
+	// skills-config.json / skills-lock.json, stopping at a .git boundary, so
+	// `skills-config get` resolves the same root the CLI-less fallback would.
+	describe('find_config_root (walk-up)', () => {
+		let root
+		beforeEach(() => { root = fs.mkdtempSync(path.join(os.tmpdir(), 'hs-find-config-')) })
+		afterEach(() => { fs.rmSync(root, { recursive: true, force: true }) })
+
+		it('returns the nearest ancestor holding skills-config.json', () => {
+			fs.writeFileSync(path.join(root, 'skills-config.json'), '{}')
+			const sub = path.join(root, 'a', 'b')
+			fs.mkdirSync(sub, { recursive: true })
+			assert.strictEqual(paths.find_config_root(sub), root)
+		})
+
+		it('finds the root via skills-lock.json when no config file exists yet', () => {
+			fs.writeFileSync(path.join(root, 'skills-lock.json'), '{}')
+			const sub = path.join(root, 'sub')
+			fs.mkdirSync(sub, { recursive: true })
+			assert.strictEqual(paths.find_config_root(sub), root)
+		})
+
+		it('stops at a .git boundary even without a config/lock file', () => {
+			fs.mkdirSync(path.join(root, '.git'))
+			const sub = path.join(root, 'x', 'y')
+			fs.mkdirSync(sub, { recursive: true })
+			assert.strictEqual(paths.find_config_root(sub), root)
+		})
+
+		it('falls back to the start dir when no marker is found', () => {
+			const sub = path.join(root, 'lonely')
+			fs.mkdirSync(sub, { recursive: true })
+			assert.strictEqual(paths.find_config_root(sub), sub)
+		})
+	})
+
 	// NEW-C3 — the server-derived install-dir name must not escape the skills dir.
 	describe('install-dir path safety (NEW-C3)', () => {
 		const base = path.join(os.tmpdir(), 'hs-skills-base')

package/src/constants.js

@@ -22,6 +22,7 @@ const SKILL_JSON = 'skill.json'
 const SKILL_MD = 'SKILL.md'
 const README_MD = 'README.md'
 const LOCK_FILE = 'skills-lock.json'
+const SKILLS_CONFIG_FILE = 'skills-config.json'
 const INSTALL_LOCK = '.install.lock'
 
 const COMMAND_ALIASES = {
@@ -71,6 +72,7 @@ const COMMANDS = [
 	'validate',
 	'self-update',
 	'config',
+	'skills-config',
 	'people',
 	'groups',
 	'access',
@@ -100,6 +102,7 @@ module.exports = {
 	SKILL_MD,
 	README_MD,
 	LOCK_FILE,
+	SKILLS_CONFIG_FILE,
 	INSTALL_LOCK,
 	COMMAND_ALIASES,
 	COMMANDS

package/src/engine/installer.js

@@ -8,7 +8,7 @@ const { check_system_dependencies } = require('./system_deps')
 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 { verify_lock_disk_consistency } = require('../lock/verify')
+const { verify_lock_disk_consistency, dependency_closure_satisfied } = require('../lock/verify')
 const { skills_dir, tmp_dir, skill_install_dir, lock_root } = require('../config/paths')
 const { ensure_dir, remove_dir, file_exists, read_json } = require('../utils/fs')
 const { SKILL_JSON, SKILL_TYPES } = require('../constants')
@@ -110,7 +110,18 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 			const [, exists] = await file_exists(install_dir)
 			if (exists) {
 				const [, valid] = locked.integrity ? await verify_integrity(install_dir, locked.integrity) : [null, true]
-				if (valid !== false) {
+				// The skill itself is present and intact — but "already installed"
+				// must also mean its declared dependency closure is materialized on
+				// disk. A lock entry can carry a `dependencies` map whose skills were
+				// never installed (e.g. a kit entry written by `publish`, which
+				// records deps but installs nothing). Skipping such an entry leaves
+				// the lock and `.agents/skills/` permanently out of sync. If any
+				// transitive dep is missing, decline the skip and fall through to
+				// resolution so the missing deps get backfilled.
+				const [, closure] = valid !== false
+					? await dependency_closure_satisfied(lock_data, skill, (s) => skill_install_dir(base_dir, s.split('/')[1]))
+					: [null, { satisfied: false, missing: [] }]
+				if (valid !== false && closure && closure.satisfied) {
 					// Verify and repair symlinks even for already-installed skills (skip kits — not agent-invocable)
 					if (agents.length > 0 && locked.type !== SKILL_TYPES.KIT) {
 						const name = skill.split('/')[1]
@@ -134,7 +145,8 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 						forced: []
 					}
 				}
-				// integrity mismatch — fall through to reinstall at locked version
+				// integrity mismatch or an incomplete dependency closure — fall
+				// through to re-resolve and reinstall/backfill at the locked version
 			}
 		}
 	}
@@ -371,6 +383,24 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 
 		spinner.succeed(`Installed ${packages_to_install.length} package(s)`)
 
+		// Consumer-side skill configuration (spec 260704-01). For any installed package
+		// that declares a config/env schema, scaffold its .env and write skills-config.json
+		// (beside the lock file). Prompting is opt-in (direct interactive install only); the
+		// no-arg/lock/manifest reinstall paths never set prompt_config, so they scaffold
+		// defaults silently and surface unset required secrets as warnings.
+		const { configure_installed_skills } = require('../skills_config/configure')
+		const [config_err, config_result] = await configure_installed_skills(
+			downloaded.map(({ pkg }) => pkg),
+			{
+				base_dir,
+				config_root: lock_dir,
+				interactive: options.prompt_config === true,
+				only_required: options.config_only_required === true
+			}
+		)
+		if (config_err) print_warn(`Skill configuration step failed: ${config_err[0]?.message || 'unknown error'}`)
+		const config_warnings = config_result?.warnings || []
+
 		const linked_count = downloaded.length - disabled_skills.size
 		if (agents.length > 0 && linked_count > 0) {
 			if (agents_source === 'default') {
@@ -424,7 +454,7 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 		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' }))
 		const default_agent_warnings = _format_default_agent_warnings(agents_source, linked_count)
-		const warnings = [..._format_warnings(missing_deps), ...cycle_warnings, ...default_agent_warnings]
+		const warnings = [..._format_warnings(missing_deps), ...cycle_warnings, ...default_agent_warnings, ...config_warnings]
 		const forced = forced_pkgs.map(p => ({ skill: p.skill, version: p.version }))
 
 		const linked_agents = agents.map(a => a.id)