happyskills 1.16.3 → 1.18.0

package/src/skills_config/resolve.test.js

@@ -0,0 +1,112 @@
+'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 { resolve_skill_config, deep_merge, author_defaults } = require('./resolve')
+const { set_skill_config_entry } = require('./writer')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-resolve-'))
+
+const MANIFEST = {
+	name: 'slack-notify',
+	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 }
+	}
+}
+
+let root
+beforeEach(() => { root = make_tmp() })
+afterEach(() => { fs.rmSync(root, { recursive: true, force: true }) })
+
+describe('deep_merge + author_defaults', () => {
+	it('project wins over global wins over defaults', () => {
+		const merged = deep_merge(deep_merge({ a: 1, b: 1, c: 1 }, { b: 2, c: 2 }), { c: 3 })
+		assert.deepStrictEqual(merged, { a: 1, b: 2, c: 3 })
+	})
+
+	it('author_defaults pulls config defaults + NON-secret env defaults, never secret defaults', () => {
+		const d = author_defaults(MANIFEST)
+		assert.strictEqual(d.channel, '#general')
+		assert.strictEqual(d.max_chars, 500)
+		assert.strictEqual(d.DEPLOY_TIMEOUT, 300)
+		assert.ok(!('SLACK_BOT_TOKEN' in d))
+	})
+})
+
+describe('resolve_skill_config — cascade + secrets', () => {
+	it('merges project ⊕ global ⊕ author-default and returns required secret NAMES only', async () => {
+		await set_skill_config_entry(root, 'acme/slack-notify', {
+			envFile: './secrets/slack-notify.env',
+			config: { channel: '#deploys' } // project override
+		})
+
+		const [err, resolved] = await resolve_skill_config('acme/slack-notify', {
+			project_root: root,
+			manifest: MANIFEST,
+			global_config: { 'acme/slack-notify': { config: { max_chars: 900 } } } // global override
+		})
+		assert.ifError(err)
+
+		// project channel wins; global max_chars wins over default; DEPLOY_TIMEOUT falls to default
+		assert.strictEqual(resolved.config.channel, '#deploys')
+		assert.strictEqual(resolved.config.max_chars, 900)
+		assert.strictEqual(resolved.config.DEPLOY_TIMEOUT, 300)
+
+		// required secret NAME only — never a value
+		assert.deepStrictEqual(resolved.requiredSecrets, ['SLACK_BOT_TOKEN'])
+		assert.strictEqual(resolved.secretsPresent, false) // .env has no value
+
+		// resolver returns the ABSOLUTE envFile internally; the command relativizes it to the
+		// caller's cwd for output (see skills-config.test.js)
+		assert.strictEqual(resolved.envFile, path.resolve(root, 'secrets/slack-notify.env'))
+
+		// the whole resolved object never contains a secret value
+		assert.ok(!JSON.stringify(resolved).includes('xoxb'))
+	})
+
+	it('reports secretsPresent:true when the secret is set in the .env', async () => {
+		fs.mkdirSync(path.join(root, 'secrets'), { recursive: true })
+		fs.writeFileSync(path.join(root, 'secrets', 'slack-notify.env'), 'SLACK_BOT_TOKEN=xoxb-real\n')
+		await set_skill_config_entry(root, 'acme/slack-notify', { envFile: './secrets/slack-notify.env', config: {} })
+
+		const [err, resolved] = await resolve_skill_config('acme/slack-notify', {
+			project_root: root, manifest: MANIFEST, global_config: null
+		})
+		assert.ifError(err)
+		assert.strictEqual(resolved.secretsPresent, true)
+		// value is read for presence, but never surfaced
+		assert.ok(!JSON.stringify(resolved).includes('xoxb'))
+	})
+
+	it('NEVER surfaces a secret value even when the author wrongly gives a secret a default (§0 hard rule)', async () => {
+		const bad_manifest = {
+			name: 'leaky',
+			env: { API_KEY: { required: true, secret: true, default: 'sk-LEAKED-DEFAULT' } }
+		}
+		const [err, resolved] = await resolve_skill_config('acme/leaky', {
+			project_root: root, manifest: bad_manifest, global_config: null
+		})
+		assert.ifError(err)
+		assert.ok(!('API_KEY' in resolved.config), 'secret default must not appear in resolved config')
+		assert.ok(!JSON.stringify(resolved).includes('sk-LEAKED-DEFAULT'), 'secret value must never appear anywhere in the resolved object')
+		assert.deepStrictEqual(resolved.requiredSecrets, ['API_KEY'])
+	})
+
+	it('resolves to author defaults when no consumer config exists', async () => {
+		const [err, resolved] = await resolve_skill_config('acme/slack-notify', {
+			project_root: root, manifest: MANIFEST, global_config: null
+		})
+		assert.ifError(err)
+		assert.strictEqual(resolved.config.channel, '#general')
+		assert.strictEqual(resolved.envFile, null)
+		assert.strictEqual(resolved.secretsPresent, false) // required secret, none set
+	})
+})

