feat(cli): add ask skills namespace (list/install/remove)

[amondnet]

Summary

Introduces ask skills — a sibling namespace to ask docs that surfaces and installs producer-side skills (agent-facing instruction bundles) shipped by libraries under a top-level skills/ directory.

• ask skills <spec> / ask skills list <spec> — prints candidate skill paths (one per line) from node_modules/<pkg>/ and the cached GitHub checkout.
• ask skills install <spec> — vendors each discovered skill into .ask/skills/<spec-key>/<skill-name>/ and creates relative POSIX symlinks into every selected coding-agent directory (.claude/skills/, .cursor/skills/, .opencode/skills/, .codex/skills/). Detects agents automatically; prompts via consola.prompt multiselect when >1 is present. Supports --agent, --force, --no-fetch.
• ask skills remove <spec> — reverses install deterministically via .ask/skills-lock.json; only unlinks symlinks whose target matches the vendored path.

The lock file is the single source of truth for removal so user-authored skills are never touched. Re-install is idempotent. Ignore markers in .gitignore, .prettierignore, sonar-project.properties, and .markdownlintignore now cover .ask/skills/ and .ask/skills-lock.json via the existing # ask:start ... # ask:end block.

Refs #86

Scope

• New walker: packages/cli/src/commands/find-skill-paths.ts
• New skills module: packages/cli/src/skills/{spec-key,lock,agent-detect,vendor,symlinks}.ts
• New commands: packages/cli/src/commands/skills/{index,list,install,remove}.ts
• Wired into packages/cli/src/index.ts
• Extended packages/cli/src/ignore-files.ts
• README.md section + product.md sync

Test plan

• Unit tests for walker, spec-key, lock, agent-detect, vendor, symlinks, ignore-files
• Command-level tests for list (mocked ensureCheckout)
• Integration test: install → idempotent reinstall → remove on a synthetic checkout with .claude/skills/
• Registration test: all subcommands + flags exposed via main.subCommands
• ESLint clean (project-wide; 1 pre-existing unrelated error outside this PR)
• 66/66 skills-related tests pass
• Manual smoke on a real ask skills install github:...@v... in a project with .claude/ + .cursor/
• Windows native junction fallback (deferred)

Design notes

• Why symlinks, not copies: agents share one .ask/skills/<key>/ vendored copy; avoids byte duplication and keeps versions in sync.
• Why lock file: scanning agent dirs at remove time would either over-delete user skills or under-delete (if the agent set changes). Lock is authoritative.
• Why .ask/skills/<spec-key>/<name>/ layout: name collisions between libraries resolve via the spec-key namespace; remove is a single rm -rf.
• <spec-key> encoding: / and : → __, @ kept. Grep-friendly, reversible.

See the full plan at .please/docs/tracks/active/ask-skills-command-20260414/plan.md.

---

Summary by cubic

Adds a new ask skills CLI namespace to list, install, and remove producer-side skills from libraries. Skills are vendored into .ask/skills/, symlinked into detected agents, and tracked via a lock file; also fixes ignore patching for skills-only projects. Aligns with Linear #86.

• New Features

  • ask skills [list] <spec> prints candidate skill paths from node_modules/<pkg>/ and the cached checkout.
  • ask skills install <spec> vendors into .ask/skills/<spec-key>/<skill-name>/ and symlinks into detected agents (.claude/skills/, .cursor/skills/, .opencode/skills/, .codex/skills/). Supports --agent, --force, --no-fetch.
  • ask skills remove <spec> reverses install via .ask/skills-lock.json; only unlinks symlinks that point to the vendored target.
  • Auto-detects agents and prompts if more than one is present; ask skills <spec> is shorthand for skills list.
  • Ignore markers cover .ask/skills/ and .ask/skills-lock.json. Uses relative POSIX symlinks; Windows junction fallback deferred.

• Bug Fixes

  • Ignore file management now treats skills usage as opt-in. If .ask/skills/ or .ask/skills-lock.json exists, .gitignore and friends are patched even without an ask.json, preventing vendored skills from being committed.

^{Written for commit 038c926. Summary will update on new commits.}

Verification Checklist

