happyskills 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-06-02
+
+### Added
+
+- **Complete the per-command surface of `happyskills schema`** (spec 260602-01). All 36 commands that previously returned a stub now export a curated `schema` — real `purpose`, `input` contract (positionals + flags actually read by the command), `output.data_shape`, and `errors[]` paired with the `next_step` each code produces. `happyskills schema --json` is now a true machine-readable manual of every command, not just a name listing.
+- **New `examples` field on the per-command schema shape** — 1–2 concrete, copy-pasteable invocation strings per command (the agent-native substitute for prose use-cases). Added to `default_schema` so any future command is valid by default.
+- **Anti-stub guard test** in `cli/src/integration/schema.test.js` — fails the build if any command returns the stub purpose, ships an empty `examples` array, or drops the `input.positional` / `input.flags` arrays. Operationalizes the "a command is not done until it has a `happyskills schema` entry" rule.
+- **Reconcile the closed envelope enums with what the CLI actually emits.** A full sweep of the CLI surfaced nine envelope labels that commands emit but were never added to the closed enums — so an agent hitting those failures received a label it could not look up. Added them to both the `cli/` and `api/` mirrors (additive, non-breaking): error codes `AUTH_FAILED` (login flow), and `COMPARE_FAILED` / `CLONE_BASE_FAILED` / `CLONE_REMOTE_FAILED` / `READ_LOCAL_FAILED` / `SWAP_FAILED` (the `pull --rebase` pipeline); next_step actions `retry_or_abandon` (recovery, `pull --rebase`), `resolve_unknown_drift` (decision, `reconcile`), and `review_publish_error` (recovery, `release`). Central default wired for `AUTH_FAILED` → `recovery/login`; `ACTION_KIND` mappings added for the new actions.
+
 ## [1.1.0] - 2026-06-02
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.1.0",
+	"version": "1.2.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/access.js