package/src/skills_config/skills_config.test.js

@@ -0,0 +1,92 @@
+'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 { read_skills_config, get_skill_config_entry } = require('./reader')
+const { write_skills_config, upsert_skill_config, set_skill_config_entry, build_config_entry } = require('./writer')
+const { SKILLS_CONFIG_FILE } = require('../constants')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-skills-config-'))
+const read_raw = (root) => fs.readFileSync(path.join(root, SKILLS_CONFIG_FILE), 'utf-8')
+
+let root
+beforeEach(() => { root = make_tmp() })
+afterEach(() => { fs.rmSync(root, { recursive: true, force: true }) })
+
+describe('skills_config reader', () => {
+	it('returns null when the file does not exist', async () => {
+		const [err, data] = await read_skills_config(root)
+		assert.ifError(err)
+		assert.strictEqual(data, null)
+	})
+
+	it('reads back a written entry', async () => {
+		await set_skill_config_entry(root, 'acme/slack-notify', { envFile: './secrets/x.env', config: { channel: '#deploys' } })
+		const [err, data] = await read_skills_config(root)
+		assert.ifError(err)
+		const entry = get_skill_config_entry(data, 'acme/slack-notify')
+		assert.strictEqual(entry.envFile, './secrets/x.env')
+		assert.deepStrictEqual(entry.config, { channel: '#deploys' })
+	})
+})
+
+describe('skills_config writer — key-scoped writes', () => {
+	it('adding skill B leaves skill A byte-identical', async () => {
+		await set_skill_config_entry(root, 'acme/aaa', { envFile: './secrets/a.env', config: { x: 1 } })
+		const raw_a_before = read_raw(root)
+		const block_a_before = JSON.stringify(JSON.parse(raw_a_before)['acme/aaa'])
+
+		await set_skill_config_entry(root, 'acme/bbb', { envFile: './secrets/b.env', config: { y: 2 } })
+		const parsed = JSON.parse(read_raw(root))
+		assert.strictEqual(JSON.stringify(parsed['acme/aaa']), block_a_before)
+		assert.ok(parsed['acme/bbb'])
+	})
+
+	it('produces sorted, byte-stable output across two identical writes', async () => {
+		await set_skill_config_entry(root, 'acme/zzz', { envFile: './z.env', config: { b: 2, a: 1 } })
+		await set_skill_config_entry(root, 'acme/aaa', { envFile: './a.env', config: { d: 4, c: 3 } })
+		const first = read_raw(root)
+
+		// Top-level keys sorted: acme/aaa before acme/zzz
+		assert.ok(first.indexOf('acme/aaa') < first.indexOf('acme/zzz'))
+		// Nested config keys sorted too
+		assert.ok(first.indexOf('"c"') < first.indexOf('"d"'))
+
+		// Re-writing the same entry yields identical bytes
+		await set_skill_config_entry(root, 'acme/aaa', { envFile: './a.env', config: { d: 4, c: 3 } })
+		assert.strictEqual(read_raw(root), first)
+	})
+
+	it('never persists a secret value — build_config_entry drops everything but envFile and config', () => {
+		const entry = build_config_entry({
+			envFile: './secrets/x.env',
+			config: { channel: '#deploys' },
+			SLACK_BOT_TOKEN: 'xoxb-super-secret',
+			secrets: { SLACK_BOT_TOKEN: 'xoxb-super-secret' }
+		})
+		assert.deepStrictEqual(Object.keys(entry).sort(), ['config', 'envFile'])
+		assert.ok(!JSON.stringify(entry).includes('xoxb-super-secret'))
+	})
+
+	it('upsert with null removes the key', () => {
+		const next = upsert_skill_config({ 'acme/a': { config: {} }, 'acme/b': { config: {} } }, 'acme/a', null)
+		assert.deepStrictEqual(Object.keys(next), ['acme/b'])
+	})
+
+	it('refuses to clobber an existing but corrupt skills-config.json (data-loss guard)', async () => {
+		fs.writeFileSync(path.join(root, SKILLS_CONFIG_FILE), '{ this is not valid json ')
+		const [err] = await set_skill_config_entry(root, 'acme/new', { config: { x: 1 } })
+		assert.ok(err, 'a corrupt existing file must surface an error, not be silently overwritten')
+		// original corrupt content is preserved, not replaced
+		assert.strictEqual(read_raw(root), '{ this is not valid json ')
+	})
+
+	it('write_skills_config sorts keys deeply', async () => {
+		await write_skills_config(root, { 'z/z': { config: { b: 1, a: 2 } }, 'a/a': { envFile: './a.env' } })
+		const raw = read_raw(root)
+		assert.ok(raw.indexOf('a/a') < raw.indexOf('z/z'))
+	})
+})

