happyskills 1.17.0 → 1.18.0

package/CHANGELOG.md

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

package/package.json

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

package/src/skills_config/cleanup.test.js

@@ -0,0 +1,123 @@
+'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 { cleanup_uninstalled_configs, strip_env_var_lines, read_skill_secret_names } = require('./cleanup')
+
+describe('strip_env_var_lines (pure)', () => {
+	it('removes only the named assignment lines, keeps the rest', () => {
+		const content = 'SLACK_BOT_TOKEN=xoxb-123\nDB_URL=postgres://x\n'
+		const r = strip_env_var_lines(content, ['SLACK_BOT_TOKEN'])
+		assert.equal(r.changed, true)
+		assert.ok(r.next.includes('DB_URL=postgres://x'))
+		assert.ok(!r.next.includes('SLACK_BOT_TOKEN'))
+		assert.equal(r.all_blank, false)
+	})
+
+	it('reports all_blank when nothing but whitespace remains', () => {
+		const r = strip_env_var_lines('SLACK_BOT_TOKEN=xoxb\n', ['SLACK_BOT_TOKEN'])
+		assert.equal(r.changed, true)
+		assert.equal(r.all_blank, true)
+	})
+
+	it('no-op when no named line is present', () => {
+		const r = strip_env_var_lines('DB_URL=x\n', ['NOPE'])
+		assert.equal(r.changed, false)
+	})
+})
+
+// Build a fake project: base_dir holds installed skill dirs (each with skill.json),
+// config_root holds skills-config.json + secrets/*.env + .env.example.
+const scaffold = (root, { skills, config, envFiles, example }) => {
+	const base_dir = path.join(root, 'skills')
+	for (const [key, manifest] of Object.entries(skills)) {
+		const dir = path.join(base_dir, key.split('/')[1])
+		fs.mkdirSync(dir, { recursive: true })
+		fs.writeFileSync(path.join(dir, 'skill.json'), JSON.stringify(manifest))
+	}
+	fs.writeFileSync(path.join(root, 'skills-config.json'), JSON.stringify(config))
+	fs.mkdirSync(path.join(root, 'secrets'), { recursive: true })
+	for (const [rel, body] of Object.entries(envFiles || {})) {
+		fs.writeFileSync(path.join(root, rel), body)
+	}
+	if (example !== undefined) fs.writeFileSync(path.join(root, '.env.example'), example)
+	return base_dir
+}
+
+describe('cleanup_uninstalled_configs', () => {
+	let root
+	beforeEach(() => { root = fs.mkdtempSync(path.join(os.tmpdir(), 'hs-cfg-cleanup-')) })
+	afterEach(() => { fs.rmSync(root, { recursive: true, force: true }) })
+
+	it('removes the uninstalled skill config entry and deletes its now-empty secrets file', async () => {
+		const base_dir = scaffold(root, {
+			skills: {
+				'acme/slack': { name: 'slack', env: { SLACK_BOT_TOKEN: { secret: true, required: true } } },
+				'acme/keep':  { name: 'keep',  env: { DB_URL: { secret: true } } }
+			},
+			config: {
+				'acme/slack': { envFile: './secrets/slack.env', config: { channel: '#ops' } },
+				'acme/keep':  { envFile: './secrets/keep.env' }
+			},
+			envFiles: { 'secrets/slack.env': 'SLACK_BOT_TOKEN=xoxb-123\n', 'secrets/keep.env': 'DB_URL=postgres://x\n' },
+			example: 'SLACK_BOT_TOKEN=\nDB_URL=\n'
+		})
+
+		const [err] = await cleanup_uninstalled_configs({
+			config_root: root,
+			base_dir,
+			removed: [{ key: 'acme/slack', name: 'slack', secret_names: ['SLACK_BOT_TOKEN'] }],
+			surviving_keys: ['acme/keep']
+		})
+		assert.ifError(err)
+
+		const cfg = JSON.parse(fs.readFileSync(path.join(root, 'skills-config.json'), 'utf-8'))
+		assert.ok(!cfg['acme/slack'], 'removed skill entry should be gone')
+		assert.ok(cfg['acme/keep'], 'surviving skill entry should remain')
+		assert.equal(fs.existsSync(path.join(root, 'secrets/slack.env')), false, 'empty secrets file should be deleted')
+		assert.equal(fs.existsSync(path.join(root, 'secrets/keep.env')), true, 'other skill secrets file untouched')
+		const example = fs.readFileSync(path.join(root, '.env.example'), 'utf-8')
+		assert.ok(!example.includes('SLACK_BOT_TOKEN'), 'removed secret name stripped from .env.example')
+		assert.ok(example.includes('DB_URL'), 'surviving secret name kept in .env.example')
+	})
+
+	it('preserves a secret still declared by a surviving skill (shared envFile)', async () => {
+		const base_dir = scaffold(root, {
+			skills: {
+				'acme/slack': { name: 'slack', env: { SLACK_BOT_TOKEN: { secret: true }, SHARED: { secret: true } } },
+				'acme/keep':  { name: 'keep',  env: { SHARED: { secret: true } } }
+			},
+			config: {
+				'acme/slack': { envFile: './secrets/shared.env' },
+				'acme/keep':  { envFile: './secrets/shared.env' }
+			},
+			envFiles: { 'secrets/shared.env': 'SLACK_BOT_TOKEN=xoxb\nSHARED=zzz\n' }
+		})
+
+		const [err] = await cleanup_uninstalled_configs({
+			config_root: root,
+			base_dir,
+			removed: [{ key: 'acme/slack', name: 'slack', secret_names: ['SLACK_BOT_TOKEN', 'SHARED'] }],
+			surviving_keys: ['acme/keep']
+		})
+		assert.ifError(err)
+
+		const env = fs.readFileSync(path.join(root, 'secrets/shared.env'), 'utf-8')
+		assert.ok(!env.includes('SLACK_BOT_TOKEN'), 'unshared secret stripped')
+		assert.ok(env.includes('SHARED=zzz'), 'secret shared with a surviving skill is preserved')
+	})
+
+	it('read_skill_secret_names returns the manifest secret var names', async () => {
+		const base_dir = scaffold(root, {
+			skills: { 'acme/slack': { name: 'slack', env: { SLACK_BOT_TOKEN: { secret: true }, PUBLIC: { secret: false } } } },
+			config: {},
+			envFiles: {}
+		})
+		const [err, names] = await read_skill_secret_names(base_dir, 'acme/slack')
+		assert.ifError(err)
+		assert.deepEqual(names, ['SLACK_BOT_TOKEN'])
+	})
+})

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/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')
+	})
+})