happyskills 1.16.3 → 1.17.0

package/CHANGELOG.md

@@ -7,6 +7,15 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.16.3",
+	"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/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

@@ -118,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
@@ -289,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 = []
 

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

@@ -383,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') {
@@ -436,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)

package/src/integration/skills-config.test.js

@@ -0,0 +1,98 @@
+'use strict'
+// Conformance test for `happyskills skills-config get` — spec 260704-01 Tier 3 §4.4.
+// Exercises the real command end-to-end (spawned CLI) against a tmp project: envelope
+// conformance (STRICT), owner/name validation, and the §0 hard rule that no secret VALUE
+// ever reaches stdout/stderr.
+
+const { describe, it, beforeEach, afterEach } = require('node:test')
+const assert = require('node:assert/strict')
+const { spawnSync } = require('child_process')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const CLI = path.resolve(__dirname, '../../bin/happyskills.js')
+const NODE = process.execPath
+
+const run = (args, cwd) => {
+	const result = spawnSync(NODE, [CLI, ...args], {
+		cwd,
+		env: { ...process.env, NO_COLOR: '1', HAPPYSKILLS_ENVELOPE_STRICT: '1', HAPPYSKILLS_API_URL: 'http://localhost:0', CI: '' },
+		encoding: 'utf-8',
+		timeout: 10000,
+	})
+	return { stdout: result.stdout || '', stderr: result.stderr || '', code: result.status }
+}
+
+const SECRET = 'xoxb-SUPER-SECRET-DO-NOT-LEAK'
+
+let proj
+beforeEach(() => {
+	proj = fs.mkdtempSync(path.join(os.tmpdir(), 'hs-sc-cmd-'))
+	const skill_dir = path.join(proj, '.agents', 'skills', 'slack-notify')
+	fs.mkdirSync(skill_dir, { recursive: true })
+	fs.writeFileSync(path.join(skill_dir, 'skill.json'), JSON.stringify({
+		name: 'slack-notify', version: '1.0.0',
+		config: { channel: { type: 'string', default: '#general' }, max_chars: { type: 'integer', default: 500 } },
+		env: { SLACK_BOT_TOKEN: { required: true, secret: true }, DEPLOY_TIMEOUT: { required: false, secret: false, type: 'integer', default: 300 } }
+	}))
+	fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), '# slack\n')
+	fs.writeFileSync(path.join(proj, 'skills-config.json'), JSON.stringify({
+		'acme/slack-notify': { envFile: './secrets/slack-notify.env', config: { channel: '#deploys' } }
+	}))
+	fs.mkdirSync(path.join(proj, 'secrets'), { recursive: true })
+	fs.writeFileSync(path.join(proj, 'secrets', 'slack-notify.env'), `SLACK_BOT_TOKEN=${SECRET}\n`)
+})
+afterEach(() => { fs.rmSync(proj, { recursive: true, force: true }) })
+
+describe('happyskills skills-config get', () => {
+	it('emits a valid success envelope with the resolved non-secret config — and NO secret value', () => {
+		const { stdout, stderr, code } = run(['skills-config', 'get', 'acme/slack-notify', '--json'], proj)
+		assert.strictEqual(code, 0)
+		const env = JSON.parse(stdout)
+		assert.strictEqual(env.ok, true)
+		assert.strictEqual(env.meta.command, 'skills-config')
+		assert.strictEqual(typeof env.data, 'object')
+		assert.ok(!Array.isArray(env.data))
+		assert.strictEqual(env.data.config.channel, '#deploys')      // project override wins
+		assert.strictEqual(env.data.config.max_chars, 500)           // author default
+		assert.deepStrictEqual(env.data.requiredSecrets, ['SLACK_BOT_TOKEN'])
+		assert.strictEqual(env.data.secretsPresent, true)
+		assert.strictEqual(env.data.envFile, './secrets/slack-notify.env')
+
+		// §0 hard rule: the secret VALUE must never appear in any output stream
+		assert.ok(!stdout.includes(SECRET), 'secret leaked to stdout')
+		assert.ok(!stderr.includes(SECRET), 'secret leaked to stderr')
+	})
+
+	it('resolves from a SUBDIRECTORY by walking up to the project root (§6 #7)', () => {
+		const sub = path.join(proj, 'services', 'api')
+		fs.mkdirSync(sub, { recursive: true })
+		const { stdout, code } = run(['skills-config', 'get', 'acme/slack-notify', '--json'], sub)
+		assert.strictEqual(code, 0)
+		const env = JSON.parse(stdout)
+		assert.strictEqual(env.ok, true)
+		// same resolution as from the root — proves the CLI now matches the file-fallback walk-up
+		assert.strictEqual(env.data.config.channel, '#deploys')
+		assert.strictEqual(env.data.secretsPresent, true)
+		// envFile is relative to the caller's cwd (the subdir), so it stays usable from here
+		assert.strictEqual(env.data.envFile, '../../secrets/slack-notify.env')
+	})
+
+	it('rejects a non-owner/name argument with a USAGE_ERROR envelope', () => {
+		const { stdout, code } = run(['skills-config', 'get', 'not-a-scoped-name', '--json'], proj)
+		assert.strictEqual(code, 2)
+		const env = JSON.parse(stdout)
+		assert.strictEqual(env.ok, false)
+		assert.strictEqual(env.error.code, 'USAGE_ERROR')
+		assert.strictEqual(typeof env.data, 'object')
+	})
+
+	it('rejects an unknown subcommand', () => {
+		const { stdout, code } = run(['skills-config', 'wat', '--json'], proj)
+		assert.strictEqual(code, 2)
+		const env = JSON.parse(stdout)
+		assert.strictEqual(env.ok, false)
+		assert.strictEqual(env.error.code, 'USAGE_ERROR')
+	})
+})

