happyskills 1.17.0 → 1.19.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.19.0] - 2026-07-06
+
+### Added
+
+- Add constellation-aware shared secrets. A non-kit skill that declares `sharedEnv: true` in `skill.json` now shares a single `./secrets/<core>.env` across itself and its skill-dependencies on install, instead of scaffolding an identical per-skill secrets file for every member (the redundant, drift-prone case for related skills). A consumer-set `envFile` still wins, standalone installs and kits are unaffected, and a collision guard warns when two shared members declare the same secret name with a different type. `happyskills validate` now checks `sharedEnv` (must be a boolean; error on a kit; warning when `true` without dependencies). Documented in `docs/skill-format.md` §4.6.
+
+## [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.19.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/skills_config/configure.js

@@ -75,11 +75,54 @@ const configure_installed_skills = (packages, options = {}) => catch_errors('Fai
 
 	const [, existing_config_file] = await read_skills_config(config_root)
 
+	// Constellation shared-env pre-pass (spec: `sharedEnv`). A non-kit package that declares
+	// `sharedEnv: true` is a constellation root: it and every skill-dependency being installed
+	// share ONE derived `.env` (`./secrets/<root>.env`) instead of a redundant, drift-prone file
+	// each. Kits (unrelated bundles) are excluded and keep per-member files. Deterministic: sorted
+	// iteration, first root wins, and a consumer's own envFile pointer (honored in the loop below)
+	// always overrides the shared default.
+	const pkg_keys = new Set((packages || []).map(p => p.skill))
+	const manifest_by_key = new Map()
+	for (const pkg of packages || []) {
+		const pkg_name = pkg.skill.split('/')[1]
+		const [, m] = await read_json(path.join(skill_install_dir(base_dir, pkg_name), SKILL_JSON))
+		if (m) manifest_by_key.set(pkg.skill, m)
+	}
+
+	const shared_env_file_by_key = new Map()
+	for (const root_key of [...pkg_keys].sort()) {
+		const m = manifest_by_key.get(root_key)
+		if (!m || m.sharedEnv !== true || m.type === 'kit') continue
+		const shared_file = `./secrets/${root_key.split('/')[1]}.env`
+		const dep_keys = Object.keys(as_object(m.dependencies) || {})
+		for (const member_key of [root_key, ...dep_keys]) {
+			if (pkg_keys.has(member_key) && !shared_env_file_by_key.has(member_key)) shared_env_file_by_key.set(member_key, shared_file)
+		}
+	}
+
+	// Collision guard: within one shared file, two members declaring the same secret NAME with a
+	// different `type` may not mean the same secret. Warn once so the author reconciles.
+	const shared_secret_seen = new Map() // `${file}\0${name}` -> { type, owner }
+	for (const member_key of [...shared_env_file_by_key.keys()].sort()) {
+		const shared_file = shared_env_file_by_key.get(member_key)
+		const env = as_object((manifest_by_key.get(member_key) || {}).env) || {}
+		for (const [var_name, spec] of Object.entries(env)) {
+			if (!spec || spec.secret !== true) continue
+			const seen_key = `${shared_file}\0${var_name}`
+			const this_type = spec.type === undefined ? null : spec.type
+			const prev = shared_secret_seen.get(seen_key)
+			if (prev) {
+				if (prev.type !== this_type) warnings.push(`Shared-env collision: secret "${var_name}" is declared by ${prev.owner} and ${member_key} with different types in ${shared_file} — verify they are the same secret.`)
+			} else {
+				shared_secret_seen.set(seen_key, { type: this_type, owner: member_key })
+			}
+		}
+	}
+
 	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))
+		const manifest = manifest_by_key.get(key)
 		if (!manifest) continue
 
 		const config_schema = as_object(manifest.config)
