happyskills 1.16.3 → 1.18.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.18.0] - 2026-07-05
+
+### Added
+
+- Add a static config-usage lint to `happyskills validate`. For a skill whose `skill.json` declares a `config`/`env` block, `validate` now reads the skill's instruction text (SKILL.md + everything under `references/`) and emits advisory **warnings** — never blocking — when the instructions don't reference `happyskills skills-config get` (rule `config_resolution_guidance`, i.e. the skill should embed the one canonical resolution recipe rather than improvise a resolver) or when a declared `config` field / `env` variable is never referenced anywhere in the skill's text (rule `declared_unused`). The check is purely static — it never executes skill code.
+
+### Fixed
+
+- `happyskills uninstall` now cleans up a skill's consumer-side configuration instead of leaving it behind. Previously install wrote a skill's `skills-config.json` block and scaffolded its `.env` secrets, but uninstall removed neither — the config entry and secret lines persisted after the skill was gone. Uninstall (for the named skill and every pruned orphan) now removes the `owner/name` entry from `skills-config.json` and surgically strips the skill's declared secret names from the resolved `envFile` and `.env.example`, deleting the `envFile` if it is left empty. The strip is shared-`envFile` safe — a secret still declared by a skill that remains installed is preserved. Cleanup is best-effort: a failure warns but never fails the uninstall.
+
+## [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.18.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/commands/validate.js