@@ -209,4 +209,44 @@ const run = (args) => catch_errors('Access command failed', async () => {
 	throw new UsageError(`Unknown subcommand: ${sub}. Run happyskills access --help`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name: 'access',
+	audience: 'account',
+	purpose: 'Manage group-level skill access: list grants, grant, revoke, or change permission on a skill for a group.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'subcommand', required: true, type: 'string', enum: ['list', 'grant', 'revoke', 'set'] }
+		],
+		flags: [
+			{ name: 'workspace', alias: 'w', type: 'string' },
+			{ name: 'group', type: 'string' },
+			{ name: 'skill', type: 'string' },
+			{ name: 'permission', type: 'string' },
+			{ name: 'confirm', type: 'boolean' },
+			{ name: 'dep-permission', type: 'string' },
+			{ name: 'keep-deps', type: 'boolean' },
+			{ name: 'json', type: 'boolean' }
+		]
+	},
+	output: {
+		data_shape: {
+			results: 'array<{ skill: string, group_name: string, permission: string, is_direct: boolean }>'
+		}
+	},
+	errors: [
+		{ code: 'AUTH_REQUIRED', next_step: { kind: 'recovery', action: 'login' } },
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } },
+		{ code: 'NOT_FOUND' },
+		{ code: 'FORBIDDEN' },
+		{ code: 'DEPENDENCY_CASCADE_REQUIRED', next_step: { kind: 'confirmation', action: 'confirm_cascade' } },
+		{ code: 'NETWORK_ERROR', next_step: { kind: 'recovery', action: 'retry' } }
+	],
+	examples: [
+		'happyskills access list -w acme --group engineering',
+		'happyskills access grant --skill acme/deploy-aws --group engineering --permission read'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/agents.js

@@ -343,4 +343,33 @@ const run = (args) => catch_errors('Agents command failed', async () => {
 	throw new UsageError(`Unknown subcommand: '${sub}'. Use add, remove, or list.`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name: 'agents',
+	audience: 'account',
+	purpose: 'Configure which agentic clients (Claude Code, Cursor, Codex, etc.) receive the skills installed in this project.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'subcommand', required: true, type: 'string', enum: ['list', 'add', 'remove'] }
+		],
+		flags: [
+			{ name: 'global', alias: 'g', type: 'boolean' },
+			{ name: 'json', type: 'boolean' }
+		]
+	},
+	output: {
+		data_shape: {
+			agents: 'array<{ id: string, display_name: string, skills_dir: string, configured: boolean, linked_skills: number }>'
+		}
+	},
+	errors: [
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } }
+	],
+	examples: [
+		'happyskills agents list',
+		'happyskills agents add codex'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/bump.js

@@ -108,4 +108,36 @@ const run = (args) => catch_errors('Bump failed', async () => {
 	print_success(`${skill_name}: ${old_version} → ${manifest.version}`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name: 'bump',
+	audience: 'consumer',
+	purpose: 'Bump the version in a skill\'s skill.json (patch, minor, major, or explicit semver) without touching the lock file.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'type', required: true, type: 'string', pattern: 'patch|minor|major|<semver>' },
+			{ name: 'skill-name', required: true, type: 'string' }
+		],
+		flags: [
+			{ name: 'json', type: 'boolean', default: false }
+		]
+	},
+	output: {
+		data_shape: {
+			skill: 'string',
+			old_version: 'string',
+			new_version: 'string',
+			bump_type: 'string'
+		}
+	},
+	errors: [
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } }
+	],
+	examples: [
+		'happyskills bump patch my-skill',
+		'happyskills bump 2.0.0 my-skill'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/changelog.js

@@ -122,4 +122,40 @@ const run = (args) => catch_errors('Changelog failed', async () => {
 	if (!content.endsWith('\n')) process.stdout.write('\n')
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run, find_changelog_entry, synthesize_from_refs, normalize_ref }
+const schema = {
+	name:     'changelog',
+	audience: 'consumer',
+	purpose:  'Print a skill\'s CHANGELOG.md at the latest (or specified) version, or synthesize one from registry release messages if none exists.',
+	mutation: false,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'skill', required: true, type: 'string', pattern: '<owner>/<name>' },
+		],
+		flags: [
+			{ name: 'version', type: 'string', default: null },
+			{ name: 'json',    type: 'boolean', default: false },
+		],
+	},
+	output: {
+		data_shape: {
+			skill:       'string',
+			version:     'string',
+			ref:         'string',
+			commit:      'string',
+			synthesized: 'boolean',
+			content:     'string',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',  next_step: { kind: 'routing',  action: 'discover_schema' } },
+		{ code: 'NOT_FOUND' },
+		{ code: 'NETWORK_ERROR', next_step: { kind: 'recovery', action: 'retry' } },
+	],
+	examples: [
+		'happyskills changelog acme/deploy-aws',
+		'happyskills changelog acme/deploy-aws --version 1.2.0 --json',
+	],
+}
+
+module.exports = { run, find_changelog_entry, synthesize_from_refs, normalize_ref, schema }

package/src/commands/check.js