package/src/skills_config/writer.js

@@ -0,0 +1,59 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { atomic_write_json, read_json, file_exists } = require('../utils/fs')
+const { skills_config_file_path } = require('../config/paths')
+
+// Deterministic serialization: recursively sort object keys so concurrent git additions
+// merge cleanly and re-writing an unchanged entry is byte-stable. Arrays and scalars pass
+// through untouched.
+const sort_keys_deep = (value) => {
+	if (Array.isArray(value)) return value.map(sort_keys_deep)
+	if (value === null || typeof value !== 'object') return value
+	const out = {}
+	for (const key of Object.keys(value).sort()) out[key] = sort_keys_deep(value[key])
+	return out
+}
+
+// A skills-config.json entry carries ONLY a non-secret `envFile` pointer and non-secret
+// `config` overrides. This helper is the structural guard that a secret value can never
+// leak into the committed file — anything but envFile/config is dropped here.
+const build_config_entry = ({ envFile, config } = {}) => {
+	const entry = {}
+	if (envFile !== undefined) entry.envFile = envFile
+	if (config !== undefined) entry.config = config
+	return entry
+}
+
+const upsert_skill_config = (existing, key, entry) => {
+	const out = { ...(existing || {}) }
+	if (entry === null) delete out[key]
+	else out[key] = entry
+	return out
+}
+
+const write_skills_config = (project_root, config_data) => catch_errors('Failed to write skills-config.json', async () => {
+	const config_path = skills_config_file_path(project_root)
+	const [errors] = await atomic_write_json(config_path, sort_keys_deep(config_data || {}))
+	if (errors) throw errors[0]
+})
+
+// Read-modify-write a single `owner/name` subtree: read the current file, replace only that
+// key's block (leaving every other skill's block untouched), and atomically re-serialize with
+// sorted keys. Pass `entry: null` to remove the key.
+const set_skill_config_entry = (project_root, key, entry) => catch_errors('Failed to set skills-config.json entry', async () => {
+	const config_path = skills_config_file_path(project_root)
+	const [read_errors, existing] = await read_json(config_path)
+	// Distinguish "no file yet" (start fresh) from "file exists but is corrupt". Clobbering a
+	// corrupt file would silently discard every OTHER skill's block — the exact opposite of the
+	// key-scoped guarantee. On a corrupt existing file, fail loud instead of overwriting.
+	if (read_errors) {
+		const [, exists] = await file_exists(config_path)
+		if (exists) throw new Error(`skills-config.json exists but could not be parsed at ${config_path} — refusing to overwrite it. Fix or remove the file, then retry.`)
+	}
+	const current = read_errors ? {} : (existing || {})
+	const next = upsert_skill_config(current, key, entry)
+	const [write_errors] = await atomic_write_json(config_path, sort_keys_deep(next))
+	if (write_errors) throw write_errors[0]
+	return next
+})
+
+module.exports = { write_skills_config, upsert_skill_config, set_skill_config_entry, build_config_entry, sort_keys_deep }

package/src/utils/fs.js

@@ -38,6 +38,10 @@ const remove_dir = (dir_path) => catch_errors(`Failed to remove directory ${dir_
 	await fs.promises.rm(dir_path, { recursive: true, force: true })
 })
 
+const remove_file = (file_path) => catch_errors(`Failed to remove file ${file_path}`, async () => {
+	await fs.promises.rm(file_path, { force: true })
+})
+
 const read_file = (file_path) => catch_errors(`Failed to read file ${file_path}`, async () => {
 	return await fs.promises.readFile(file_path, 'utf-8')
 })
@@ -46,4 +50,4 @@ const write_file = (file_path, content) => catch_errors(`Failed to write file ${
 	await fs.promises.writeFile(file_path, content, 'utf-8')
 })
 
