happyskills 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-04-02
+
+### Added
+- Add agent-orphan skill detection to `list` command — scans all agent-specific skill directories (`.claude/skills/`, `.cursor/skills/`, etc.) for skills placed directly in agent folders without going through HappySkills, and reports them as `agent_orphans` in JSON output or `agent-orphan (<agent>)` source in table output
+
+## [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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.25.0",
+	"version": "0.27.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')
@@ -72,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()
@@ -122,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}`)

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

@@ -2,7 +2,8 @@ const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { skills_dir, skill_install_dir, find_project_root, lock_root } = require('../config/paths')
 const { file_exists, read_json } = require('../utils/fs')
-const { scan_skills_dir } = require('../utils/skill_scanner')
+const { scan_skills_dir, scan_agent_orphan_skills } = require('../utils/skill_scanner')
+const { AGENTS } = require('../agents/registry')
 const { print_help, print_table, print_json, print_info } = require('../ui/output')
 const { exit_with_error } = require('../utils/errors')
 const { EXIT_CODES, SKILL_JSON, SKILL_TYPES } = require('../constants')
@@ -40,9 +41,14 @@ const run = (args) => catch_errors('List failed', async () => {
 	const managed_names = new Set(managed_entries.map(([k]) => k.split('/')[1]))
 	const external_skills = (disk_skills || []).filter(s => !managed_names.has(s.name))
 
-	if (managed_entries.length === 0 && external_skills.length === 0) {
+	// Scan agent-specific dirs for skills placed directly in agent folders (not symlinked from .agents/skills/)
+	const all_known_names = new Set([...managed_names, ...external_skills.map(s => s.name)])
+	const [, agent_orphans] = await scan_agent_orphan_skills(AGENTS, is_global, project_root, all_known_names)
+	const orphan_skills = agent_orphans || []
+
+	if (managed_entries.length === 0 && external_skills.length === 0 && orphan_skills.length === 0) {
 		if (args.flags.json) {
-			print_json({ data: { skills: {}, external: [] } })
+			print_json({ data: { skills: {}, external: [], agent_orphans: [] } })
 			return
 		}
 		print_info('No skills installed.')
@@ -69,7 +75,12 @@ const run = (args) => catch_errors('List failed', async () => {
 			skills_map[name] = { version: data.version, type, source, status }
 		}
 		const external = external_skills.map(s => ({ name: s.name, description: s.description || '' }))
-		print_json({ data: { skills: skills_map, external } })
+		const agent_orphan_list = orphan_skills.map(s => ({
+			name: s.name,
+			description: s.description || '',
+			agents: s.agents
+		}))
+		print_json({ data: { skills: skills_map, external, agent_orphans: agent_orphan_list } })
 		return
 	}
 
@@ -88,6 +99,11 @@ const run = (args) => catch_errors('List failed', async () => {
 		rows.push([s.name, '-', 'external', 'installed'])
 	}
 
+	for (const s of orphan_skills) {
+		const agent_label = s.agents.map(a => a.name).join(', ')
+		rows.push([s.name, '-', `agent-orphan (${agent_label})`, 'installed'])
+	}
+
 	print_table(['Skill', 'Version', 'Source', 'Status'], rows)
 }).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/utils/skill_scanner.js

@@ -53,4 +53,80 @@ const scan_skills_dir = (base_dir) => catch_errors('Failed to scan skills direct
 	return skills
 })
 
-module.exports = { scan_skills_dir, parse_frontmatter }
+/**
+ * Scans agent-specific skill directories for skills that are NOT symlinks
+ * back to the canonical .agents/skills/ directory. These are "agent-orphan"
+ * skills — placed directly in an agent folder without going through HappySkills.
+ *
+ * @param {Array} agents - Agent definitions from the registry (AGENTS array)
+ * @param {boolean} is_global - Whether to scan global or project-level dirs
+ * @param {string} project_root - Project root path
+ * @param {Set<string>} known_names - Names already tracked (managed + external from canonical dir)
+ * @returns {[Error|null, Array<{name:string, description:string, agent_id:string, agent_name:string}>]}
+ */
+const scan_agent_orphan_skills = (agents, is_global, project_root, known_names) => catch_errors('Failed to scan agent skill directories', async () => {
+	const orphans = []
+
+	for (const agent of agents) {
+		const agent_dir = is_global
+			? path.join(require('os').homedir(), agent.global_skills_dir)
+			: path.join(project_root || process.cwd(), agent.skills_dir)
+
+		let entries
+		try {
+			entries = await fs.promises.readdir(agent_dir, { withFileTypes: true })
+		} catch {
+			continue
+		}
+
+		for (const entry of entries) {
+			if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+			if (entry.name.startsWith('.') || SKIP_ENTRIES.has(entry.name)) continue
+
+			// Skip symlinks — those are managed by HappySkills
+			if (entry.isSymbolicLink()) continue
+
+			// Skip skills already known from the canonical dir or lock file
+			if (known_names.has(entry.name)) continue
+
+			const dir = path.join(agent_dir, entry.name)
+			const skill_md_path = path.join(dir, 'SKILL.md')
+
+			let content
+			try {
+				content = await fs.promises.readFile(skill_md_path, 'utf-8')
+			} catch {
+				continue
+			}
+
+			const frontmatter = parse_frontmatter(content)
+			if (!frontmatter || !frontmatter.name) continue
+
+			orphans.push({
+				name: frontmatter.name,
+				description: frontmatter.description || '',
+				agent_id: agent.id,
+				agent_name: agent.display_name
+			})
+		}
+	}
+
+	// Deduplicate — the same skill dir name might appear in multiple agent dirs.
+	// Keep the first occurrence and collect all agent IDs.
+	const by_name = new Map()
+	for (const s of orphans) {
+		if (by_name.has(s.name)) {
+			by_name.get(s.name).agents.push({ id: s.agent_id, name: s.agent_name })
+		} else {
+			by_name.set(s.name, {
+				name: s.name,
+				description: s.description,
+				agents: [{ id: s.agent_id, name: s.agent_name }]
+			})
+		}
+	}
+
+	return [...by_name.values()]
+})
+
+module.exports = { scan_skills_dir, scan_agent_orphan_skills, parse_frontmatter }