@@ -122,7 +165,7 @@ const configure_installed_skills = (packages, options = {}) => catch_errors('Fai
 
 		let env_file_rel = (existing_entry && existing_entry.envFile) || null
 		if (secret_names.length) {
-			env_file_rel = env_file_rel || `./secrets/${name}.env`
+			env_file_rel = env_file_rel || shared_env_file_by_key.get(key) || `./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))

package/src/skills_config/configure.test.js

@@ -127,6 +127,104 @@ describe('configure_installed_skills — interactive overrides', () => {
 	})
 })
 
+describe('configure_installed_skills — constellation sharedEnv', () => {
+	const TOKEN_ENV = { env: { CLOUDFLARE_API_TOKEN: { required: true, secret: true, description: 'CF token' } } }
+
+	it('routes a shared-env core and its dependency members to ONE derived envFile', async () => {
+		write_skill(base_dir, 'cloudflare', {
+			sharedEnv: true,
+			dependencies: { 'nicolasdao/cloudflare-deploy': '^0.1.0', 'nicolasdao/cloudflare-config': '^0.1.0' },
+			...TOKEN_ENV
+		})
+		write_skill(base_dir, 'cloudflare-deploy', TOKEN_ENV)
+		write_skill(base_dir, 'cloudflare-config', TOKEN_ENV)
+
+		const [err] = await configure_installed_skills(
+			[{ skill: 'nicolasdao/cloudflare' }, { skill: 'nicolasdao/cloudflare-deploy' }, { skill: 'nicolasdao/cloudflare-config' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+
+		const cfg = JSON.parse(read(path.join(config_root, 'skills-config.json')))
+		assert.strictEqual(cfg['nicolasdao/cloudflare'].envFile, './secrets/cloudflare.env')
+		assert.strictEqual(cfg['nicolasdao/cloudflare-deploy'].envFile, './secrets/cloudflare.env')
+		assert.strictEqual(cfg['nicolasdao/cloudflare-config'].envFile, './secrets/cloudflare.env')
+
+		// exactly ONE shared secrets file — the redundant per-member files are not created
+		assert.ok(fs.existsSync(path.join(config_root, 'secrets', 'cloudflare.env')))
+		assert.ok(!fs.existsSync(path.join(config_root, 'secrets', 'cloudflare-deploy.env')))
+		assert.ok(!fs.existsSync(path.join(config_root, 'secrets', 'cloudflare-config.env')))
+
+		// the shared file carries the token name exactly once
+		const env_content = read(path.join(config_root, 'secrets', 'cloudflare.env'))
+		assert.strictEqual((env_content.match(/CLOUDFLARE_API_TOKEN=/g) || []).length, 1)
+	})
+
+	it('respects a consumer-set envFile over the shared default', async () => {
+		fs.writeFileSync(
+			path.join(config_root, 'skills-config.json'),
+			JSON.stringify({ 'nicolasdao/cloudflare-deploy': { envFile: './my-secrets/cf.env' } }, null, '\t')
+		)
+		write_skill(base_dir, 'cloudflare', { sharedEnv: true, dependencies: { 'nicolasdao/cloudflare-deploy': '^0.1.0' }, ...TOKEN_ENV })
+		write_skill(base_dir, 'cloudflare-deploy', TOKEN_ENV)
+
+		const [err] = await configure_installed_skills(
+			[{ skill: 'nicolasdao/cloudflare' }, { skill: 'nicolasdao/cloudflare-deploy' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+
+		const cfg = JSON.parse(read(path.join(config_root, 'skills-config.json')))
+		assert.strictEqual(cfg['nicolasdao/cloudflare-deploy'].envFile, './my-secrets/cf.env') // consumer override wins
+		assert.strictEqual(cfg['nicolasdao/cloudflare'].envFile, './secrets/cloudflare.env')
+	})
+
+	it('does NOT share when the core lacks sharedEnv (regression: per-skill files)', async () => {
+		write_skill(base_dir, 'cloudflare', { dependencies: { 'nicolasdao/cloudflare-deploy': '^0.1.0' }, ...TOKEN_ENV })
+		write_skill(base_dir, 'cloudflare-deploy', TOKEN_ENV)
+
+		const [err] = await configure_installed_skills(
+			[{ skill: 'nicolasdao/cloudflare' }, { skill: 'nicolasdao/cloudflare-deploy' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+
+		const cfg = JSON.parse(read(path.join(config_root, 'skills-config.json')))
+		assert.strictEqual(cfg['nicolasdao/cloudflare'].envFile, './secrets/cloudflare.env')
+		assert.strictEqual(cfg['nicolasdao/cloudflare-deploy'].envFile, './secrets/cloudflare-deploy.env')
+	})
+
+	it('does NOT share for a kit (kit members keep isolated secrets)', async () => {
+		write_skill(base_dir, '_kit-x', { type: 'kit', sharedEnv: true, dependencies: { 'acme/a': '^1.0.0' } })
+		write_skill(base_dir, 'a', TOKEN_ENV)
+
+		const [err] = await configure_installed_skills(
+			[{ skill: 'acme/_kit-x' }, { skill: 'acme/a' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+
+		const cfg = JSON.parse(read(path.join(config_root, 'skills-config.json')))
+		assert.strictEqual(cfg['acme/a'].envFile, './secrets/a.env') // NOT the kit's file
+	})
+
+	it('warns when two shared members declare the same secret with a different type', async () => {
+		write_skill(base_dir, 'core', {
+			sharedEnv: true,
+			dependencies: { 'acme/sat': '^1.0.0' },
+			env: { TOK: { required: true, secret: true, type: 'string' } }
+		})
+		write_skill(base_dir, 'sat', { env: { TOK: { required: true, secret: true, type: 'integer' } } })
+
+		const [err, result] = await configure_installed_skills(
+			[{ skill: 'acme/core' }, { skill: 'acme/sat' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+		assert.ok(result.warnings.some(w => /TOK/.test(w) && /shared/i.test(w)), 'a same-name/different-type shared secret must warn')
+	})
+})
+
 describe('configure_installed_skills — reconcile on update (only_required)', () => {
 	it('re-prompts exactly the newly-required field and leaves existing values untouched', async () => {
 		// v1: only `channel` config. Consumer sets it.

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

package/src/validation/skill_json_rules.js

@@ -277,6 +277,40 @@ const validate_env = (manifest) => {
 	return results
 }
 
+// sharedEnv (constellation-only). When a non-kit skill sets `sharedEnv: true`, the CLI points the
+// skill AND its skill-dependencies at one shared `.env` on install — a constellation shares a
+// config namespace, so its members should not each scaffold an identical secrets file. Forbidden
+// on kits: a kit bundles unrelated skills, which keep isolated secrets. A no-op without deps.
+const validate_shared_env = (manifest) => {
+	const results = []
+	if (manifest.sharedEnv === undefined) return results
+
+	if (typeof manifest.sharedEnv !== 'boolean') {
+		results.push(result('sharedEnv', 'type', 'error', 'sharedEnv must be a boolean'))
+		return results
+	}
+
+	if (manifest.sharedEnv !== true) {
+		results.push(result('sharedEnv', 'valid', 'pass', 'sharedEnv is false'))
+		return results
+	}
+
+	if (manifest.type === SKILL_TYPES.KIT) {
+		results.push(result('sharedEnv', 'kit_forbidden', 'error', 'sharedEnv is not allowed on a kit — kit members bundle unrelated skills and keep isolated secrets. Use sharedEnv only on a constellation core.'))
+		return results
+	}
+
+	const deps = manifest.dependencies
+	const dep_count = deps && typeof deps === 'object' && !Array.isArray(deps) ? Object.keys(deps).length : 0
+	if (dep_count === 0) {
+		results.push(result('sharedEnv', 'no_dependencies', 'warning', 'sharedEnv: true has no effect without dependencies — it shares one .env across the skill and its skill-dependencies (a constellation).'))
+		return results
+	}
+
+	results.push(result('sharedEnv', 'valid', 'pass', 'sharedEnv: true — the skill and its dependencies will share one .env on install'))
+	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)
@@ -308,6 +342,7 @@ const validate_skill_json = (skill_dir) => catch_errors('Failed to validate skil
 	results.push(...validate_system_dependencies(manifest))
 	results.push(...validate_config(manifest))
 	results.push(...validate_env(manifest))
+	results.push(...validate_shared_env(manifest))
 
 	const is_kit = manifest.type === SKILL_TYPES.KIT
 	if (is_kit) {

package/src/validation/skill_json_rules.test.js

@@ -69,6 +69,40 @@ describe('validate_skill_json — name', () => {
 	})
 })
 
+describe('validate_skill_json — sharedEnv', () => {
+	it('errors when sharedEnv is not a boolean', async () => {
+		write_json(tmp, { name: 'core', version: '1.0.0', sharedEnv: 'yes', dependencies: { 'a/b': '^1.0.0' } })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'sharedEnv' && r.rule === 'type')
+		assert.strictEqual(check.severity, 'error')
+	})
+
+	it('errors when a kit declares sharedEnv: true', async () => {
+		write_json(tmp, { name: '_kit-x', version: '1.0.0', type: 'kit', sharedEnv: true, dependencies: { 'a/b': '^1.0.0' } })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'sharedEnv' && r.rule === 'kit_forbidden')
+		assert.strictEqual(check.severity, 'error')
+	})
+
+	it('warns when sharedEnv: true has no dependencies', async () => {
+		write_json(tmp, { name: 'core', version: '1.0.0', sharedEnv: true })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'sharedEnv' && r.rule === 'no_dependencies')
+		assert.strictEqual(check.severity, 'warning')
+	})
+
+	it('passes for sharedEnv: true with dependencies', async () => {
+		write_json(tmp, { name: 'core', version: '1.0.0', sharedEnv: true, dependencies: { 'a/b': '^1.0.0' } })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'sharedEnv' && r.rule === 'valid')
+		assert.strictEqual(check.severity, 'pass')
+	})
+})
+
 describe('validate_skill_json — version', () => {
 	it('errors when version is missing', async () => {
 		write_json(tmp, { name: 'my-skill' })