@skilly-hand/skilly-hand 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -16,6 +16,39 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.6.0] - 2026-04-03
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.6.0)
+
+### Added
+- Added portable skill `angular-guidelines` for Angular-only generation/review workflows, including mandatory latest-stable preflight checks and modern Angular best-practice defaults.
+
+### Changed
+- _None._
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
+## [0.5.0] - 2026-04-03
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.5.0)
+
+### Added
+- Interactive command launcher when running `npx skilly-hand` in a TTY, including install skill/agent selection flow.
+- New `selectedSkillIds` install path for explicitly choosing portable skills.
+- Comprehensive CLI interaction tests in `tests/interactive-cli.test.js`.
+
+### Changed
+- Help, docs, and install/uninstall confirmation messaging now reflect current behavior and naming (`skilly-hand` branding).
+- CLI bin execution mode and command routing were refactored into testable `runCli`/service helpers.
+
+### Fixed
+- Non-interactive invocation without a command now defaults to install output instead of opening prompts.
+
+### Removed
+- _None._
+
 ## [0.4.0] - 2026-04-03
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.4.0)
 

package/README.md

@@ -37,6 +37,8 @@ npm install
 npx skilly-hand
 ```
 
+`npx skilly-hand` opens an interactive command launcher when running in a TTY.
+
 ---
 
 ## Commands
@@ -49,6 +51,14 @@ npx skilly-hand
 | `npx skilly-hand doctor` | Diagnose installation and configuration issues |
 | `npx skilly-hand uninstall` | Remove installed skills |
 
+### Common Flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `--json` | Emit machine-readable output and disable interactive prompts |
+| `--yes`, `-y` | Skip confirmation prompts for mutating commands (`install`, `uninstall`) |
+| `--dry-run` | Preview install plan without writing files |
+
 ---
 
 ## Current Portable Catalog
@@ -56,6 +66,7 @@ npx skilly-hand
 The catalog currently includes:
 
 - `agents-root-orchestrator`
+- `angular-guidelines`
 - `figma-mcp-0to1`
 - `skill-creator`
 - `spec-driven-development`

package/catalog/README.md

@@ -5,6 +5,7 @@ Published portable skills consumed by the `skilly-hand` CLI.
 | Skill | Description | Tags | Installs For |
 | ----- | ----------- | ---- | ------------ |
 | `agents-root-orchestrator` | Author root AGENTS.md as a Where/What/When orchestrator that routes tasks and skill invocation clearly. | core, workflow, orchestration | all |
+| `angular-guidelines` | Guide Angular code generation and review using latest stable Angular verification and modern framework best practices. | angular, frontend, workflow, best-practices | all |
 | `figma-mcp-0to1` | Guide users from Figma MCP installation and authentication through first canvas creation, with function-level tool coverage and operational recovery patterns. | figma, mcp, workflow, design | all |
 | `skill-creator` | Create and standardize AI skills with reusable structure, metadata rules, and templates. | core, workflow, authoring | all |
 | `spec-driven-development` | Plan, execute, and verify multi-step work through versioned specs with small, testable tasks. | core, workflow, planning | all |

package/catalog/catalog-index.json

@@ -1,5 +1,6 @@
 [
   "agents-root-orchestrator",
+  "angular-guidelines",
   "figma-mcp-0to1",
   "skill-creator",
   "spec-driven-development",

package/catalog/skills/angular-guidelines/SKILL.md

@@ -0,0 +1,176 @@
+# Angular Guidelines
+
+## When to Use
+
+Use this skill when:
+
+- You are generating Angular components, directives, pipes, services, or supporting files.
+- You are refactoring existing Angular code to current framework patterns.
+- You are reviewing Angular code quality and framework-alignment in an Angular workspace.
+
+Do not use this skill for:
+
+- Non-Angular frontend stacks (React, Vue, Svelte, or framework-agnostic UI tasks).
+- Deep architecture decisions outside code artifact generation/review scope.
+- Pure test-strategy design unrelated to Angular implementation details.
+
+---
+
+## Routing Map
+
+Choose sub-agents by intent:
+
+| Intent | Sub-agent |
+| --- | --- |
+| Create, refactor, or review Angular components | [agents/component-creator.md](agents/component-creator.md) |
+| Write or review Angular tests | [agents/angular-tester.md](agents/angular-tester.md) |
+
+---
+
+## Standard Execution Sequence
+
+1. Run latest stable Angular preflight checks.
+2. Route to the smallest matching sub-agent by task intent.
+3. Apply the sub-agent checklist before finalizing generated code or review output.
+
+---
+
+## Critical Patterns
+
+### Pattern 1: Latest Stable Angular Preflight (Mandatory)
+
+Before generating or changing Angular code:
+
+1. Check the latest stable Angular core release:
+   `npm view @angular/core version`
+2. Check the project's installed or declared Angular version:
+   `npm ls @angular/core` or inspect `package.json`.
+3. If versions diverge, generate content for the latest stable APIs and call out upgrade steps.
+4. If npm metadata is unavailable, verify against official Angular release sources before proceeding.
+
+Never hardcode a specific Angular major as the default baseline.
+
+### Pattern 2: Modern Angular Defaults for New Code
+
+Use these defaults unless project constraints explicitly prevent them:
+
+| Area | Default |
+| --- | --- |
+| Component model | Standalone-first (`standalone: true`) |
+| State + bindings | Signals (`signal`, `computed`, `input`, `output`) |
+| Template flow | `@if`, `@for`, `@switch` control flow blocks |
+| Dependency injection | `inject()` over constructor injection for new code |
+| Forms | Typed reactive forms |
+| Rendering strategy | OnPush-friendly patterns and deferred/lazy rendering where appropriate |
+
+### Pattern 3: Generation and Review Guardrails
+
+- Keep generated files focused and minimal for the requested artifact.
+- Prefer framework-native patterns over custom abstractions unless required by repo conventions.
+- Call out deprecated patterns in reviewed code and suggest modern Angular replacements.
+- For component-specific work, apply [agents/component-creator.md](agents/component-creator.md).
+- For testing-specific work, apply [agents/angular-tester.md](agents/angular-tester.md).
+
+---
+
+## Decision Tree
+
+```text
+Is this an Angular project (angular.json or @angular/core present)?
+  NO  -> Do not apply this skill
+  YES -> Continue
+
+Is this a create/generate task?
+  YES -> Run latest stable preflight, then generate with modern defaults
+  NO  -> Continue
+
+Is this a refactor task?
+  YES -> Preserve behavior, migrate incrementally to modern Angular patterns
+  NO  -> Continue
+
+Is this a review task?
+  YES -> Validate latest-stable alignment + best-practice checklist
+  NO  -> Apply the minimal Angular guidance needed for the request
+```
+
+---
+
+## Code Examples
+
+### Example 1: Standalone + Signals Component
+
+```typescript
+import { ChangeDetectionStrategy, Component, computed, input, output } from "@angular/core";
+
+@Component({
+  selector: "app-badge",
+  standalone: true,
+  template: `
+    <span [attr.data-tone]="tone()">{{ label() }}</span>
+    @if (showCount()) {
+      <small>{{ count() }}</small>
+    }
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush
+})
+export class BadgeComponent {
+  readonly label = input.required<string>();
+  readonly count = input(0);
+  readonly increment = output<void>();
+  readonly showCount = computed(() => this.count() > 0);
+}
+```
+
+### Example 2: Service with `inject()`
+
+```typescript
+import { Injectable, inject } from "@angular/core";
+import { HttpClient } from "@angular/common/http";
+
+@Injectable({ providedIn: "root" })
+export class ProfileService {
+  private readonly http = inject(HttpClient);
+
+  getProfile() {
+    return this.http.get("/api/profile");
+  }
+}
+```
+
+---
+
+## Review Checklist
+
+- Latest stable Angular preflight was completed before code generation/refactor.
+- New artifacts use standalone-first + signal-first patterns where applicable.
+- Template control flow uses modern block syntax.
+- DI and forms follow modern typed Angular practices.
+- Output avoids deprecated Angular APIs unless needed for compatibility.
+
+---
+
+## Commands
+
+```bash
+# Latest stable Angular version
+npm view @angular/core version
+
+# Workspace Angular version
+npm ls @angular/core
+
+# Create a standalone component
+ng generate component <name> --standalone
+
+# Apply Angular framework updates in a workspace
+ng update @angular/core @angular/cli
+```
+
+---
+
+## Resources
+
+- Angular docs: https://angular.dev
+- Angular API reference: https://angular.dev/api
+- Angular update guide: https://angular.dev/update-guide
+- Angular blog (official releases): https://blog.angular.dev
+- Angular GitHub releases: https://github.com/angular/angular/releases

package/catalog/skills/angular-guidelines/agents/angular-tester.md

@@ -0,0 +1,130 @@
+# Angular Tester
+
+## When to Use
+
+Use this sub-agent when:
+
+- Adding or updating Angular component/service tests.
+- Reviewing Angular tests for correctness and modern framework usage.
+- Choosing test patterns for async, signal-based, or HTTP-driven behaviors.
+
+Do not use this sub-agent for:
+
+- Component implementation guidance without tests (use `component-creator`).
+- Framework-agnostic testing standards not tied to Angular behavior.
+
+---
+
+## Runner Policy
+
+- Default: Vitest-first in Angular workspaces.
+- Fallback: Use Jasmine/Karma patterns only when the workspace is already configured for Jasmine.
+- Do not force runner migration inside unrelated feature tasks.
+
+---
+
+## Core Testing Patterns
+
+- Configure `TestBed` with standalone imports for component tests.
+- Test signal and computed behavior directly when possible.
+- Test signal inputs/outputs using component instance APIs and DOM-triggered events.
+- Cover async behavior with `fakeAsync`/`tick`/`flush` or `waitForAsync`/`whenStable`.
+- For HTTP paths, use `HttpClientTestingModule`/`HttpTestingController` and verify requests.
+- For services, prefer explicit DI setup and clear mocking boundaries.
+
+---
+
+## Command Matrix
+
+| Scenario | Preferred Command | Fallback |
+| --- | --- | --- |
+| Run all unit tests | `ng test` | Existing workspace test command |
+| Watch mode | `ng test --watch` | Workspace equivalent |
+| Coverage | `ng test --code-coverage` | Workspace equivalent |
+| CI-style single run | `ng test --watch=false` | Workspace equivalent |
+
+If the workspace uses Jasmine/Karma, keep command behavior aligned with existing runner configuration.
+
+---
+
+## Decision Tree
+
+```text
+Is the target under test a standalone component?
+  YES -> Use TestBed with imports: [ComponentUnderTest]
+  NO  -> Continue
+
+Is this primarily service logic?
+  YES -> Configure TestBed providers/injection and mock dependencies
+  NO  -> Continue
+
+Is behavior async (timers, promises, stabilization)?
+  YES -> Use fakeAsync/tick or waitForAsync/whenStable
+  NO  -> Continue
+
+Does behavior involve HTTP or resource loading?
+  YES -> Use HttpTestingController and assert request + response flow
+  NO  -> Use direct synchronous assertions
+```
+
+---
+
+## Test Snippets
+
+### Standalone Component Test
+
+```typescript
+import { ComponentFixture, TestBed } from "@angular/core/testing";
+import { describe, expect, it, beforeEach } from "vitest";
+import { CounterComponent } from "./counter.component";
+
+describe("CounterComponent", () => {
+  let fixture: ComponentFixture<CounterComponent>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [CounterComponent]
+    }).compileComponents();
+    fixture = TestBed.createComponent(CounterComponent);
+    fixture.detectChanges();
+  });
+
+  it("renders default count", () => {
+    expect(fixture.componentInstance.count()).toBe(0);
+  });
+});
+```
+
+### HTTP Service Test
+
+```typescript
+import { TestBed } from "@angular/core/testing";
+import { HttpClientTestingModule, HttpTestingController } from "@angular/common/http/testing";
+
+describe("ProfileService", () => {
+  it("requests profile", () => {
+    TestBed.configureTestingModule({
+      imports: [HttpClientTestingModule]
+    });
+    const service = TestBed.inject(ProfileService);
+    const httpMock = TestBed.inject(HttpTestingController);
+
+    service.getProfile().subscribe();
+
+    const req = httpMock.expectOne("/api/profile");
+    expect(req.request.method).toBe("GET");
+    req.flush({ id: "1" });
+    httpMock.verify();
+  });
+});
+```
+
+---
+
+## Review Checklist
+
+- Tests follow the workspace runner policy (Vitest-first, Jasmine fallback only when preconfigured).
+- Standalone Angular artifacts are tested with appropriate TestBed setup.
+- Signal/input/output behavior is asserted explicitly.
+- Async and HTTP behavior use deterministic Angular testing utilities.
+- Assertions verify user-visible behavior or contract-level outcomes, not incidental internals.

package/catalog/skills/angular-guidelines/agents/component-creator.md

@@ -0,0 +1,124 @@
+# Angular Component Creator
+
+## When to Use
+
+Use this sub-agent when:
+
+- Creating a new Angular component.
+- Refactoring an existing Angular component to modern patterns.
+- Reviewing component implementation details and template patterns.
+
+Do not use this sub-agent for:
+
+- Directive, pipe, or service implementation.
+- Repository-wide architecture decisions.
+- Test-only tasks (use `angular-tester`).
+
+---
+
+## Core Rules
+
+- Keep explicit `standalone: true` in generated component metadata.
+- Use signal APIs for component IO and state (`input`, `output`, `signal`, `computed`).
+- Use native template control flow blocks (`@if`, `@for`, `@switch`).
+- Prefer `host` object bindings/events over decorator-based host metadata.
+- Use OnPush-friendly reactive patterns and avoid zone-dependent assumptions.
+- For interactive components, include keyboard and ARIA semantics in host bindings.
+
+---
+
+## Template Snippets
+
+### Minimal Standalone Component
+
+```typescript
+import { ChangeDetectionStrategy, Component } from "@angular/core";
+
+@Component({
+  selector: "app-example",
+  standalone: true,
+  template: `<p>Example works</p>`,
+  changeDetection: ChangeDetectionStrategy.OnPush
+})
+export class ExampleComponent {}
+```
+
+### Signal Inputs and Outputs
+
+```typescript
+import { Component, input, output, computed } from "@angular/core";
+
+@Component({
+  selector: "app-counter",
+  standalone: true,
+  template: `<button (click)="increment.emit()">{{ label() }} {{ count() }}</button>`
+})
+export class CounterComponent {
+  readonly label = input.required<string>();
+  readonly count = input(0);
+  readonly increment = output<void>();
+  readonly isNonZero = computed(() => this.count() > 0);
+}
+```
+
+### Host Bindings and Events
+
+```typescript
+@Component({
+  selector: "button[appActionButton]",
+  standalone: true,
+  template: `<ng-content />`,
+  host: {
+    "role": "button",
+    "[attr.aria-disabled]": "disabled() ? 'true' : null",
+    "[class.is-disabled]": "disabled()",
+    "(click)": "onClick($event)",
+    "(keydown.enter)": "onClick($event)"
+  }
+})
+export class ActionButtonComponent {
+  readonly disabled = input(false);
+  readonly pressed = output<void>();
+
+  onClick(event: Event) {
+    if (this.disabled()) {
+      event.preventDefault();
+      return;
+    }
+    this.pressed.emit();
+  }
+}
+```
+
+### Content Projection and Render-Safe Hooks
+
+```typescript
+import { Component, afterNextRender } from "@angular/core";
+
+@Component({
+  selector: "app-card",
+  standalone: true,
+  template: `
+    <header><ng-content select="[card-header]" /></header>
+    <section><ng-content /></section>
+    <footer><ng-content select="[card-footer]" /></footer>
+  `
+})
+export class CardComponent {
+  constructor() {
+    afterNextRender(() => {
+      // Run post-render DOM logic only when needed.
+    });
+  }
+}
+```
+
+---
+
+## Review Checklist
+
+- Component metadata includes explicit `standalone: true`.
+- Inputs/outputs use modern signal-based APIs where applicable.
+- Templates use native control flow blocks, not legacy structural directives.
+- Host interaction includes required ARIA and keyboard semantics for interactive UI.
+- Change detection and state flow are OnPush-friendly and predictable.

package/catalog/skills/angular-guidelines/manifest.json

@@ -0,0 +1,41 @@
+{
+  "id": "angular-guidelines",
+  "title": "Angular Guidelines",
+  "description": "Guide Angular code generation and review using latest stable Angular verification and modern framework best practices.",
+  "portable": true,
+  "tags": ["angular", "frontend", "workflow", "best-practices"],
+  "detectors": ["angular"],
+  "detectionTriggers": ["auto"],
+  "installsFor": ["all"],
+  "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot"],
+  "skillMetadata": {
+    "author": "skilly-hand",
+    "last-edit": "2026-04-03",
+    "license": "Apache-2.0",
+    "version": "1.1.1",
+    "changelog": "Added allowed-modes metadata to declare angular-guidelines sub-agent routing targets; improves discoverability of component-creator and angular-tester delegation modes; affects angular-guidelines manifest metadata",
+    "auto-invoke": "Generating, reviewing, or refactoring Angular code artifacts in Angular projects",
+    "allowed-modes": [
+      "component-creator",
+      "angular-tester"
+    ],
+    "allowed-tools": [
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "Bash",
+      "WebFetch",
+      "WebSearch",
+      "Task",
+      "SubAgent"
+    ]
+  },
+  "files": [
+    { "path": "SKILL.md", "kind": "instruction" },
+    { "path": "agents/component-creator.md", "kind": "instruction" },
+    { "path": "agents/angular-tester.md", "kind": "instruction" }
+  ],
+  "dependencies": []
+}

package/catalog/skills/figma-mcp-0to1/manifest.json

@@ -12,9 +12,15 @@
     "author": "skilly-hand",
     "last-edit": "2026-04-03",
     "license": "Apache-2.0",
-    "version": "1.0.0",
-    "changelog": "Added a complete Figma MCP setup-to-canvas guide with orchestrator subskills and full official tool matrix coverage; reduces onboarding ambiguity and improves first-run success rates; affects Figma MCP setup, tool selection, and troubleshooting workflows",
+    "version": "1.0.1",
+    "changelog": "Added allowed-modes metadata to declare figma-mcp-0to1 sub-agent routing targets; improves discoverability of install-auth, tool-function-catalog, canvas-creation-playbook, and troubleshooting-ops delegation modes; affects figma-mcp-0to1 manifest metadata",
     "auto-invoke": "Installing, configuring, or using Figma MCP from setup through first canvas creation",
+    "allowed-modes": [
+      "install-auth",
+      "tool-function-catalog",
+      "canvas-creation-playbook",
+      "troubleshooting-ops"
+    ],
     "allowed-tools": [
       "Read",
       "Edit",

package/catalog/skills/spec-driven-development/SKILL.md

@@ -33,6 +33,31 @@ Recommended task size:
 
 ---
 
+## OpenSpec Complementary Support
+
+Default execution SHOULD remain the local `.sdd` workflow.
+
+Recur to OpenSpec support when the task needs complementary structure for:
+
+- Multi-session continuity where planning context must persist across chats.
+- Shareable planning artifacts for review before implementation.
+- Requirement-delta clarity that benefits from explicit change proposals.
+
+Routing rules:
+
+- Keep the local `.sdd/active/<feature-name>/spec.md` as the execution source of truth unless the team explicitly standardizes on OpenSpec paths.
+- If OpenSpec is unavailable, continue in `.sdd` and document assumptions directly in the active spec.
+
+| Use local SDD only | Use OpenSpec support |
+| --- | --- |
+| Single-session or straightforward work with clear requirements | Work spans multiple sessions and needs persistent planning context |
+| Existing `.sdd` artifacts already provide enough review clarity | Team needs proposal/design/tasks artifacts for async review |
+| Requirement changes are small and easy to track in-place | Requirement deltas are complex and need explicit change framing |
+
+Reference (informational): [https://openspec.dev/](https://openspec.dev/)
+
+---
+
 ## Spec Structure
 
 A practical spec includes:

package/catalog/skills/spec-driven-development/manifest.json

@@ -12,9 +12,15 @@
     "author": "skilly-hand",
     "last-edit": "2026-04-03",
     "license": "Apache-2.0",
-    "version": "1.0.1",
-    "changelog": "Added explicit delta/full guidance, archive rules, task sizing decision tree, and common mistakes section; improves planning clarity and reduces execution ambiguity; affects spec-driven-development SKILL.md usage guidance",
+    "version": "1.0.3",
+    "changelog": "Added OpenSpec complementary support routing guidance to spec-driven-development instructions; improves planning continuity and review clarity when local SDD needs reinforcement; affects spec-driven-development SKILL guidance and manifest metadata",
     "auto-invoke": "Planning or executing feature work, bug fixes, and multi-phase implementation",
+    "allowed-modes": [
+      "plan",
+      "apply",
+      "verify",
+      "orchestrate"
+    ],
     "allowed-tools": [
       "Read",
       "Edit",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "publishConfig": {
@@ -40,5 +40,8 @@
     "detect": "node ./packages/cli/src/bin.js detect",
     "list": "node ./packages/cli/src/bin.js list",
     "doctor": "node ./packages/cli/src/bin.js doctor"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.10.1"
   }
 }

package/packages/cli/src/bin.js

@@ -1,17 +1,28 @@
 #!/usr/bin/env node
 import path from "node:path";
 import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { checkbox as inquirerCheckbox, confirm as inquirerConfirm, select as inquirerSelect } from "@inquirer/prompts";
 import { loadAllSkills } from "../../catalog/src/index.js";
-import { installProject, runDoctor, uninstallProject } from "../../core/src/index.js";
+import {
+  DEFAULT_AGENTS,
+  installProject,
+  resolveSkillSelection,
+  runDoctor,
+  uninstallProject
+} from "../../core/src/index.js";
 import { createTerminalRenderer } from "../../core/src/terminal.js";
 import { detectProject } from "../../detectors/src/index.js";
 
 const require = createRequire(import.meta.url);
 const { version } = require("../../../package.json");
 
-const renderer = createTerminalRenderer();
+function isExecutedDirectly(metaUrl, argv1) {
+  if (!argv1) return false;
+  return metaUrl === pathToFileURL(argv1).href;
+}
 
-function parseArgs(argv) {
+export function parseArgs(argv) {
   const args = [...argv];
   const positional = [];
   const flags = {
@@ -54,9 +65,10 @@ function parseArgs(argv) {
   return { command: positional[0], flags };
 }
 
-function buildHelpText() {
+function buildHelpText(renderer, appVersion) {
   const usage = renderer.section("Usage", renderer.list([
-    "npx skilly-hand [install]",
+    "npx skilly-hand                  # interactive launcher when running in a TTY",
+    "npx skilly-hand install",
     "npx skilly-hand detect",
     "npx skilly-hand list",
     "npx skilly-hand doctor",
@@ -66,7 +78,7 @@ function buildHelpText() {
   const flags = renderer.section("Flags", renderer.list([
     "--dry-run                     Show install plan without writing files",
     "--json                        Emit stable JSON output for automation",
-    "--yes, -y                     Reserved for future non-interactive confirmations",
+    "--yes, -y                     Skip install/uninstall confirmations",
     "--verbose, -v                 Reserved for future debug detail",
     "--agent, -a <name>            codex|claude|cursor|gemini|copilot (repeatable)",
     "--cwd <path>                  Project root (defaults to current directory)",
@@ -76,21 +88,22 @@ function buildHelpText() {
   ], { bullet: "-" }));
 
   const examples = renderer.section("Examples", renderer.list([
+    "npx skilly-hand",
     "npx skilly-hand install --dry-run",
     "npx skilly-hand detect --json",
     "npx skilly-hand install --agent codex --agent claude",
-    "npx skilly-hand list --include workflow"
+    "npx skilly-hand uninstall --yes"
   ], { bullet: "-" }));
 
   return renderer.joinBlocks([
-    renderer.banner(version),
+    renderer.banner(appVersion),
     usage,
     flags,
     examples
   ]);
 }
 
-function printInstallResult(result, flags) {
+function printInstallResult(renderer, appVersion, result, flags) {
   const mode = flags.dryRun ? "dry-run" : "apply";
   const preflight = renderer.section(
     "Install Preflight",
@@ -135,19 +148,19 @@ function printInstallResult(result, flags) {
 
   const nextSteps = result.applied
     ? renderer.nextSteps([
-      "Review generated AGENTS and assistant instruction files.",
-      "Run `npx skilly-hand doctor` to validate installation health.",
-      "Use `npx skilly-hand uninstall` to restore backed-up files if needed."
-    ])
+        "Review generated AGENTS and assistant instruction files.",
+        "Run `npx skilly-hand doctor` to validate installation health.",
+        "Use `npx skilly-hand uninstall` to restore backed-up files if needed."
+      ])
     : renderer.nextSteps([
-      "Run `npx skilly-hand install` to apply this plan.",
-      "Adjust `--include` and `--exclude` tags to tune skill selection."
-    ]);
+        "Run `npx skilly-hand install` to apply this plan.",
+        "Adjust `--include` and `--exclude` tags to tune skill selection."
+      ]);
 
-  renderer.write(renderer.joinBlocks([renderer.banner(version), preflight, detections, skills, status, nextSteps]));
+  renderer.write(renderer.joinBlocks([renderer.banner(appVersion), preflight, detections, skills, status, nextSteps]));
 }
 
-function printDetectResult(cwd, detections) {
+function printDetectResult(renderer, cwd, detections) {
   const summary = renderer.section(
     "Detection Summary",
     renderer.kv([
@@ -166,7 +179,7 @@ function printDetectResult(cwd, detections) {
   renderer.write(renderer.joinBlocks([summary, findings]));
 }
 
-function printListResult(skills) {
+function printListResult(renderer, skills) {
   const summary = renderer.section(
     "Catalog Summary",
     renderer.kv([["Skills available", String(skills.length)]])
@@ -193,7 +206,7 @@ function printListResult(skills) {
   renderer.write(renderer.joinBlocks([summary, table]));
 }
 
-function printDoctorResult(result) {
+function printDoctorResult(renderer, result) {
   const badge = renderer.healthBadge(result.installed);
 
   const summary = renderer.section(
@@ -239,7 +252,7 @@ function printDoctorResult(result) {
   renderer.write(renderer.joinBlocks([badge, summary, lock, issues, probes]));
 }
 
-function printUninstallResult(result) {
+function printUninstallResult(renderer, result) {
   if (result.removed) {
     renderer.write(
       renderer.joinBlocks([
@@ -261,34 +274,193 @@ function printUninstallResult(result) {
   );
 }
 
-async function main() {
-  const { command, flags } = parseArgs(process.argv.slice(2));
+export function buildErrorHint(message) {
+  if (message.startsWith("Unknown command:")) {
+    return "Run `npx skilly-hand --help` to see available commands.";
+  }
+  if (message.startsWith("Unknown flag:") || message.startsWith("Missing value")) {
+    return "Check command flags with `npx skilly-hand --help`.";
+  }
+  return "Retry with `--verbose` for expanded context if needed.";
+}
 
-  if (flags.help) {
-    if (flags.json) {
-      renderer.writeJson({
-        command: command || "install",
-        help: true,
-        usage: [
-          "npx skilly-hand [install]",
-          "npx skilly-hand detect",
-          "npx skilly-hand list",
-          "npx skilly-hand doctor",
-          "npx skilly-hand uninstall"
-        ]
-      });
-      return;
-    }
+export function createPromptAdapter({ selectImpl, checkboxImpl, confirmImpl } = {}) {
+  return {
+    select: selectImpl || inquirerSelect,
+    checkbox: checkboxImpl || inquirerCheckbox,
+    confirm: confirmImpl || inquirerConfirm
+  };
+}
+
+function createServices(overrides = {}) {
+  return {
+    loadAllSkills,
+    installProject,
+    resolveSkillSelection,
+    runDoctor,
+    uninstallProject,
+    detectProject,
+    defaultAgents: DEFAULT_AGENTS,
+    ...overrides
+  };
+}
+
+function isInteractiveLauncherMode({ command, flags, stdout }) {
+  return !command && !flags.json && Boolean(stdout?.isTTY);
+}
+
+async function runInteractiveInstall({
+  cwd,
+  renderer,
+  prompt,
+  services,
+  appVersion
+}) {
+  const [catalog, detections] = await Promise.all([
+    services.loadAllSkills(),
+    services.detectProject(cwd)
+  ]);
+  const portableCatalog = catalog.filter((skill) => skill.portable).sort((a, b) => a.id.localeCompare(b.id));
+  const preselected = new Set(
+    services
+      .resolveSkillSelection({ catalog, detections, includeTags: [], excludeTags: [] })
+      .map((skill) => skill.id)
+  );
+
+  const selectedSkillIds = await prompt.checkbox({
+    message: "Select skills to install",
+    choices: portableCatalog.map((skill) => ({
+      value: skill.id,
+      name: `${skill.id} - ${skill.title}`,
+      checked: preselected.has(skill.id)
+    }))
+  });
+
+  const selectedAgents = await prompt.checkbox({
+    message: "Select AI assistants to configure",
+    choices: services.defaultAgents.map((agent) => ({
+      value: agent,
+      name: agent,
+      checked: true
+    }))
+  });
+
+  const preview = await services.installProject({
+    cwd,
+    agents: selectedAgents,
+    dryRun: true,
+    selectedSkillIds
+  });
+
+  printInstallResult(renderer, appVersion, preview, {
+    dryRun: true,
+    include: [],
+    exclude: []
+  });
 
-    renderer.write(buildHelpText());
+  const shouldApply = await prompt.confirm({
+    message: "Apply installation changes now?",
+    default: true
+  });
+
+  if (!shouldApply) {
+    renderer.write(renderer.status("info", "Installation cancelled.", "No files were written."));
     return;
   }
 
-  const cwd = path.resolve(flags.cwd || process.cwd());
-  const effectiveCommand = command || "install";
+  const applied = await services.installProject({
+    cwd,
+    agents: selectedAgents,
+    dryRun: false,
+    selectedSkillIds
+  });
+
+  printInstallResult(renderer, appVersion, applied, {
+    dryRun: false,
+    include: [],
+    exclude: []
+  });
+}
+
+async function runInteractiveSession({
+  cwd,
+  renderer,
+  prompt,
+  services,
+  appVersion
+}) {
+  renderer.write(renderer.banner(appVersion));
+
+  while (true) {
+    const selection = await prompt.select({
+      message: "Select a command",
+      choices: [
+        { value: "install", name: "Install" },
+        { value: "detect", name: "Detect" },
+        { value: "list", name: "List" },
+        { value: "doctor", name: "Doctor" },
+        { value: "uninstall", name: "Uninstall" },
+        { value: "exit", name: "Exit" }
+      ]
+    });
+
+    if (selection === "exit") {
+      renderer.write(renderer.status("info", "Exited skilly-hand interactive mode."));
+      return;
+    }
+
+    if (selection === "install") {
+      await runInteractiveInstall({ cwd, renderer, prompt, services, appVersion });
+      continue;
+    }
+
+    if (selection === "detect") {
+      const detections = await services.detectProject(cwd);
+      printDetectResult(renderer, cwd, detections);
+      continue;
+    }
+
+    if (selection === "list") {
+      const skills = await services.loadAllSkills();
+      printListResult(renderer, skills);
+      continue;
+    }
+
+    if (selection === "doctor") {
+      const result = await services.runDoctor(cwd);
+      printDoctorResult(renderer, result);
+      continue;
+    }
 
-  if (effectiveCommand === "detect") {
-    const detections = await detectProject(cwd);
+    if (selection === "uninstall") {
+      const confirmed = await prompt.confirm({
+        message: "Remove the skilly-hand installation from this project?",
+        default: false
+      });
+
+      if (!confirmed) {
+        renderer.write(renderer.status("info", "Uninstall cancelled."));
+        continue;
+      }
+
+      const result = await services.uninstallProject(cwd);
+      printUninstallResult(renderer, result);
+    }
+  }
+}
+
+async function runCommand({
+  command,
+  flags,
+  cwd,
+  stdout,
+  renderer,
+  prompt,
+  services,
+  appVersion
+}) {
+  if (command === "detect") {
+    const detections = await services.detectProject(cwd);
     if (flags.json) {
       renderer.writeJson({
         command: "detect",
@@ -298,12 +470,12 @@ async function main() {
       });
       return;
     }
-    printDetectResult(cwd, detections);
+    printDetectResult(renderer, cwd, detections);
     return;
   }
 
-  if (effectiveCommand === "list") {
-    const skills = await loadAllSkills();
+  if (command === "list") {
+    const skills = await services.loadAllSkills();
     if (flags.json) {
       renderer.writeJson({
         command: "list",
@@ -312,12 +484,12 @@ async function main() {
       });
       return;
     }
-    printListResult(skills);
+    printListResult(renderer, skills);
     return;
   }
 
-  if (effectiveCommand === "doctor") {
-    const result = await runDoctor(cwd);
+  if (command === "doctor") {
+    const result = await services.runDoctor(cwd);
     if (flags.json) {
       renderer.writeJson({
         command: "doctor",
@@ -325,12 +497,23 @@ async function main() {
       });
       return;
     }
-    printDoctorResult(result);
+    printDoctorResult(renderer, result);
     return;
   }
 
-  if (effectiveCommand === "uninstall") {
-    const result = await uninstallProject(cwd);
+  if (command === "uninstall") {
+    if (!flags.json && !flags.yes && Boolean(stdout?.isTTY)) {
+      const confirmed = await prompt.confirm({
+        message: "Remove the skilly-hand installation from this project?",
+        default: false
+      });
+      if (!confirmed) {
+        renderer.write(renderer.status("info", "Uninstall cancelled."));
+        return;
+      }
+    }
+
+    const result = await services.uninstallProject(cwd);
     if (flags.json) {
       renderer.writeJson({
         command: "uninstall",
@@ -338,12 +521,23 @@ async function main() {
       });
       return;
     }
-    printUninstallResult(result);
+    printUninstallResult(renderer, result);
     return;
   }
 
-  if (effectiveCommand === "install") {
-    const result = await installProject({
+  if (command === "install") {
+    if (!flags.dryRun && !flags.json && !flags.yes && Boolean(stdout?.isTTY)) {
+      const confirmed = await prompt.confirm({
+        message: "Apply installation changes to this project?",
+        default: true
+      });
+      if (!confirmed) {
+        renderer.write(renderer.status("info", "Installation cancelled.", "No files were written."));
+        return;
+      }
+    }
+
+    const result = await services.installProject({
       cwd,
       agents: flags.agents,
       dryRun: flags.dryRun,
@@ -361,43 +555,109 @@ async function main() {
       return;
     }
 
-    printInstallResult(result, flags);
+    printInstallResult(renderer, appVersion, result, flags);
     return;
   }
 
-  throw new Error(`Unknown command: ${effectiveCommand}`);
+  throw new Error(`Unknown command: ${command}`);
 }
 
-const jsonRequested = process.argv.includes("--json");
+export async function runCli({
+  argv = process.argv.slice(2),
+  stdout = process.stdout,
+  stderr = process.stderr,
+  env = process.env,
+  platform = process.platform,
+  prompt = createPromptAdapter(),
+  services: providedServices = {},
+  appVersion = version,
+  cwdResolver = process.cwd
+} = {}) {
+  const renderer = createTerminalRenderer({ stdout, stderr, env, platform });
+  const services = createServices(providedServices);
+  const { command, flags } = parseArgs(argv);
 
-main().catch((error) => {
-  const hint =
-    error.message.startsWith("Unknown command:")
-      ? "Run `npx skilly-hand --help` to see available commands."
-      : error.message.startsWith("Unknown flag:") || error.message.startsWith("Missing value")
-      ? "Check command flags with `npx skilly-hand --help`."
-      : "Retry with `--verbose` for expanded context if needed.";
+  if (flags.help) {
+    if (flags.json) {
+      renderer.writeJson({
+        command: command || "install",
+        help: true,
+        usage: [
+          "npx skilly-hand",
+          "npx skilly-hand install",
+          "npx skilly-hand detect",
+          "npx skilly-hand list",
+          "npx skilly-hand doctor",
+          "npx skilly-hand uninstall"
+        ]
+      });
+      return;
+    }
 
-  if (jsonRequested) {
-    renderer.writeErrorJson({
-      ok: false,
-      error: {
-        what: "skilly-hand command failed",
-        why: error.message,
-        hint
-      }
-    });
-    process.exitCode = 1;
+    renderer.write(buildHelpText(renderer, appVersion));
     return;
   }
 
-  renderer.writeError(
-    renderer.error({
-      what: "skilly-hand command failed",
-      why: error.message,
-      hint,
-      exitCode: 1
-    })
-  );
-  process.exitCode = 1;
-});
+  const cwd = path.resolve(flags.cwd || cwdResolver());
+
+  if (isInteractiveLauncherMode({ command, flags, stdout })) {
+    try {
+      await runInteractiveSession({
+        cwd,
+        renderer,
+        prompt,
+        services,
+        appVersion
+      });
+      return;
+    } catch (error) {
+      if (error?.name === "ExitPromptError") {
+        renderer.write(renderer.status("info", "Interactive session cancelled."));
+        return;
+      }
+      throw error;
+    }
+  }
+
+  const effectiveCommand = command || "install";
+  await runCommand({
+    command: effectiveCommand,
+    flags,
+    cwd,
+    stdout,
+    renderer,
+    prompt,
+    services,
+    appVersion
+  });
+}
+
+if (isExecutedDirectly(import.meta.url, process.argv[1])) {
+  const jsonRequested = process.argv.includes("--json");
+  const renderer = createTerminalRenderer();
+
+  runCli().catch((error) => {
+    if (jsonRequested) {
+      renderer.writeErrorJson({
+        ok: false,
+        error: {
+          what: "skilly-hand command failed",
+          why: error.message,
+          hint: buildErrorHint(error.message)
+        }
+      });
+      process.exitCode = 1;
+      return;
+    }
+
+    renderer.writeError(
+      renderer.error({
+        what: "skilly-hand command failed",
+        why: error.message,
+        hint: buildErrorHint(error.message),
+        exitCode: 1
+      })
+    );
+    process.exitCode = 1;
+  });
+}

package/packages/core/src/index.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { copySkillTo, loadAllSkills, renderAgentsMarkdown, verifyCatalogFiles } from "../../catalog/src/index.js";
 import { detectProject, inspectProjectFiles } from "../../detectors/src/index.js";
 
-const DEFAULT_AGENTS = ["codex", "claude", "cursor", "gemini", "copilot"];
+export const DEFAULT_AGENTS = ["codex", "claude", "cursor", "gemini", "copilot"];
 const MANAGED_MARKER = "<!-- Managed by skilly-hand.";
 
 function uniq(values) {
@@ -44,6 +44,37 @@ function parseTags(input) {
   return uniq((input || []).flatMap((value) => String(value).split(",")).map((value) => value.trim()).filter(Boolean));
 }
 
+function parseSkillIds(input) {
+  return uniq((input || []).flatMap((value) => String(value).split(",")).map((value) => value.trim()).filter(Boolean));
+}
+
+export function resolveSkillSelectionByIds({ catalog, selectedSkillIds = [] }) {
+  const ids = parseSkillIds(selectedSkillIds);
+  const portableById = new Map(
+    catalog
+      .filter((skill) => skill.portable)
+      .map((skill) => [skill.id, skill])
+  );
+  const allById = new Map(catalog.map((skill) => [skill.id, skill]));
+
+  const invalid = [];
+  for (const id of ids) {
+    if (!allById.has(id)) {
+      invalid.push(`Unknown skill id: ${id}`);
+      continue;
+    }
+    if (!portableById.has(id)) {
+      invalid.push(`Skill is not portable: ${id}`);
+    }
+  }
+
+  if (invalid.length > 0) {
+    throw new Error(invalid.join("; "));
+  }
+
+  return ids.map((id) => portableById.get(id)).sort((a, b) => a.id.localeCompare(b.id));
+}
+
 export function resolveSkillSelection({ catalog, detections, includeTags = [], excludeTags = [] }) {
   const coreSkills = catalog.filter((skill) => skill.tags.includes("core"));
   const requested = new Set(coreSkills.map((skill) => skill.id));
@@ -168,17 +199,20 @@ export async function installProject({
   agents,
   dryRun = false,
   includeTags = [],
-  excludeTags = []
+  excludeTags = [],
+  selectedSkillIds
 }) {
   const selectedAgents = normalizeAgentList(agents);
   const catalog = await loadAllSkills();
   const detections = await detectProject(cwd);
-  const skills = resolveSkillSelection({
-    catalog,
-    detections,
-    includeTags: parseTags(includeTags),
-    excludeTags: parseTags(excludeTags)
-  });
+  const skills = selectedSkillIds !== undefined && selectedSkillIds !== null
+    ? resolveSkillSelectionByIds({ catalog, selectedSkillIds })
+    : resolveSkillSelection({
+        catalog,
+        detections,
+        includeTags: parseTags(includeTags),
+        excludeTags: parseTags(excludeTags)
+      });
   const plan = buildInstallPlan({ cwd, detections, skills, agents: selectedAgents });
 
   if (dryRun) {

package/packages/core/src/ui/brand.js

@@ -20,7 +20,7 @@ const LOGO_ASCII = [
 
 export function getBrand() {
   return {
-    name: "autoskills",
+    name: "skilly-hand",
     tagline: "portable AI skill orchestration",
     hint: "npx skilly-hand --help",
     logo: {