package/src/skills_config/configure.js

@@ -0,0 +1,172 @@
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+const { file_exists, read_json, ensure_dir, read_file, write_file } = require('../utils/fs')
+const { skill_install_dir } = require('../config/paths')
+const { read_skills_config, get_skill_config_entry } = require('./reader')
+const { set_skill_config_entry, build_config_entry } = require('./writer')
+const { question_prompt } = require('../utils/prompt')
+const { SKILL_JSON } = require('../constants')
+
+const to_posix = (p) => p.split(path.sep).join('/')
+
+const coerce = (raw, type) => {
+	if (type === 'integer' || type === 'number') {
+		const n = Number(raw)
+		return Number.isNaN(n) ? raw : n
+	}
+	if (type === 'boolean') return /^(y|yes|true|1)$/i.test(raw)
+	return raw
+}
+
+const as_object = (value) => (value && typeof value === 'object' && !Array.isArray(value) ? value : null)
+
+// Append missing `NAME=` lines to an env file, never touching lines that already exist —
+// so a value the consumer already set is preserved on reinstall/update.
+const ensure_env_names = (file_path, names) => catch_errors('Failed to scaffold env file', async () => {
+	const [, exists] = await file_exists(file_path)
+	let content = ''
+	if (exists) { const [, c] = await read_file(file_path); content = c || '' }
+
+	const present = new Set(content.split('\n').map(l => l.split('=')[0].trim()).filter(Boolean))
+	const additions = names.filter(n => !present.has(n)).map(n => `${n}=`)
+	if (!additions.length && exists) return
+
+	await ensure_dir(path.dirname(file_path))
+	const base = content.length && !content.endsWith('\n') ? content + '\n' : content
+	await write_file(file_path, `${base}${additions.join('\n')}${additions.length ? '\n' : ''}`)
+})
+
+const ensure_gitignore_entry = (root, pattern) => catch_errors('Failed to update .gitignore', async () => {
+	const gitignore = path.join(root, '.gitignore')
+	const [, exists] = await file_exists(gitignore)
+	let content = ''
+	if (exists) { const [, c] = await read_file(gitignore); content = c || '' }
+
+	const lines = content.split('\n').map(l => l.trim())
+	if (lines.includes(pattern)) return
+
+	const base = content.length && !content.endsWith('\n') ? content + '\n' : content
+	await write_file(gitignore, `${base}${pattern}\n`)
+})
+
+// A required secret is "unset" unless it is present with a non-empty value in ambient
+// process.env or in the scaffolded .env file. Presence gates the fail-loud warning.
+const secret_is_set = (env_abs, name) => catch_errors('Failed to check secret presence', async () => {
+	if (process.env[name] && process.env[name].trim() !== '') return true
+	const [, exists] = await file_exists(env_abs)
+	if (!exists) return false
+	const [, content] = await read_file(env_abs)
+	for (const line of (content || '').split('\n')) {
+		const idx = line.indexOf('=')
+		if (idx === -1) continue
+		if (line.slice(0, idx).trim() === name && line.slice(idx + 1).trim() !== '') return true
+	}
+	return false
+})
+
+// For every installed package that declares a `config`/`env` schema, resolve the consumer's
+// choices and persist them: non-secret overrides → skills-config.json `config`; secret names →
+// the gitignored .env (+ committed .env.example, name only); the pointer → `envFile`. Secret
+// VALUES are never written anywhere by this function — build_config_entry structurally drops
+// anything but envFile/config. Returns warnings naming required secrets still unset.
+const configure_installed_skills = (packages, options = {}) => catch_errors('Failed to configure installed skills', async () => {
+	const { base_dir, config_root, interactive = false, only_required = false, ask = question_prompt } = options
+	const warnings = []
+
+	const [, existing_config_file] = await read_skills_config(config_root)
+
+	for (const pkg of packages || []) {
+		const key = pkg.skill
+		const name = key.split('/')[1]
+		const install_dir = skill_install_dir(base_dir, name)
+		const [, manifest] = await read_json(path.join(install_dir, SKILL_JSON))
+		if (!manifest) continue
+
+		const config_schema = as_object(manifest.config)
+		const env_schema = as_object(manifest.env)
+		if (!config_schema && !env_schema) continue
+
+		// Existing consumer choices are preserved verbatim; we only ever ADD to them.
+		// `only_required` (update/reconcile) narrows prompting to newly-required fields
+		// absent from the existing entry, so unrelated values are never re-asked.
+		const existing_entry = get_skill_config_entry(existing_config_file, key)
+		const existing_overrides = as_object(existing_entry && existing_entry.config) || {}
+		const overrides = { ...existing_overrides }
+
+		const maybe_prompt = async (field, spec) => {
+			if (!interactive) return
+			const already_set = Object.prototype.hasOwnProperty.call(existing_overrides, field)
+			const is_required = spec && spec.required === true
+			if (already_set) return
+			if (only_required && !is_required) return
+			const def = spec && spec.default
+			const label = `${field}${spec && spec.description ? ` — ${spec.description}` : ''} [${def ?? ''}]:`
+			const answer = await ask(label)
+			if (answer !== '' && answer !== String(def ?? '')) overrides[field] = coerce(answer, spec && spec.type)
+		}
+
+		// config fields — prompt (per the rules above); store non-default answers.
+		for (const [field, spec] of Object.entries(config_schema || {})) {
+			await maybe_prompt(field, spec)
+		}
+
+		// env fields — secrets route to the .env; non-secret env is treated like config.
+		const secret_names = []
+		for (const [var_name, spec] of Object.entries(env_schema || {})) {
+			if (spec && spec.secret) {
+				secret_names.push({ name: var_name, required: spec.required === true })
+				continue
+			}
+			await maybe_prompt(var_name, spec)
+		}
+
+		let env_file_rel = (existing_entry && existing_entry.envFile) || null
+		if (secret_names.length) {
+			env_file_rel = env_file_rel || `./secrets/${name}.env`
+			// Resolve the (possibly consumer-chosen) envFile relative to the config root.
+			const env_abs = path.resolve(config_root, env_file_rel)
+			const [scaffold_err] = await ensure_env_names(env_abs, secret_names.map(s => s.name))
+			if (scaffold_err) throw scaffold_err[0]
+			const [example_err] = await ensure_env_names(path.join(config_root, '.env.example'), secret_names.map(s => s.name))
+			if (example_err) throw example_err[0]
+
+			const dir_rel = to_posix(path.relative(config_root, path.dirname(env_abs)))
+			const [gi_err] = await ensure_gitignore_entry(config_root, dir_rel ? `${dir_rel}/*.env` : '*.env')
+			if (gi_err) throw gi_err[0]
+
+			for (const secret of secret_names.filter(s => s.required)) {
+				const [, is_set] = await secret_is_set(env_abs, secret.name)
+				if (!is_set) warnings.push(`Required secret ${secret.name} for ${key} is not set — add it to ${env_file_rel}`)
+			}
+		}
+
+		// Fail-loud (§4.3.2): a required NON-secret config/env field with no value and no
+		// author default would be silently undefined at runtime. Surface it as a warning —
+		// the same discipline the secret loop above applies to required secrets.
+		const warn_required_unset = (field, spec) => {
+			if (!spec || spec.required !== true) return
+			if (spec.default !== undefined) return
+			if (Object.prototype.hasOwnProperty.call(overrides, field)) return
+			warnings.push(`Required config "${field}" for ${key} is not set — no value provided and the skill declares no default.`)
+		}
+		for (const [field, spec] of Object.entries(config_schema || {})) warn_required_unset(field, spec)
+		for (const [var_name, spec] of Object.entries(env_schema || {})) {
+			if (spec && spec.secret) continue
+			warn_required_unset(var_name, spec)
+		}
+
+		const entry = build_config_entry({
+			...(env_file_rel ? { envFile: env_file_rel } : {}),
+			...(Object.keys(overrides).length ? { config: overrides } : {})
+		})
+
+		if (Object.keys(entry).length) {
+			const [set_err] = await set_skill_config_entry(config_root, key, entry)
+			if (set_err) throw set_err[0]
+		}
+	}
+
+	return { warnings }
+})
+
+module.exports = { configure_installed_skills }