-module.exports = { read_json, write_json, atomic_write_json, ensure_dir, file_exists, remove_dir, read_file, write_file }
+module.exports = { read_json, write_json, atomic_write_json, ensure_dir, file_exists, remove_dir, remove_file, read_file, write_file }

package/src/utils/prompt.js

@@ -13,4 +13,19 @@ const confirm_prompt = (message) => new Promise((resolve) => {
 	})
 })
 
-module.exports = { confirm_prompt }
+// Free-text prompt. Returns the trimmed answer, or '' when there is no TTY (so callers
+// fall back to the schema default). Writes to stderr to keep stdout envelope-clean.
+const question_prompt = (message) => new Promise((resolve) => {
+	if (!process.stdin.isTTY) {
+		resolve('')
+		return
+	}
+
+	const rl = createInterface({ input: process.stdin, output: process.stderr })
+	rl.question(`${message} `, (answer) => {
+		rl.close()
+		resolve(answer.trim())
+	})
+})
+
+module.exports = { confirm_prompt, question_prompt }

package/src/validation/config_usage_rules.js

@@ -0,0 +1,86 @@
+'use strict'
+// Static config-usage lint — the deterministic authoring gate for config/secret skills.
+//
+// It CANNOT prove a skill's runtime resolver is correct (that needs execution, and we
+// deliberately don't execute skill code). Instead it verifies, statically, that a skill which
+// declares config/env ships the ONE correct resolution recipe rather than improvising: (a) its
+// instructions reference `happyskills skills-config get` (the canonical resolver — the file
+// fallback embedded alongside it is our vetted recipe, not a per-skill invention), and (b) every
+// declared config field / env var is actually referenced in the skill's text. No code execution.
+
+const path = require('path')
+const fs = require('fs')
+const { error: { catch_errors } } = require('puffy-core')
+const { file_exists, read_file } = require('../utils/fs')
+const { SKILL_JSON, SKILL_MD } = require('../constants')
+
+const RESOLVER_HINT = 'skills-config get'
+
+const as_object = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : null)
+
+const has_config_schema = (m) => {
+	const c = as_object(m && m.config)
+	const e = as_object(m && m.env)
+	return !!((c && Object.keys(c).length) || (e && Object.keys(e).length))
+}
+
+const result = (file, field, rule, severity, message, value) => ({
+	file, field, rule, severity, message, ...(value !== undefined ? { value } : {})
+})
+
+// Recursively collect files under a directory (best-effort; references are text/markdown).
+const collect_files = (dir) => {
+	const out = []
+	const walk = (d) => {
+		for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+			const full = path.join(d, entry.name)
+			if (entry.isDirectory()) walk(full)
+			else out.push(full)
+		}
+	}
+	try { walk(dir) } catch { /* unreadable dir — nothing to scan */ }
+	return out
+}
+
+// Pure static lint over the manifest + the skill's full instruction text (SKILL.md + references).
+const check_config_usage = (manifest, text) => {
+	if (!has_config_schema(manifest)) return []
+	const results = []
+	const body = String(text || '')
+
+	if (!body.includes(RESOLVER_HINT)) {
+		results.push(result(SKILL_MD, 'config', 'config_resolution_guidance', 'warning',
+			'Skill declares config/env but its instructions never reference `happyskills skills-config get`. Embed the canonical resolution snippet (skill-authoring.md § Configuration) so the agent resolves config deterministically instead of improvising — a hand-derived resolver risks reading a relative envFile against the wrong directory.'))
+	}
+
+	const config = as_object(manifest.config)
+	if (config) for (const field of Object.keys(config)) {
+		if (!body.includes(field)) results.push(result(SKILL_JSON, 'config', 'declared_unused', 'warning',
+			`config field "${field}" is declared in skill.json but never referenced in the skill's instructions — use it or remove the declaration.`, field))
+	}
+
+	const env = as_object(manifest.env)
+	if (env) for (const name of Object.keys(env)) {
+		if (!body.includes(name)) results.push(result(SKILL_JSON, 'env', 'declared_unused', 'warning',
+			`env variable "${name}" is declared in skill.json but never referenced in the skill's instructions — use it or remove the declaration.`, name))
+	}
+
+	return results
+}
+
+// Reads SKILL.md (passed in) + every file under references/, then runs the static lint.
+const validate_config_usage = (skill_dir, manifest, skill_md_content) => catch_errors('Failed to validate config usage', async () => {
+	if (!has_config_schema(manifest)) return []
+	let text = String(skill_md_content || '')
+	const refs_dir = path.join(skill_dir, 'references')
+	const [, refs_exists] = await file_exists(refs_dir)
+	if (refs_exists) {
+		for (const file of collect_files(refs_dir)) {
+			const [, content] = await read_file(file)
+			if (content) text += '\n' + content
+		}
+	}
+	return check_config_usage(manifest, text)
+})
+
+module.exports = { check_config_usage, validate_config_usage, has_config_schema }