• bun run --cwd packages/cli lint — zero errors
• bun run --cwd packages/cli test — 67/67 skills tests pass
• Integration test covers install → idempotent reinstall → remove on synthetic checkout
• Integration regression test covers skills-only (no ask.json) ignore-file patching
• AC-1 through AC-7 each covered by at least one automated test
• Manual smoke on a real ask skills install github:...@v... against a project with both .claude/ and .cursor/ markers
• Windows native junction fallback (deferred to follow-up track)

[codecov]

Codecov Report

❌ Patch coverage is 87.45387% with 68 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/cli/src/commands/skills/install.ts	75.16%	38 Missing ⚠️
packages/cli/src/commands/skills/index.ts	71.87%	9 Missing ⚠️
packages/cli/src/commands/skills/remove.ts	86.44%	8 Missing ⚠️
packages/cli/src/commands/skills/list.ts	90.76%	6 Missing ⚠️
packages/cli/src/ignore-files.ts	75.00%	4 Missing ⚠️
packages/cli/src/commands/find-skill-paths.ts	97.61%	1 Missing ⚠️
packages/cli/src/skills/spec-key.ts	95.00%	1 Missing ⚠️
packages/cli/src/skills/vendor.ts	96.87%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[cloudflare-workers-and-pages]

Deploying ask-registry with    Cloudflare Pages

Latest commit:	038c926
Status:	✅  Deploy successful!
Preview URL:	https://02bcafc6.ask-registry.pages.dev
Branch Preview URL:	https://amondnet-solar-boysenberry.ask-registry.pages.dev

View logs

[cubic-dev-ai]

0 issues found across 4 files (changes from recent commits).

_{Requires human review: Significant new feature (ask skills) with complex filesystem logic (symlinks, lock files) and a large line count (1960), requiring human architectural review.}

[cubic-dev-ai]

No issues found across 29 files

_{Requires human review: Significant new feature (1900+ lines) adding filesystem mutations, symlinking logic, and lock file management; requires human validation of the architectural implementation.}

Architecture diagram

sequenceDiagram
    participant User as CLI User
    participant CLI as Skills Command Logic
    participant Res as Resolver (ensureCheckout)
    participant FS as Local Filesystem (.ask/)
    participant Agents as Agent Dirs (.claude, .cursor, etc)

    Note over User,Agents: NEW: ask skills install [spec] Flow

    User->>CLI: ask skills install <spec>
    CLI->>Res: resolve and fetch spec
    alt Cache Miss & --no-fetch
        Res-->>CLI: NoCacheError
        CLI-->>User: Exit 1
    else Success
        Res-->>CLI: checkout directory path
    end

    CLI->>CLI: NEW: findSkillLikePaths(checkout)
    
    CLI->>CLI: NEW: detectAgents(projectDir)
    alt Multiple Agents Found
        CLI->>User: consola.prompt (multiselect)
        User-->>CLI: selected agents (e.g., claude, cursor)
    else Zero Agents Found
        CLI-->>User: Error: No agents detected
    end

    rect rgb(240, 240, 240)
        Note over CLI,FS: Atomic Vendoring
        CLI->>FS: NEW: vendorSkills()
        FS->>FS: Create .ask/skills/<spec-key>/.tmp
        FS->>FS: Copy source skills to .tmp
        FS->>FS: Rename .tmp to canonical path
    end

    loop For each Skill and Selected Agent
        CLI->>Agents: NEW: linkSkill()
        Agents->>Agents: Create relative POSIX symlink to .ask/skills/
    end

    CLI->>FS: NEW: writeLockAtomic(.ask/skills-lock.json)
    CLI->>FS: CHANGED: manageIgnoreFiles()
    Note right of FS: Patches .gitignore, .prettierignore, etc.
    
    CLI-->>User: Success Summary

    Note over User,Agents: NEW: ask skills remove [spec] Flow

    User->>CLI: ask skills remove <spec>
    CLI->>FS: readLock()
    FS-->>CLI: Lock entries (spec, skills, agents)
    
    loop For each recorded Symlink in Lock
        CLI->>Agents: NEW: unlinkIfOwned()
        Note right of Agents: Only unlinks if target matches vendor path
    end

    CLI->>FS: NEW: removeVendorDir()
    CLI->>FS: writeLockAtomic() (remove entry)
    CLI-->>User: Success message

Loading