@@ -7,6 +7,7 @@ const { validate_no_conflict_markers } = require('../validation/conflict_marker_
 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 { validate_config_usage } = require('../validation/config_usage_rules')
 const { file_exists, read_json } = require('../utils/fs')
 const { skills_dir, find_project_root, lock_root } = require('../config/paths')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
@@ -178,6 +179,8 @@ const run = (args) => catch_errors('Validate failed', async () => {
 	if (size_err) throw size_err
 	const [cl_err, cl_results] = await validate_changelog_version(skill_dir, json_data.manifest)
 	if (cl_err) throw cl_err
+	const [cfg_err, cfg_results] = await validate_config_usage(skill_dir, json_data.manifest, md_data.content)
+	if (cfg_err) throw cfg_err
 
 	// Dependency validation — registry checks when authenticated
 	let dep_results = []
@@ -219,7 +222,7 @@ const run = (args) => catch_errors('Validate failed', async () => {
 		}
 	}
 
-	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results, ...size_results, ...cl_results, ...dep_results]
+	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results, ...size_results, ...cl_results, ...(cfg_results || []), ...dep_results]
 	const type_label = is_kit ? ' [kit]' : ''
 
 	if (args.flags.json) {

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/engine/uninstaller.js

@@ -4,7 +4,8 @@ const { write_lock, update_lock_skills } = require('../lock/writer')
 const { skills_dir, skill_install_dir, lock_root } = require('../config/paths')
 const { remove_dir } = require('../utils/fs')
 const { resolve_agents, unlink_from_agents } = require('../agents')
-const { print_success, print_info } = require('../ui/output')
+const { cleanup_uninstalled_configs, read_skill_secret_names } = require('../skills_config/cleanup')
+const { print_success, print_info, print_warn } = require('../ui/output')
 
 const find_orphans = (skills, removed_skill) => {
 	// A skill is still needed if a SURVIVING skill (anything other than the one
@@ -98,6 +99,15 @@ const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', asyn
 	const orphans = find_orphans_cascading(all_skills, skill)
 	const to_remove = [skill, ...orphans]
 
+	// Capture each removed skill's declared secret NAMES BEFORE its install dir is deleted —
+	// the manifest is unreadable afterward, and the config cleanup below needs them to surgically
+	// strip the right .env lines. Non-secret / non-config skills yield an empty list.
+	const removed_config_info = []
+	for (const name of to_remove) {
+		const [, secret_names] = await read_skill_secret_names(base_dir, name)
+		removed_config_info.push({ key: name, name: name.split('/')[1], secret_names: secret_names || [] })
+	}
+
 	for (const name of to_remove) {
 		const install_dir = skill_install_dir(base_dir, name.split('/')[1])
 		const [rm_errors] = await remove_dir(install_dir)
@@ -120,6 +130,19 @@ const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', asyn
 	const [write_errors] = await write_lock(lock_dir, new_skills)
 	if (write_errors) throw e('Failed to update lock file', write_errors)
 
+	// Consumer-side config cleanup (spec 260704-01 Tier 6 — prune policy). Drop each removed
+	// skill's skills-config.json block and surgically strip its now-unused secret names from the
+	// .env / .env.example, preserving any secret a surviving skill still declares. Best-effort:
+	// a failure here warns but never fails the uninstall — the skill is already gone.
+	const surviving_keys = Object.keys(all_skills).filter(k => !to_remove.includes(k))
+	const [cleanup_err] = await cleanup_uninstalled_configs({
+		config_root: lock_dir,
+		base_dir,
+		removed: removed_config_info,
+		surviving_keys
+	})
+	if (cleanup_err) print_warn(`Config cleanup step failed: ${cleanup_err[0]?.message || 'unknown error'}`)
+
 	print_success(`Removed ${skill}`)
 	if (orphans.length > 0) {
 		print_info(`Pruned ${orphans.length} orphaned dependency(s): ${orphans.join(', ')}`)

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/cleanup.js

@@ -0,0 +1,107 @@
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+const { read_json, read_file, write_file, file_exists, remove_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 } = require('./writer')
+const { SKILL_JSON } = require('../constants')
+
+const as_object = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : null)
+
+// The env-var names an installed skill declares as SECRETS (secret: true). These are the only
+// names install ever scaffolds into a .env, so they are the only names uninstall may strip.
+const secret_names_from_manifest = (manifest) => {
+	const env = as_object(manifest && manifest.env) || {}
+	return Object.entries(env).filter(([, spec]) => spec && spec.secret).map(([name]) => name)
+}
+
+// Reads a skill's secret var names from its installed skill.json. Called BEFORE the install dir
+// is removed (the manifest is unreadable afterward), so the uninstaller can hand them to cleanup.
+const read_skill_secret_names = (base_dir, key) => catch_errors('Failed to read skill secret names', async () => {
+	const name = key.split('/')[1]
+	const [, manifest] = await read_json(path.join(skill_install_dir(base_dir, name), SKILL_JSON))
+	return secret_names_from_manifest(manifest)
+})
+
+// Pure: drop every `NAME=...` line whose key is in `names`, leaving all other lines (other
+// assignments, comments, blanks) untouched. `all_blank` is true when nothing but whitespace
+// survives — the signal to delete the file rather than leave an empty husk.
+const strip_env_var_lines = (content, names) => {
+	const set = new Set(names)
+	const kept = []
+	let changed = false
+	for (const line of String(content || '').split('\n')) {
+		const idx = line.indexOf('=')
+		const key = idx === -1 ? null : line.slice(0, idx).trim()
+		if (key && set.has(key)) { changed = true; continue }
+		kept.push(line)
+	}
+	return { changed, next: kept.join('\n'), all_blank: kept.every(l => l.trim() === '') }
+}
+
+// Strip `names` from an env file in place. Deletes the file when it is left all-blank; otherwise
+// rewrites it. A missing file or a no-op strip touches nothing.
+const strip_names_from_env_file = (abs, names) => catch_errors('Failed to strip env file', async () => {
+	const [, exists] = await file_exists(abs)
+	if (!exists) return
+	const [, content] = await read_file(abs)
+	const { changed, next, all_blank } = strip_env_var_lines(content, names)
+	if (!changed) return
+	if (all_blank) { const [rm_err] = await remove_file(abs); if (rm_err) throw rm_err[0]; return }
+	const [w_err] = await write_file(abs, next.endsWith('\n') ? next : next + '\n')
+	if (w_err) throw w_err[0]
+})
+
+// Uninstall-time counterpart to configure_installed_skills: for every removed skill, drop its
+// `owner/name` block from skills-config.json and surgically strip its secret NAMES from the
+// resolved envFile (and .env.example). A secret name still declared by a SURVIVING installed
+// skill is preserved (shared-envFile safe). Never touches the .gitignore line. Best-effort —
+// the caller treats a failure here as a warning, not an uninstall failure.
+const cleanup_uninstalled_configs = ({ config_root, base_dir, removed, surviving_keys } = {}) => catch_errors('Failed to clean up skills-config on uninstall', async () => {
+	if (!config_root || !(removed && removed.length)) return { config_keys_removed: [], secrets_stripped: [] }
+
+	const [, existing] = await read_skills_config(config_root)
+
+	// Union of secret names declared by every skill that REMAINS installed — the shared-safe guard.
+	const surviving_secrets = new Set()
+	for (const key of surviving_keys || []) {
+		const name = key.split('/')[1]
+		const [, manifest] = await read_json(path.join(skill_install_dir(base_dir, name), SKILL_JSON))
+		for (const secret of secret_names_from_manifest(manifest)) surviving_secrets.add(secret)
+	}
+
+	const config_keys_removed = []
+	const secrets_stripped = []
+	for (const { key, name, secret_names } of removed) {
+		const entry = get_skill_config_entry(existing, key)
+
+		// Remove the config block (committed, git-recoverable — safe to prune).
+		if (entry) {
+			const [set_err] = await set_skill_config_entry(config_root, key, null)
+			if (set_err) throw set_err[0]
+			config_keys_removed.push(key)
+		}
+
+		const names_to_strip = (secret_names || []).filter(n => !surviving_secrets.has(n))
+		if (!names_to_strip.length) continue
+
+		// envFile: the consumer's declared pointer, else the install-time default location.
+		const env_file_rel = (entry && entry.envFile) || `./secrets/${name}.env`
+		const env_abs = path.resolve(config_root, env_file_rel)
+		const [env_err] = await strip_names_from_env_file(env_abs, names_to_strip)
+		if (env_err) throw env_err[0]
+		// The committed name-only twin gets the same treatment.
+		const [ex_err] = await strip_names_from_env_file(path.join(config_root, '.env.example'), names_to_strip)
+		if (ex_err) throw ex_err[0]
+		secrets_stripped.push(...names_to_strip)
+	}
+
+	return { config_keys_removed, secrets_stripped }
+})
+
+module.exports = {
+	cleanup_uninstalled_configs,
+	read_skill_secret_names,
+	strip_env_var_lines,
+	secret_names_from_manifest
+}