package/src/validation/config_usage_rules.test.js

@@ -0,0 +1,61 @@
+'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 { check_config_usage, validate_config_usage } = require('./config_usage_rules')
+
+const SLACK = {
+	name: 'slack-notify',
+	config: { channel: { type: 'string', default: '#general' } },
+	env: { SLACK_BOT_TOKEN: { required: true, secret: true } }
+}
+
+describe('check_config_usage (pure)', () => {
+	it('warns when a config/env skill never references `skills-config get`', () => {
+		const r = check_config_usage(SLACK, 'Posts to a channel using a token.')
+		assert.ok(r.some(x => x.rule === 'config_resolution_guidance' && x.severity === 'warning'))
+	})
+
+	it('does NOT warn about resolution guidance when `skills-config get` is embedded', () => {
+		const text = 'Run `happyskills skills-config get acme/slack-notify --json`. Uses channel and SLACK_BOT_TOKEN.'
+		const r = check_config_usage(SLACK, text)
+		assert.ok(!r.some(x => x.rule === 'config_resolution_guidance'))
+	})
+
+	it('warns per declared config field / env var that is never referenced', () => {
+		// references the recipe + channel, but NOT SLACK_BOT_TOKEN
+		const text = 'happyskills skills-config get acme/slack-notify. Posts to channel.'
+		const r = check_config_usage(SLACK, text)
+		assert.ok(r.some(x => x.rule === 'declared_unused' && x.value === 'SLACK_BOT_TOKEN'), 'unused env var should warn')
+		assert.ok(!r.some(x => x.rule === 'declared_unused' && x.value === 'channel'), 'referenced config field should not warn')
+	})
+
+	it('returns no results for a skill with no config/env block', () => {
+		assert.deepStrictEqual(check_config_usage({ name: 'plain' }, 'anything at all'), [])
+	})
+
+	it('a well-formed, fully-referenced config skill yields no warnings', () => {
+		const text = 'Resolve via `happyskills skills-config get acme/slack-notify --json`. Uses channel and SLACK_BOT_TOKEN.'
+		const r = check_config_usage(SLACK, text)
+		assert.deepStrictEqual(r, [])
+	})
+})
+
+describe('validate_config_usage (reads SKILL.md + references/)', () => {
+	let dir
+	beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), 'hs-cfg-usage-')) })
+	afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }) })
+
+	it('finds the recipe + token references across references/ files', async () => {
+		fs.writeFileSync(path.join(dir, 'SKILL.md'), '# Slack\nSee references for setup.\n')
+		fs.mkdirSync(path.join(dir, 'references'))
+		fs.writeFileSync(path.join(dir, 'references', 'setup.md'),
+			'Run `happyskills skills-config get acme/slack-notify --json`. Uses channel and SLACK_BOT_TOKEN.')
+		const [err, results] = await validate_config_usage(dir, SLACK, '# Slack\nSee references for setup.\n')
+		assert.ifError(err)
+		assert.deepStrictEqual(results, [], 'recipe + tokens in references/ should satisfy the lint')
+	})
+})

package/src/validation/skill_json_rules.js

