happyskills 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.26.0] - 2026-04-01
+
+### Added
+- Add `people` command with subcommands: `list`, `add`, `remove`, `role`, `search` for workspace membership management
+- Add `groups` command (alias: `grp`) with subcommands: `list`, `create`, `delete`, `show`, `add`, `remove`, `default` for workspace group management
+- Add `access` command with subcommands: `list`, `grant`, `revoke`, `set` for group-level skill permission management
+- Add `confirm_prompt` utility for interactive confirmation on destructive operations (`people remove`, `groups delete`)
+
+### Changed
+- Make `convert` authentication optional — when not logged in, `--workspace <slug>` is required and the registry conflict check is skipped
+
+## [0.25.0] - 2026-03-30
+
+### Added
+- Add `--agents` flag to `init` and `convert` commands for explicit agent targeting, matching `install` behavior
+- Add `recommendations` array to `validate` description max_length error — provides a 4-step procedure (audit, lossless compression, lossy compression, verify) for safely shortening descriptions without breaking auto-invocation triggers
+
+### Fixed
+- Fix `init` not creating symlinks to secondary agents (Cursor, Windsurf, Codex, etc.) — newly scaffolded skills now use the same multi-agent linking as `install`
+- Fix `convert` not creating symlinks to secondary agents — converted skills now get symlinked to all detected agents
+
 ## [0.24.0] - 2026-03-30
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.24.0",
+	"version": "0.26.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/api/group_permissions.js