@@ -206,4 +206,33 @@ const run = (args) => catch_errors('Check failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name: 'check',
+	audience: 'consumer',
+	purpose: 'Check installed skills for available updates and report drift, ahead, and conflict states.',
+	mutation: false,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [{ name: 'skill', required: false, type: 'string', pattern: '<owner>/<name>' }],
+		flags: [
+			{ name: 'json', type: 'boolean', default: false }
+		]
+	},
+	output: {
+		data_shape: {
+			results: 'array<{ skill: string, installed: string, latest: string, status: string, via: string|null, drift: object|null, ahead: object|null }>',
+			outdated_count: 'number',
+			up_to_date_count: 'number',
+			conflicts_count: 'number',
+			drift_count: 'number',
+			ahead_count: 'number'
+		}
+	},
+	errors: [],
+	examples: [
+		'happyskills check',
+		'happyskills check acme/deploy-aws'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/config.js

@@ -209,4 +209,37 @@ const run = (args) => catch_errors('Config failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'config',
+	audience: 'account',
+	purpose:  'View or modify the global CLI configuration; the agents sub-key controls which AI agents receive installed skills.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'key',   required: false, type: 'string', enum: ['agents'] },
+			{ name: 'value', required: false, type: 'string' }
+		],
+		flags: [
+			{ name: 'list',  type: 'boolean', default: false },
+			{ name: 'reset', type: 'boolean', default: false },
+			{ name: 'json',  type: 'boolean', default: false }
+		]
+	},
+	output: {
+		data_shape: {
+			key: 'string',
+			value: 'string | null',
+			status: 'string'
+		}
+	},
+	errors: [
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } }
+	],
+	examples: [
+		'happyskills config agents claude,cursor',
+		'happyskills config agents --list'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/convert.js

@@ -249,4 +249,41 @@ const run = (args) => catch_errors('Convert failed', async () => {
 	print_info(`Next step: enrich metadata, then run \`happyskills publish ${skill_name}\` to publish.`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'convert',
+	audience: 'author',
+	purpose:  'Convert an external Claude Code skill into a managed HappySkills package by writing skill.json and updating the lock file.',
+	mutation: true,
+	interactive_in_text_mode: true,
+	input: {
+		positional: [ { name: 'skill', required: true, type: 'string', description: 'Name of the skill in .claude/skills/' } ],
+		flags: [
+			{ name: 'global',    alias: 'g', type: 'boolean', default: false,     description: 'Look in global skills (~/.agents/skills/)' },
+			{ name: 'workspace', type: 'string',  default: undefined, description: 'Target workspace slug' },
+			{ name: 'version',   type: 'string',  default: '1.0.0',   description: 'Initial version' },
+			{ name: 'keywords',  type: 'string',  default: undefined, description: 'Comma-separated keywords' },
+			{ name: 'agents',    type: 'string',  default: undefined, description: 'Target specific agents (comma-separated); default: auto-detect' },
+			{ name: 'yes',       alias: 'y', type: 'boolean', default: false, description: 'Skip confirmation prompt' },
+			{ name: 'json',      type: 'boolean', default: false,     description: 'Output as JSON' },
+		],
+	},
+	output: {
+		data_shape: {
+			skill:         'string',
+			version:       'string',
+			workspace:     'string',
+			description:   'string',
+			linked_agents: 'string[] | undefined',
+			warnings:      'string[] | undefined',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } },
+	],
+	examples: [
+		'happyskills convert pulumi-aws-docs --workspace happyskillsai',
+		'happyskills convert pulumi-aws-docs --version 2.0.0 -y',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/delete.js

@@ -89,4 +89,36 @@ const run = (args) => catch_errors('Delete failed', async () => {
 	print_success(`Deleted "${skill}" from the registry.`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'delete',
+	audience: 'author',
+	purpose:  'Permanently delete a skill from the registry (soft-delete on server; irreversible from CLI perspective).',
+	mutation: true,
+	interactive_in_text_mode: true,
+	input: {
+		positional: [
+			{ name: 'skill', required: true, type: 'string', pattern: '<owner>/<name>' },
+		],
+		flags: [
+			{ name: 'yes',  short: 'y', type: 'boolean', default: false },
+			{ name: 'json', type: 'boolean', default: false },
+		],
+	},
+	output: {
+		data_shape: {
+			deleted: 'boolean',
+			skill:   'string',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',           next_step: { kind: 'routing',      action: 'discover_schema'    } },
+		{ code: 'AUTH_REQUIRED',         next_step: { kind: 'recovery',     action: 'login'              } },
+		{ code: 'CONFIRMATION_REQUIRED', next_step: { kind: 'confirmation', action: 'confirm_destructive' } },
+	],
+	examples: [
+		'happyskills delete acme/deploy-aws',
+		'happyskills delete acme/deploy-aws --json -y',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/diff.js

@@ -349,4 +349,36 @@ const run = (args) => catch_errors('Diff failed', async () => {
 
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name: 'diff',
+	audience: 'consumer',
+	purpose: 'Show file-level differences for an installed skill with unified diffs (local vs base, base vs remote, or three-way).',
+	mutation: false,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [{ name: 'skill', required: true, type: 'string', pattern: '<owner>/<name>' }],
+		flags: [
+			{ name: 'remote', type: 'boolean', default: false },
+			{ name: 'full', type: 'boolean', default: false },
+			{ name: 'no-content', type: 'boolean', default: false },
+			{ name: 'global', type: 'boolean', default: false },
+			{ name: 'json', type: 'boolean', default: false }
+		]
+	},
+	output: {
+		data_shape: {
+			mode: 'string',
+			report: 'object',
+			drift: 'object|null'
+		}
+	},
+	errors: [
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } }
+	],
+	examples: [
+		'happyskills diff acme/deploy-aws',
+		'happyskills diff acme/deploy-aws --full'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/disable.js

@@ -102,4 +102,34 @@ const run = (args) => catch_errors('Disable failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name: 'disable',
+	audience: 'consumer',
+	purpose: 'Remove agent symlinks for one or more skills without deleting skill files; skills can be re-enabled at any time.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'skill', required: true, type: 'string' }
+		],
+		flags: [
+			{ name: 'global', alias: 'g', type: 'boolean' },
+			{ name: 'agents', type: 'string' },
+			{ name: 'json', type: 'boolean' }
+		]
+	},
+	output: {
+		data_shape: {
+			results: 'array<{ skill: string, status: string }>'
+		}
+	},
+	errors: [
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } }
+	],
+	examples: [
+		'happyskills disable acme/deploy-aws',
+		'happyskills disable acme/deploy-aws acme/monitoring -g'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/enable.js

@@ -118,4 +118,34 @@ const run = (args) => catch_errors('Enable failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name: 'enable',
+	audience: 'consumer',
+	purpose: 'Restore agent symlinks for one or more previously disabled skills.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'skill', required: true, type: 'string' }
+		],
+		flags: [
+			{ name: 'global', alias: 'g', type: 'boolean' },
+			{ name: 'agents', type: 'string' },
+			{ name: 'json', type: 'boolean' }
+		]
+	},
+	output: {
+		data_shape: {
+			results: 'array<{ skill: string, status: string }>'
+		}
+	},
+	errors: [
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } }
+	],
+	examples: [
+		'happyskills enable acme/deploy-aws',
+		'happyskills enable acme/deploy-aws acme/monitoring -g'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/feedback.js

@@ -257,4 +257,44 @@ const run = (args) => catch_errors('Feedback command failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'feedback',
+	audience: 'account',
+	purpose:  'Lodge feedback (bug, wish, compliment, question, or other) with HappySkills; opens $EDITOR when body is omitted.',
+	mutation: true,
+	interactive_in_text_mode: true,
+	input: {
+		positional: [
+			{ name: 'category', required: true,  type: 'string', enum: ['bug', 'wish', 'compliment', 'question', 'other'] },
+			{ name: 'body',     required: false, type: 'string' }
+		],
+		flags: [
+			{ name: 'subject', type: 'string',  default: null },
+			{ name: 'attach',  type: 'string',  default: null },
+			{ name: 'json',    type: 'boolean', default: false }
+		]
+	},
+	output: {
+		data_shape: {
+			feedback: 'object',
+			attachments: 'array'
+		}
+	},
+	errors: [
+		{ code: 'AUTH_REQUIRED',          next_step: { kind: 'recovery',      action: 'login' } },
+		{ code: 'USAGE_ERROR',            next_step: { kind: 'routing',       action: 'discover_schema' } },
+		{ code: 'NETWORK_ERROR',          next_step: { kind: 'recovery',      action: 'retry' } },
+		{ code: 'ATTACHMENT_TOO_LARGE' },
+		{ code: 'SUBJECT_TOO_LONG' },
+		{ code: 'BODY_TOO_LONG' },
+		{ code: 'BODY_REQUIRED' },
+		{ code: 'INVALID_CATEGORY' },
+		{ code: 'ATTACHMENT_LIMIT_REACHED' }
+	],
+	examples: [
+		'happyskills feedback bug "search returns nothing for partial slugs"',
+		'happyskills feedback wish "I wish I could export my catalog to JSON"'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/fork.js

@@ -117,4 +117,38 @@ const run = (args) => catch_errors('Fork failed', async () => {
 	print_hint(`Edit the skill, then run ${code(`happyskills publish --workspace ${workspace.slug}`)} when ready.`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'fork',
+	audience: 'author',
+	purpose:  'Fork a published skill to your own workspace: downloads the latest version and writes skill.json referencing the original.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [ { name: 'skill', required: true, type: 'string', pattern: '<owner>/<name>' } ],
+		flags: [
+			{ name: 'workspace', type: 'string',  default: undefined, description: 'Target workspace (if you have multiple)' },
+			{ name: 'json',      type: 'boolean', default: false,     description: 'Output as JSON' },
+		],
+	},
+	output: {
+		data_shape: {
+			skill:          'string',
+			forked_version: 'string',
+			new_version:    'string',
+			workspace:      'string',
+			directory:      'string',
+		},
+	},
+	errors: [
+		{ code: 'AUTH_REQUIRED',  next_step: { kind: 'recovery', action: 'login' } },
+		{ code: 'USAGE_ERROR',    next_step: { kind: 'routing',  action: 'discover_schema' } },
+		{ code: 'NETWORK_ERROR',  next_step: { kind: 'recovery', action: 'retry' } },
+		{ code: 'NOT_FOUND' },
+	],
+	examples: [
+		'happyskills fork acme/deploy-aws',
+		'happyskills fork acme/deploy-aws --workspace myorg',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/groups.js

@@ -216,4 +216,43 @@ const run = (args) => catch_errors('Groups command failed', async () => {
 	throw new UsageError(`Unknown subcommand: ${sub}. Run happyskills groups --help`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name: 'groups',
+	audience: 'account',
+	purpose: 'Manage workspace groups and group membership: list, create, delete, show, add/remove members, toggle default.',
+	mutation: true,
+	interactive_in_text_mode: true,
+	input: {
+		positional: [
+			{ name: 'subcommand', required: true, type: 'string', enum: ['list', 'create', 'delete', 'show', 'add', 'remove', 'default'] }
+		],
+		flags: [
+			{ name: 'workspace', alias: 'w', type: 'string' },
+			{ name: 'description', type: 'string' },
+			{ name: 'default', type: 'boolean' },
+			{ name: 'on', type: 'boolean' },
+			{ name: 'off', type: 'boolean' },
+			{ name: 'yes', alias: 'y', type: 'boolean' },
+			{ name: 'json', type: 'boolean' }
+		]
+	},
+	output: {
+		data_shape: {
+			results: 'array<{ name: string, description: string, member_count: number, is_default: boolean }>'
+		}
+	},
+	errors: [
+		{ code: 'AUTH_REQUIRED', next_step: { kind: 'recovery', action: 'login' } },
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } },
+		{ code: 'NOT_FOUND' },
+		{ code: 'ALREADY_EXISTS' },
+		{ code: 'FORBIDDEN' },
+		{ code: 'NETWORK_ERROR', next_step: { kind: 'recovery', action: 'retry' } }
+	],
+	examples: [
+		'happyskills groups list -w acme',
+		'happyskills groups create -w acme engineering --description "Core team"'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/init.js

@@ -147,4 +147,38 @@ const run = (args) => catch_errors('Init failed', async () => {
 	print_hint(`Edit these files, then run ${code(`happyskills release ${final_name} --workspace <slug>`)} to publish.`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'init',
+	audience: 'consumer',
+	purpose:  'Scaffold a new skill (or kit) directory with skill.json and SKILL.md under .agents/skills/<name>/.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [ { name: 'name', required: true, type: 'string', description: 'Skill name (e.g., my-deploy-skill)' } ],
+		flags: [
+			{ name: 'global',  alias: 'g',       type: 'boolean', default: false,     description: 'Create in global skills (~/.agents/skills/)' },
+			{ name: 'kit',                        type: 'boolean', default: false,     description: 'Initialize as a kit (collection of skills)' },
+			{ name: 'agents',                     type: 'string',  default: undefined, description: 'Target specific agents (comma-separated)' },
+			{ name: 'json',                        type: 'boolean', default: false,     description: 'Output as JSON' },
+		],
+	},
+	output: {
+		data_shape: {
+			name:          'string',
+			type:          'string',
+			files_created: 'string[]',
+			directory:     'string',
+			linked_agents: 'string[] (optional)',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',    next_step: { kind: 'routing',   action: 'discover_schema' } },
+		{ code: 'ALREADY_EXISTS' },
+	],
+	examples: [
+		'happyskills init my-deploy-skill',
+		'happyskills init my-kit --kit',
+	],
+}
+
+module.exports = { run, schema }