@@ -7,6 +7,7 @@ const { SKILL_JSON, VALID_SKILL_TYPES, SKILL_TYPES, KIT_PREFIX } = require('../c
 const NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/
 const KIT_NAME_PATTERN = /^_kit-[a-z0-9][a-z0-9-]*$/
 const REQUIRED_PLATFORMS = ['darwin', 'linux', 'win32']
+const CONFIG_TYPES = ['string', 'integer', 'number', 'boolean']
 
 const result = (field, rule, severity, message, value) => ({
 	file: SKILL_JSON, field, rule, severity, message, ...(value !== undefined ? { value } : {})
@@ -180,6 +181,102 @@ const validate_system_dependencies = (manifest) => {
 	return results
 }
 
+// config: map of field -> { type, default?, description?, required? }. Non-secret,
+// typed tunables that override the skill's hardcoded defaults. `type` is required.
+const validate_config = (manifest) => {
+	const results = []
+	const config = manifest.config
+
+	if (config === undefined) return results
+
+	if (typeof config !== 'object' || Array.isArray(config)) {
+		results.push(result('config', 'type', 'error', 'config must be an object'))
+		return results
+	}
+
+	for (const [key, entry] of Object.entries(config)) {
+		if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+			results.push(result('config', 'entry_structure', 'error', `config field "${key}" must be an object`, key))
+			continue
+		}
+
+		if (!CONFIG_TYPES.includes(entry.type)) {
+			results.push(result('config', 'type_value', 'error', `config field "${key}" must declare a "type" of: ${CONFIG_TYPES.join(', ')} — got "${entry.type}"`, key))
+		}
+
+		if (entry.required !== undefined && typeof entry.required !== 'boolean') {
+			results.push(result('config', 'required_flag', 'error', `config field "${key}" "required" must be a boolean`, key))
+		}
+
+		if (entry.description !== undefined && typeof entry.description !== 'string') {
+			results.push(result('config', 'description_type', 'error', `config field "${key}" "description" must be a string`, key))
+		}
+	}
+
+	return results
+}
+
+// env: map of VAR_NAME -> { required?, secret?, description?, type?, default?, validate? }.
+// `required: true` entries are the activation gate. Secrets are routed to the .env, never
+// committed — so a secret with an inline default is a warning, not a hard error.
+const validate_env = (manifest) => {
+	const results = []
+	const env = manifest.env
+
+	if (env === undefined) return results
+
+	if (typeof env !== 'object' || Array.isArray(env)) {
+		results.push(result('env', 'type', 'error', 'env must be an object'))
+		return results
+	}
+
+	const seen_lower = new Map()
+
+	for (const [key, entry] of Object.entries(env)) {
+		if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+			results.push(result('env', 'entry_structure', 'error', `env var "${key}" must be an object`, key))
+			continue
+		}
+
+		if (entry.required !== undefined && typeof entry.required !== 'boolean') {
+			results.push(result('env', 'required_flag', 'error', `env var "${key}" "required" must be a boolean`, key))
+		}
+
+		if (entry.secret !== undefined && typeof entry.secret !== 'boolean') {
+			results.push(result('env', 'secret_flag', 'error', `env var "${key}" "secret" must be a boolean`, key))
+		}
+
+		if (entry.secret === true && entry.default !== undefined) {
+			results.push(result('env', 'secret_default', 'warning', `env var "${key}" is secret but carries a committed default — secret fields must not carry a committed default`, key))
+		}
+
+		if (entry.type !== undefined && !CONFIG_TYPES.includes(entry.type)) {
+			results.push(result('env', 'type_value', 'error', `env var "${key}" has unknown type "${entry.type}" (allowed: ${CONFIG_TYPES.join(', ')})`, key))
+		}
+
+		if (entry.validate !== undefined) {
+			if (typeof entry.validate !== 'string') {
+				results.push(result('env', 'validate_regex', 'error', `env var "${key}" "validate" must be a string regex`, key))
+			} else {
+				try {
+					new RegExp(entry.validate)
+				} catch (err) {
+					results.push(result('env', 'validate_regex', 'error', `env var "${key}" "validate" is not a valid regex: ${err.message}`, key))
+				}
+			}
+		}
+
+		const lower = key.toLowerCase()
+		if (seen_lower.has(lower)) {
+			results.push(result('env', 'case_collision', 'error', `env var "${key}" collides case-insensitively with "${seen_lower.get(lower)}" — env names must be unique regardless of case`, key))
+		} else {
+			seen_lower.set(lower, key)
+		}
+	}
+
+	return results
+}
+
 const validate_skill_json = (skill_dir) => catch_errors('Failed to validate skill.json', async () => {
 	const results = []
 	const json_path = path.join(skill_dir, SKILL_JSON)
@@ -209,6 +306,8 @@ const validate_skill_json = (skill_dir) => catch_errors('Failed to validate skil
 	results.push(...validate_description(manifest))
 	results.push(...validate_dependencies(manifest))
 	results.push(...validate_system_dependencies(manifest))
+	results.push(...validate_config(manifest))
+	results.push(...validate_env(manifest))
 
 	const is_kit = manifest.type === SKILL_TYPES.KIT
 	if (is_kit) {