@@ -0,0 +1,32 @@
+const { error: { catch_errors } } = require('puffy-core')
+const client = require('./client')
+
+const repo_path = (owner, name) => `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/groups`
+
+const list_by_skill = (owner, name) => catch_errors('List skill groups failed', async () => {
+	const [errors, data] = await client.get(repo_path(owner, name))
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const grant = (owner, name, body) => catch_errors('Grant access failed', async () => {
+	const [errors, data] = await client.post(repo_path(owner, name), body)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const revoke = (owner, name, group_id, revoke_dependencies = true) => catch_errors('Revoke access failed', async () => {
+	const path = `${repo_path(owner, name)}/${encodeURIComponent(group_id)}?revoke_dependencies=${revoke_dependencies}`
+	const [errors, data] = await client.del(path)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const update = (owner, name, group_id, permission) => catch_errors('Update permission failed', async () => {
+	const path = `${repo_path(owner, name)}/${encodeURIComponent(group_id)}`
+	const [errors, data] = await client.patch(path, { permission })
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+module.exports = { list_by_skill, grant, revoke, update }

package/src/api/groups.js

@@ -0,0 +1,58 @@
+const { error: { catch_errors } } = require('puffy-core')
+const client = require('./client')
+
+const ws_path = (slug) => `/workspaces/${encodeURIComponent(slug)}/groups`
+const grp_path = (slug, name) => `${ws_path(slug)}/${encodeURIComponent(name)}`
+
+const list_groups = (slug) => catch_errors('List groups failed', async () => {
+	const [errors, data] = await client.get(ws_path(slug))
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const create_group = (slug, name, description, is_default = false) => catch_errors('Create group failed', async () => {
+	const body = { name }
+	if (description) body.description = description
+	if (is_default) body.is_default = true
+	const [errors, data] = await client.post(ws_path(slug), body)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const delete_group = (slug, name) => catch_errors('Delete group failed', async () => {
+	const [errors, data] = await client.del(grp_path(slug, name))
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const show_group = (slug, name) => catch_errors('Show group failed', async () => {
+	const [errors, data] = await client.get(grp_path(slug, name))
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const add_member = (slug, group, username) => catch_errors('Add group member failed', async () => {
+	const [errors, data] = await client.post(`${grp_path(slug, group)}/members`, { username })
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const remove_member = (slug, group, username) => catch_errors('Remove group member failed', async () => {
+	const [errors, data] = await client.del(`${grp_path(slug, group)}/members/${encodeURIComponent(username)}`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const update_group = (slug, name, fields) => catch_errors('Update group failed', async () => {
+	const [errors, data] = await client.patch(grp_path(slug, name), fields)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const list_permissions = (slug, group) => catch_errors('List group permissions failed', async () => {
+	const [errors, data] = await client.get(`${grp_path(slug, group)}/permissions`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+module.exports = { list_groups, create_group, delete_group, show_group, add_member, remove_member, update_group, list_permissions }

package/src/api/members.js

@@ -0,0 +1,28 @@
+const { error: { catch_errors } } = require('puffy-core')
+const client = require('./client')
+
+const list_members = (slug) => catch_errors('List members failed', async () => {
+	const [errors, data] = await client.get(`/workspaces/${encodeURIComponent(slug)}/members`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const add_member = (slug, username, role = 'member') => catch_errors('Add member failed', async () => {
+	const [errors, data] = await client.post(`/workspaces/${encodeURIComponent(slug)}/members`, { username, role })
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const remove_member = (slug, username) => catch_errors('Remove member failed', async () => {
+	const [errors, data] = await client.del(`/workspaces/${encodeURIComponent(slug)}/members/${encodeURIComponent(username)}`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const update_role = (slug, username, role) => catch_errors('Update role failed', async () => {
+	const [errors, data] = await client.patch(`/workspaces/${encodeURIComponent(slug)}/members/${encodeURIComponent(username)}`, { role })
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+module.exports = { list_members, add_member, remove_member, update_role }

package/src/api/users.js

@@ -0,0 +1,11 @@
+const { error: { catch_errors } } = require('puffy-core')
+const client = require('./client')
+
+const search_users = (query, limit = 10) => catch_errors('Search users failed', async () => {
+	const params = new URLSearchParams({ q: query, limit: String(limit), exclude_self: 'true' })
+	const [errors, data] = await client.get(`/users/search?${params}`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+module.exports = { search_users }

package/src/commands/access.js

@@ -0,0 +1,212 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { require_token } = require('../auth/token_store')
+const groups_api = require('../api/groups')
+const perms_api = require('../api/group_permissions')
+const { print_help, print_json, print_table, print_success, print_warn } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills access <subcommand> [options]
+
+Manage group-level skill access.
+
+Subcommands:
+  list                       List access grants (by group or by skill)
+  grant                      Grant a group access to a skill
+  revoke                     Revoke a group's access to a skill
+  set                        Change a group's permission on a skill
+
+Options:
+  -w, --workspace <slug>     Workspace slug (required for --group list mode)
+  --group <group>            Group name
+  --skill <owner/name>       Skill identifier (owner/name)
+  --permission <perm>        Permission: read, write, or admin
+  --confirm                  Confirm dependency cascade for grant
+  --dep-permission <perm>    Permission for dependencies: read or write
+  --keep-deps                Keep dependency grants on revoke
+  --json                     Output as JSON
+
+Examples:
+  happyskills access list -w acme --group engineering
+  happyskills access list --skill acme/deploy-aws
+  happyskills access grant --skill acme/deploy-aws --group engineering --permission read
+  happyskills access revoke --skill acme/deploy-aws --group engineering
+  happyskills access set --skill acme/deploy-aws --group engineering --permission write`
+
+const parse_skill = (skill_flag) => {
+	if (!skill_flag) throw new UsageError('--skill <owner/name> is required')
+	const parts = skill_flag.split('/')
+	if (parts.length !== 2 || !parts[0] || !parts[1]) throw new UsageError('--skill must be in owner/name format')
+	return { owner: parts[0], name: parts[1] }
+}
+
+const resolve_group_id = (groups, group_name) => {
+	const match = groups.find(g => g.group_name === group_name || g.name === group_name)
+	if (!match) throw new UsageError(`Group "${group_name}" not found in skill's access list`)
+	return match.id || match.group_id
+}
+
+const list_access = (args) => catch_errors('List access failed', async () => {
+	const group_flag = args.flags.group
+	const skill_flag = args.flags.skill
+
+	if (!group_flag && !skill_flag) {
+		throw new UsageError('Either --group or --skill is required. Run happyskills access list --help')
+	}
+
+	if (group_flag) {
+		const workspace = args.flags.workspace
+		if (!workspace) throw new UsageError('--workspace (-w) is required when using --group')
+
+		const [errors, permissions] = await groups_api.list_permissions(workspace, group_flag)
+		if (errors) throw errors[errors.length - 1]
+
+		if (args.flags.json) {
+			print_json({ data: permissions })
+			return
+		}
+
+		if (!permissions || permissions.length === 0) {
+			console.log('No skill access grants found.')
+			return
+		}
+
+		print_table(
+			['Skill', 'Permission', 'Direct'],
+			permissions.map(p => [p.skill || `${p.owner}/${p.name}`, p.permission, p.is_direct !== false ? 'yes' : 'no'])
+		)
+		return
+	}
+
+	const { owner, name } = parse_skill(skill_flag)
+	const [errors, groups] = await perms_api.list_by_skill(owner, name)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data: groups })
+		return
+	}
+
+	if (!groups || groups.length === 0) {
+		console.log('No group access grants found.')
+		return
+	}
+
+	print_table(
+		['Group', 'Permission', 'Direct'],
+		groups.map(g => [g.group_name || g.name, g.permission, g.is_direct !== false ? 'yes' : 'no'])
+	)
+})
+
+const grant_access = (args) => catch_errors('Grant access failed', async () => {
+	const { owner, name } = parse_skill(args.flags.skill)
+	const group_name = args.flags.group
+	if (!group_name) throw new UsageError('--group is required')
+	const permission = args.flags.permission
+	if (!permission) throw new UsageError('--permission is required (read, write, or admin)')
+
+	const body = { group_name, permission }
+	if (args.flags.confirm) body.confirm = true
+	if (args.flags['dep-permission']) body.dependency_permission = args.flags['dep-permission']
+
+	const [errors, data] = await perms_api.grant(owner, name, body)
+	if (errors) throw errors[errors.length - 1]
+
+	if (data && data.requires_confirmation) {
+		if (args.flags.json) {
+			print_json({ data })
+			return
+		}
+
+		print_warn('This skill has private dependencies that will also receive access:')
+		const deps = data.dependencies || []
+		for (const dep of deps) {
+			console.log(`  - ${dep.owner}/${dep.name}`)
+		}
+		console.log()
+		console.log('Re-run with --confirm to proceed, or add --dep-permission <read|write> to set dependency permission level.')
+		return
+	}
+
+	if (args.flags.json) {
+		print_json({ data })
+		return
+	}
+
+	print_success(`Granted ${group_name} ${permission} access to ${owner}/${name}`)
+	const dep_count = data?.dependency_grants?.length || 0
+	if (dep_count > 0) {
+		console.log(`  Also granted access to ${dep_count} dependenc${dep_count === 1 ? 'y' : 'ies'}`)
+	}
+})
+
+const revoke_access = (args) => catch_errors('Revoke access failed', async () => {
+	const { owner, name } = parse_skill(args.flags.skill)
+	const group_name = args.flags.group
+	if (!group_name) throw new UsageError('--group is required')
+
+	const revoke_deps = args.flags['keep-deps'] !== true
+
+	// Resolve group name to group ID
+	const [list_errors, groups] = await perms_api.list_by_skill(owner, name)
+	if (list_errors) throw list_errors[list_errors.length - 1]
+
+	const group_id = resolve_group_id(groups, group_name)
+
+	const [errors, data] = await perms_api.revoke(owner, name, group_id, revoke_deps)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data })
+		return
+	}
+
+	print_success(`Revoked ${group_name} access to ${owner}/${name}`)
+	const dep_count = data?.dependencies_revoked || 0
+	if (dep_count > 0) {
+		console.log(`  Also revoked access to ${dep_count} dependenc${dep_count === 1 ? 'y' : 'ies'}`)
+	}
+})
+
+const set_permission = (args) => catch_errors('Set permission failed', async () => {
+	const { owner, name } = parse_skill(args.flags.skill)
+	const group_name = args.flags.group
+	if (!group_name) throw new UsageError('--group is required')
+	const permission = args.flags.permission
+	if (!permission) throw new UsageError('--permission is required (read, write, or admin)')
+
+	// Resolve group name to group ID
+	const [list_errors, groups] = await perms_api.list_by_skill(owner, name)
+	if (list_errors) throw list_errors[list_errors.length - 1]
+
+	const group_id = resolve_group_id(groups, group_name)
+
+	const [errors, data] = await perms_api.update(owner, name, group_id, permission)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data })
+		return
+	}
+
+	print_success(`Changed ${group_name} permission on ${owner}/${name} to ${permission}`)
+})
+
+const run = (args) => catch_errors('Access command failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	await require_token()
+
+	const sub = args._[0]
+	if (!sub || sub === 'list') return list_access(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+	if (sub === 'grant') return grant_access(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+	if (sub === 'revoke') return revoke_access(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+	if (sub === 'set') return set_permission(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+
+	throw new UsageError(`Unknown subcommand: ${sub}. Run happyskills access --help`)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run }

package/src/commands/convert.js

@@ -2,7 +2,7 @@ const fs = require('fs')
 const path = require('path')
 const readline = require('readline')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
-const { require_token } = require('../auth/token_store')
+const { load_token } = require('../auth/token_store')
 const repos_api = require('../api/repos')
 const workspaces_api = require('../api/workspaces')
 const { parse_frontmatter } = require('../utils/skill_scanner')
@@ -13,6 +13,7 @@ const { write_lock, update_lock_skills } = require('../lock/writer')
 const { hash_directory } = require('../lock/integrity')
 const { skills_dir, find_project_root, lock_root } = require('../config/paths')
 const { file_exists } = require('../utils/fs')
+const { resolve_agents, link_to_agents } = require('../agents')
 const { create_spinner } = require('../ui/spinner')
 const { print_help, print_success, print_error, print_info, print_warn, print_label, print_json } = require('../ui/output')
 const { exit_with_error, UsageError, CliError } = require('../utils/errors')
@@ -26,10 +27,12 @@ Arguments:
   skill-name            Name of the skill in .claude/skills/
 
 Options:
-  -g, --global          Look in global skills (~/.claude/skills/)
+  -g, --global          Look in global skills (~/.agents/skills/)
   --workspace <slug>    Target workspace (if you have multiple)
   --version <ver>       Initial version (default: 1.0.0)
   --keywords <tags>     Comma-separated keywords (e.g., "deploy,aws,iac")
+  --agents <list>       Target specific agents (comma-separated, e.g., claude,cursor)
+                        Default: auto-detect. Env: HAPPYSKILLS_AGENTS
   -y, --yes             Skip confirmation prompt
 
 Examples:
@@ -69,7 +72,8 @@ const run = (args) => catch_errors('Convert failed', async () => {
 		throw new UsageError('Please specify a skill name (e.g., happyskills convert my-skill).')
 	}
 
-	await require_token()
+	const [, token_data] = await load_token()
+	const is_authenticated = !!token_data
 
 	const is_global = args.flags.global || false
 	const project_root = find_project_root()
@@ -119,22 +123,29 @@ const run = (args) => catch_errors('Convert failed', async () => {
 		}
 	}
 
-	const spinner = create_spinner('Resolving workspace...')
+	let workspace
+	if (is_authenticated) {
+		const spinner = create_spinner('Resolving workspace...')
+		const [ws_err, workspaces] = await workspaces_api.list_workspaces()
+		if (ws_err) { spinner.fail('Failed to list workspaces'); throw e('Failed to list workspaces', ws_err) }
 
-	const [ws_err, workspaces] = await workspaces_api.list_workspaces()
-	if (ws_err) { spinner.fail('Failed to list workspaces'); throw e('Failed to list workspaces', ws_err) }
+		workspace = choose_workspace(workspaces, args.flags.workspace)
 
-	const workspace = choose_workspace(workspaces, args.flags.workspace)
-
-	spinner.update('Checking registry...')
-	const [repo_err] = await repos_api.get_repo(workspace.slug, skill_name, { auth: true })
-	if (!repo_err) {
+		spinner.update('Checking registry...')
+		const [repo_err] = await repos_api.get_repo(workspace.slug, skill_name, { auth: true })
+		if (!repo_err) {
+			spinner.stop()
+			throw new CliError(`Skill "${workspace.slug}/${skill_name}" already exists in the registry. Use \`happyskills publish\` instead to push a new version.`, EXIT_CODES.ERROR)
+		}
 		spinner.stop()
-		throw new CliError(`Skill "${workspace.slug}/${skill_name}" already exists in the registry. Use \`happyskills publish\` instead to push a new version.`, EXIT_CODES.ERROR)
+	} else {
+		if (!args.flags.workspace) {
+			throw new UsageError('Not logged in. Either run `happyskills login` first, or pass --workspace <slug> to convert without authentication.')
+		}
+		workspace = { slug: args.flags.workspace }
+		print_warn('Not authenticated — skipping registry conflict check. Run `happyskills login` before publishing.')
 	}
 
-	spinner.stop()
-
 	if (!args.flags.yes && !args.flags.json) {
 		console.error('')
 		console.error(`  Skill:       ${skill_name}`)
@@ -190,8 +201,25 @@ const run = (args) => catch_errors('Convert failed', async () => {
 	const [lock_err] = await write_lock(lock_dir, new_skills)
 	if (lock_err) { pub_spinner.fail('Failed to write lock file'); throw e('Lock write failed', lock_err) }
 
+	// Link to detected agents (non-fatal — warnings only)
+	const linked_agents = []
+	const [agents_err, agents_result] = await resolve_agents(args.flags.agents || undefined)
+	if (!agents_err && agents_result?.agents?.length > 0) {
+		pub_spinner.update(`Linking to ${agents_result.agents.length} agent(s)...`)
+		const [link_errs] = await link_to_agents(skill_dir, agents_result.agents, { global: is_global, project_root, skill_name })
+		if (link_errs) {
+			print_warn(`Warning: failed to link ${skill_name} to some agents`)
+		} else {
+			linked_agents.push(...agents_result.agents.map(a => a.id))
+		}
+	}
+
 	pub_spinner.succeed(`Converted ${full_name}@${merged_version}`)
 
+	if (linked_agents.length > 0) {
+		print_info(`Linked to: ${agents_result.agents.map(a => a.display_name).join(', ')}`)
+	}
+
 	if (args.flags.json) {
 		const json_data = {
 			skill: full_name,
@@ -199,6 +227,7 @@ const run = (args) => catch_errors('Convert failed', async () => {
 			workspace: workspace.slug,
 			description: merged_description || ''
 		}
+		if (linked_agents.length > 0) json_data.linked_agents = linked_agents
 		if (frontmatter_warnings.length > 0) json_data.warnings = frontmatter_warnings
 		print_json({ data: json_data })
 		return

package/src/commands/groups.js

@@ -0,0 +1,219 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { require_token } = require('../auth/token_store')
+const groups_api = require('../api/groups')
+const { print_help, print_json, print_table, print_success, print_label, print_hint } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills groups <subcommand> [options]
+
+Manage workspace groups and group membership.
+
+Subcommands:
+  list                       List workspace groups
+  create <name>              Create a group
+  delete <name>              Delete a group
+  show <name>                Show group detail and members
+  add <group> <username>     Add a person to a group
+  remove <group> <username>  Remove a person from a group
+  default <name> --on|--off  Toggle default group status
+
+Options:
+  -w, --workspace <slug>     Workspace slug (required)
+  --description <desc>       Description for create
+  --default                  Mark as default group on create
+  --on                       Enable default status
+  --off                      Disable default status
+  -y, --yes                  Skip confirmation prompts
+  --json                     Output as JSON
+
+Aliases:
+  grp                        Alias for groups
+
+Examples:
+  happyskills groups list -w acme
+  happyskills groups create -w acme engineering --description "Core team"
+  happyskills groups show -w acme engineering
+  happyskills groups add -w acme engineering alice
+  happyskills groups delete -w acme engineering --yes
+  happyskills grp default -w acme engineering --on`
+
+const require_workspace = (args) => {
+	const workspace = args.flags.workspace
+	if (!workspace) throw new UsageError('--workspace (-w) is required')
+	return workspace
+}
+
+const list_groups_cmd = (args) => catch_errors('List groups failed', async () => {
+	const workspace = require_workspace(args)
+	const [errors, groups] = await groups_api.list_groups(workspace)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data: groups })
+		return
+	}
+
+	if (!groups || groups.length === 0) {
+		console.log('No groups found.')
+		return
+	}
+
+	print_table(
+		['Name', 'Description', 'Members', 'Default'],
+		groups.map(g => [g.name, g.description || '', g.member_count ?? '', g.is_default ? 'yes' : 'no'])
+	)
+})
+
+const create_group = (args) => catch_errors('Create group failed', async () => {
+	const workspace = require_workspace(args)
+	const name = args._[1]
+	if (!name) throw new UsageError('Group name is required. Usage: happyskills groups create -w <workspace> <name>')
+
+	const description = args.flags.description || null
+	const is_default = args.flags.default === true
+
+	const [errors, data] = await groups_api.create_group(workspace, name, description, is_default)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data })
+		return
+	}
+
+	print_success(`Created group ${name}`)
+	print_hint(`Run happyskills groups show -w ${workspace} ${name} to see group details`)
+})
+
+const delete_group = (args) => catch_errors('Delete group failed', async () => {
+	const workspace = require_workspace(args)
+	const name = args._[1]
+	if (!name) throw new UsageError('Group name is required. Usage: happyskills groups delete -w <workspace> <name>')
+
+	if (!args.flags.yes) {
+		const { confirm_prompt } = require('../utils/prompt')
+		const confirmed = await confirm_prompt(`Delete group ${name}? This will also remove all skill access grants.`)
+		if (!confirmed) {
+			console.log('Cancelled.')
+			return
+		}
+	}
+
+	const [errors, data] = await groups_api.delete_group(workspace, name)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data })
+		return
+	}
+
+	print_success(`Deleted group ${name}`)
+})
+
+const show_group = (args) => catch_errors('Show group failed', async () => {
+	const workspace = require_workspace(args)
+	const name = args._[1]
+	if (!name) throw new UsageError('Group name is required. Usage: happyskills groups show -w <workspace> <name>')
+
+	const [errors, group] = await groups_api.show_group(workspace, name)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data: group })
+		return
+	}
+
+	print_label('Group', group.name)
+	print_label('Description', group.description || '(none)')
+	print_label('Default', group.is_default ? 'yes' : 'no')
+
+	const members = group.members || []
+	console.log()
+	print_label(`Members (${members.length})`, '')
+	if (members.length === 0) {
+		console.log('  (none)')
+	} else {
+		for (const m of members) {
+			console.log(`  ${m.username}    ${m.email || ''}`)
+		}
+	}
+})
+
+const add_member = (args) => catch_errors('Add group member failed', async () => {
+	const workspace = require_workspace(args)
+	const group = args._[1]
+	const username = args._[2]
+	if (!group || !username) throw new UsageError('Group and username are required. Usage: happyskills groups add -w <workspace> <group> <username>')
+
+	const [errors, data] = await groups_api.add_member(workspace, group, username)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data })
+		return
+	}
+
+	print_success(`Added ${username} to group ${group}`)
+	print_hint(`Run happyskills groups show -w ${workspace} ${group} to see group details`)
+})
+
+const remove_member = (args) => catch_errors('Remove group member failed', async () => {
+	const workspace = require_workspace(args)
+	const group = args._[1]
+	const username = args._[2]
+	if (!group || !username) throw new UsageError('Group and username are required. Usage: happyskills groups remove -w <workspace> <group> <username>')
+
+	const [errors, data] = await groups_api.remove_member(workspace, group, username)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data })
+		return
+	}
+
+	print_success(`Removed ${username} from group ${group}`)
+})
+
+const toggle_default = (args) => catch_errors('Toggle default failed', async () => {
+	const workspace = require_workspace(args)
+	const name = args._[1]
+	if (!name) throw new UsageError('Group name is required. Usage: happyskills groups default -w <workspace> <name> --on|--off')
+
+	const on = args.flags.on === true
+	const off = args.flags.off === true
+	if (!on && !off) throw new UsageError('Either --on or --off is required. Usage: happyskills groups default -w <workspace> <name> --on|--off')
+	if (on && off) throw new UsageError('Cannot use both --on and --off')
+
+	const is_default = on
+	const [errors, data] = await groups_api.update_group(workspace, name, { is_default })
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data })
+		return
+	}
+
+	print_success(is_default ? `${name} is now a default group` : `${name} is no longer a default group`)
+})
+
+const run = (args) => catch_errors('Groups command failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	await require_token()
+
+	const sub = args._[0]
+	if (!sub || sub === 'list') return list_groups_cmd(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+	if (sub === 'create') return create_group(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+	if (sub === 'delete') return delete_group(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+	if (sub === 'show') return show_group(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+	if (sub === 'add') return add_member(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+	if (sub === 'remove') return remove_member(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+	if (sub === 'default') return toggle_default(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+
+	throw new UsageError(`Unknown subcommand: ${sub}. Run happyskills groups --help`)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run }

package/src/commands/init.js

@@ -2,26 +2,29 @@ const path = require('path')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { write_manifest } = require('../manifest/writer')
 const { write_file, file_exists, ensure_dir } = require('../utils/fs')
-const { print_success, print_error, print_help, print_hint, print_json, code } = require('../ui/output')
+const { print_success, print_error, print_help, print_hint, print_json, print_info, print_warn, code } = require('../ui/output')
 const { exit_with_error, CliError, UsageError } = require('../utils/errors')
 const { SKILL_JSON, SKILL_MD, EXIT_CODES, SKILL_TYPES, KIT_PREFIX } = require('../constants')
 const { find_project_root, skills_dir } = require('../config/paths')
+const { resolve_agents, link_to_agents } = require('../agents')
 
 const HELP_TEXT = `Usage: happyskills init <name> [options]
 
-Scaffold a new skill in .claude/skills/<name>/.
+Scaffold a new skill in .agents/skills/<name>/.
 
 Creates:
-  .claude/skills/<name>/skill.json    Skill manifest (name, version, deps)
-  .claude/skills/<name>/SKILL.md      Skill instructions for AI agents
+  .agents/skills/<name>/skill.json    Skill manifest (name, version, deps)
+  .agents/skills/<name>/SKILL.md      Skill instructions for AI agents
 
 Arguments:
   name          Skill name (required, e.g., my-deploy-skill)
 
 Options:
-  -g, --global  Create in global skills (~/.claude/skills/)
-  --kit         Initialize as a kit (collection of skills)
-  --json        Output as JSON
+  -g, --global    Create in global skills (~/.agents/skills/)
+  --kit           Initialize as a kit (collection of skills)
+  --agents <list> Target specific agents (comma-separated, e.g., claude,cursor)
+                  Default: auto-detect. Env: HAPPYSKILLS_AGENTS
+  --json          Output as JSON
 
 Examples:
   happyskills init my-deploy-skill
@@ -104,14 +107,31 @@ const run = (args) => catch_errors('Init failed', async () => {
 
 	const label = is_kit ? 'kit' : 'skill'
 
+	// Link to detected agents (non-fatal — warnings only)
+	const linked_agents = []
+	const [agents_err, agents_result] = await resolve_agents(args.flags.agents || undefined)
+	if (!agents_err && agents_result?.agents?.length > 0) {
+		const [link_errs] = await link_to_agents(dir, agents_result.agents, { global: is_global, project_root, skill_name: final_name })
+		if (link_errs) {
+			print_warn(`Warning: failed to link ${final_name} to some agents`)
+		} else {
+			linked_agents.push(...agents_result.agents.map(a => a.id))
+		}
+	}
+
 	if (args.flags.json) {
-		print_json({ data: { name: final_name, type: is_kit ? SKILL_TYPES.KIT : SKILL_TYPES.SKILL, files_created, directory: dir } })
+		const data = { name: final_name, type: is_kit ? SKILL_TYPES.KIT : SKILL_TYPES.SKILL, files_created, directory: dir }
+		if (linked_agents.length > 0) data.linked_agents = linked_agents
+		print_json({ data })
 		return
 	}
 
 	print_success(`Initialized ${label} "${final_name}" at ${dir}`)
 	console.log(`  ${SKILL_JSON}  — manifest`)
 	console.log(`  ${SKILL_MD}    — ${is_kit ? 'kit description' : 'instructions'}`)
+	if (linked_agents.length > 0) {
+		print_info(`Linked to: ${agents_result.agents.map(a => a.display_name).join(', ')}`)
+	}
 	console.log()
 	print_hint(`Edit these files, then run ${code('happyskills publish')} to share.`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })

package/src/commands/people.js

@@ -0,0 +1,162 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { require_token } = require('../auth/token_store')
+const members_api = require('../api/members')
+const users_api = require('../api/users')
+const { print_help, print_json, print_table, print_success, print_hint } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills people <subcommand> [options]
+
+Manage workspace membership.
+
+Subcommands:
+  list                       List workspace members
+  add <username>             Add a person to the workspace
+  remove <username>          Remove a person from the workspace
+  role <username> <role>     Change a person's role
+  search <query>             Search for users
+
+Options:
+  -w, --workspace <slug>     Workspace slug (required for list, add, remove, role)
+  --role <role>              Role for add: owner, admin, member, viewer (default: member)
+  --limit <n>               Max search results (default: 10)
+  --json                    Output as JSON
+
+Examples:
+  happyskills people list -w acme
+  happyskills people add -w acme alice --role admin
+  happyskills people remove -w acme alice
+  happyskills people role -w acme alice admin
+  happyskills people search alice`
+
+const require_workspace = (args) => {
+	const workspace = args.flags.workspace
+	if (!workspace) throw new UsageError('--workspace (-w) is required')
+	return workspace
+}
+
+const list_people = (args) => catch_errors('List people failed', async () => {
+	const workspace = require_workspace(args)
+	const [errors, members] = await members_api.list_members(workspace)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data: members })
+		return
+	}
+
+	if (!members || members.length === 0) {
+		console.log('No members found.')
+		return
+	}
+
+	print_table(
+		['Username', 'Email', 'Role', 'Joined'],
+		members.map(m => [m.username, m.email || '', m.role, m.created_at ? m.created_at.slice(0, 10) : ''])
+	)
+})
+
+const add_person = (args) => catch_errors('Add person failed', async () => {
+	const workspace = require_workspace(args)
+	const username = args._[1]
+	if (!username) throw new UsageError('Username is required. Usage: happyskills people add -w <workspace> <username>')
+	const role = args.flags.role || 'member'
+
+	const [errors, data] = await members_api.add_member(workspace, username, role)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data })
+		return
+	}
+
+	print_success(`Added ${username} to ${workspace} as ${role}`)
+	print_hint(`Run happyskills people list -w ${workspace} to see all members`)
+})
+
+const remove_person = (args) => catch_errors('Remove person failed', async () => {
+	const workspace = require_workspace(args)
+	const username = args._[1]
+	if (!username) throw new UsageError('Username is required. Usage: happyskills people remove -w <workspace> <username>')
+
+	if (!args.flags.yes) {
+		const { confirm_prompt } = require('../utils/prompt')
+		const confirmed = await confirm_prompt(`Remove ${username} from ${workspace}?`)
+		if (!confirmed) {
+			console.log('Cancelled.')
+			return
+		}
+	}
+
+	const [errors, data] = await members_api.remove_member(workspace, username)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data })
+		return
+	}
+
+	print_success(`Removed ${username} from ${workspace}`)
+})
+
+const change_role = (args) => catch_errors('Change role failed', async () => {
+	const workspace = require_workspace(args)
+	const username = args._[1]
+	const role = args._[2]
+	if (!username || !role) throw new UsageError('Username and role are required. Usage: happyskills people role -w <workspace> <username> <role>')
+
+	const [errors, data] = await members_api.update_role(workspace, username, role)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data })
+		return
+	}
+
+	print_success(`Changed ${username} role to ${role}`)
+})
+
+const search_people = (args) => catch_errors('Search users failed', async () => {
+	const query = args._[1]
+	if (!query) throw new UsageError('Search query is required. Usage: happyskills people search <query>')
+	const limit = args.flags.limit ? parseInt(args.flags.limit, 10) : 10
+
+	const [errors, users] = await users_api.search_users(query, limit)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data: users })
+		return
+	}
+
+	if (!users || users.length === 0) {
+		console.log('No users found.')
+		return
+	}
+
+	print_table(
+		['Username', 'Email', 'Name'],
+		users.map(u => [u.username, u.email || '', u.name || ''])
+	)
+})
+
+const run = (args) => catch_errors('People command failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	await require_token()
+
+	const sub = args._[0]
+	if (!sub || sub === 'list') return list_people(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+	if (sub === 'add') return add_person(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+	if (sub === 'remove') return remove_person(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+	if (sub === 'role') return change_role(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+	if (sub === 'search') return search_people(args).then(([errors]) => { if (errors) throw errors[errors.length - 1] })
+
+	throw new UsageError(`Unknown subcommand: ${sub}. Run happyskills people --help`)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run }

package/src/constants.js

@@ -37,7 +37,8 @@ const COMMAND_ALIASES = {
 	pub: 'publish',
 	v: 'validate',
 	del: 'delete',
-	vis: 'visibility'
+	vis: 'visibility',
+	grp: 'groups'
 }
 
 const COMMANDS = [
@@ -64,7 +65,10 @@ const COMMANDS = [
 	'setup',
 	'validate',
 	'self-update',
-	'config'
+	'config',
+	'people',
+	'groups',
+	'access'
 ]
 
 module.exports = {

package/src/index.js

@@ -102,6 +102,9 @@ Commands:
   fork <owner/skill>       Fork a skill to your workspace
   setup                    Install the HappySkills CLI skill globally
   self-update              Upgrade happyskills CLI to latest version
+  people <sub>             Manage workspace members (list, add, remove, role, search)
+  groups <sub>             Manage workspace groups (list, create, delete, show, add, remove, default)
+  access <sub>             Manage group skill access (list, grant, revoke, set)
   login                    Authenticate with the registry
   logout                   Clear stored credentials
   whoami                   Show current user

package/src/utils/prompt.js

@@ -0,0 +1,16 @@
+const { createInterface } = require('readline')
+
+const confirm_prompt = (message) => new Promise((resolve) => {
+	if (!process.stdin.isTTY) {
+		resolve(false)
+		return
+	}
+
+	const rl = createInterface({ input: process.stdin, output: process.stderr })
+	rl.question(`${message} (y/N) `, (answer) => {
+		rl.close()
+		resolve(answer.trim().toLowerCase() === 'y')
+	})
+})
+
+module.exports = { confirm_prompt }

package/src/validation/skill_md_rules.js

@@ -74,7 +74,19 @@ const validate_description = (fm) => {
 	}
 
 	if (desc.length > 1024) {
-		results.push(result('description', 'max_length', 'error', `Description is ${desc.length} chars (max 1024)`, desc))
+		const deficit = desc.length - 1024
+		results.push({
+			...result('description', 'max_length', 'error', `Description is ${desc.length} chars (max 1024). Must reduce by ${deficit} chars.`, desc),
+			recommendations: [
+				'STEP 1 - AUDIT: Before changing anything, read the skill\'s routing table or capability list. Map each phrase in the description to the capability it triggers. Mark each phrase as: IDENTITY (describes what the skill is, usually one phrase), UNIQUE (the only phrase matching a specific capability), or REINFORCING (overlaps with another phrase\'s coverage).',
+				'STEP 2 - LOSSLESS COMPRESSION: Apply these transformations that reduce characters without changing semantic meaning: (a) Remove articles (a, an, the). (b) Remove possessives (my, your) when the subject is implied. (c) Remove filler verbs (do, does, can, have, is, am). (d) Merge parallel structures that share the same verb (e.g., \'install kit. publish kit\' becomes \'install, publish kits\') or the same object (e.g., \'find kits, search kits\' becomes \'find, search kits\'). Stop here if now under the limit.',
+				'STEP 3 - LOSSY COMPRESSION (only if still over the limit after step 2): Remove REINFORCING phrases only. When two phrases overlap semantically, remove the more general one and keep the more specific one. In synonym clusters, keep the two most commonly used verbs and remove the rest.',
+				'NEVER remove an IDENTITY phrase — it anchors the understanding of the skill\'s purpose and provides context for all other trigger phrases.',
+				'NEVER remove a UNIQUE trigger phrase — it is the only semantic path to that capability. Removing it makes that capability unreachable via auto-invocation.',
+				'NEVER rephrase a trigger in a way that changes the core verb or noun (e.g., \'how many skills installed\' must not become \'skill count\'). The original phrasing matches how users naturally speak.',
+				'STEP 4 - VERIFY: Cross-check the shortened description against the skill\'s routing table or capability list. Every documented capability must still have at least one semantically matching phrase in the description. If any capability lost coverage, restore its trigger phrase and find different savings.'
+			]
+		})
 	} else {
 		results.push(result('description', 'max_length', 'pass', `Description: ${desc.length} chars (max 1024)`))
 	}