feat: add skilld prepare command for package.json hooks

[harlan-zw]

❓ Type of change

• 📖 Documentation
• 🐞 Bug fix
• 👌 Enhancement
• ✨ New feature
• 🧹 Chore
• ⚠️ Breaking change

📚 Description

Improves integration with packages that publish their own skills via the skills-npm convention, and keeps installed skills in sync with node_modules.

Adds skilld prepare, a lightweight, blocking command designed for package.json prepare hooks. Unlike the previous skilld update -b recommendation (which ran the full LLM pipeline in the background), skilld prepare does three things fast and without any LLM calls:

1. Restores broken .skilld/pkg symlinks from the lockfile (e.g. after pnpm install recreates node_modules)
2. Auto-installs shipped skills from dependencies that publish a skills/ directory
3. Reports how many packages have new features or breaking changes and suggests running skilld update

Also extracts the "add prepare hook" suggestion into a shared suggestPrepareHook() helper and surfaces it after skilld add, skilld update, and multi-package sync completions, so users discover the hook earlier.

Summary by CodeRabbit

• New Features

  • Added skilld prepare to restore references, install shipped skills, and report outdated packages
  • CLI now detects available "shipped" skills, shows a shipped-skills summary during setup, and lets you install them from setup or the main menu
  • CLI suggests adding a prepare hook after sync/setup operations

• Documentation

  • Updated README to recommend skilld prepare in package.json and clarify its role vs skilld update

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: afb67448-a77b-4b1d-aee9-c71f9e162d8b

📥 Commits

Reviewing files that changed from the base of the PR and between 4b77e27 and a300e78.

📒 Files selected for processing (1)

• src/commands/prepare.ts

---

📝 Walkthrough

Walkthrough

Introduces a new skilld prepare CLI subcommand (package.json hook) that restores symlinks, syncs shipped skills from dependencies into the project skills directory, and reports outdated items. Adds CLI integration, project-state shipped-skill discovery, a prepare helper suggestion, and documentation updates.

Changes

Cohort / File(s)	Summary
Documentation CLAUDE.md, README.md	Added skilld prepare docs; replaced skilld update -b with skilld prepare in prepare hook guidance; updated FAQ to direct prepare vs update responsibilities.
CLI Helper Infrastructure src/cli-helpers.ts	Added exported suggestPrepareHook(cwd?: string): boolean to detect/advise adding skilld prepare to package.json prepare script.
CLI Command Registration & UI src/cli.ts	Registered new prepare subcommand; added shipped-skills flow into initial setup and main menu; uses suggestPrepareHook for prepare-hook messaging.
Prepare Command Implementation src/commands/prepare.ts	New exported prepareCommandDef implementing: restore per-skill lock symlinks, link shipped skills into skillsDir (with lock metadata), optionally link to agent shared dir, and report outdated skills. Adds restorePkgSymlink helper.
Sync Integration src/commands/sync.ts, src/commands/sync-parallel.ts	Invoke suggestPrepareHook(cwd) after sync completion to suggest adding the prepare hook.
Core State & Types src/core/skills.ts	Added AvailableShippedSkill type and ProjectState.shipped field; updated getProjectState() to compute available shipped skills from dependencies and exclude already-installed skills.

Sequence Diagram

sequenceDiagram
    participant CLI as CLI (skilld prepare)
    participant State as getProjectState
    participant FS as Filesystem
    participant Symlink as Symlink Ops
    participant Deps as Dependency Packages

    CLI->>FS: read per-skill lockfiles
    CLI->>Symlink: restore or recreate `.skilld/pkg` symlinks
    Symlink->>FS: verify/create links

    CLI->>State: load current project state (includes shipped)
    CLI->>Deps: for each shipped dependency skill -> link into skillsDir
    Deps->>FS: create skill dir/link and write lock entry (source: 'shipped')

    CLI->>State: re-read project state (post-install)
    State-->>CLI: return updated state with `shipped`
    CLI->>CLI: log count of outdated skills (suggest `skilld update`)

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

A rabbit hops and hums a tune, 🐇
Restoring paths beneath the moon,
Shipped skills land in tidy rows,
Symlinks click where the project grows,
I nudge prepare — then off I zoom!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main feature: adding a new skilld prepare command for package.json hooks, which is the primary objective of the PR.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/skilld-prepare

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}