feat(manager): implement upskill/manager — unified skill inventory [v1.1+]

[ngouy]

upskill/manager — Implementation Brief

Deferred to v1.1+. v1 focuses on publisher (#2) and doctor (#3).

What This Is

manager is the unified inventory layer for all installed Claude Code skills. It provides a single view of every skill on the user's machine — regardless of whether it came from a plugin, a global local file, or a project's .claude/skills/ directory.

Reference: VISION.md → Section "upskill/manager"
Session structure: brainstorm → plan → implement → review (do not skip or combine)

---

The Core Problem It Solves

Today, Claude Code users have three categories of skills with no unified view:

1. Plugin-installed skills — installed via /plugin install, managed by Claude Code, live in ~/.claude/plugins/cache/
2. Global local skills — raw markdown files in ~/.claude/skills/, not managed by anything
3. Project-level skills — skills in <project>/.claude/skills/, shared via the repo with the whole team

There is no single place to see everything that's loaded, where it came from, and when it was last updated. /plugin list only shows plugins — not global or project skills.

manager fixes this by presenting one unified inventory — the source differences are implementation details, not user concerns.

---

Capability Set

1. List / Inventory

Show all installed skills with rich metadata in a structured table:

• Skill name
• Source: plugin, local (global), or project
• Version: semver for plugins, (untracked) for local/project files with no git history, git short SHA if in a git repo
• Last updated: human-readable relative time
• Update available badge when detected

Example output format:

┌─────────────────────────────────────────────────────────────────────┐
│ INSTALLED SKILLS                                          2 plugins  │
├──────────────────────┬────────────┬────────────┬───────────────────┤
│ Skill                │ Source     │ Version    │ Last Updated       │
├──────────────────────┼────────────┼────────────┼───────────────────┤
│ manager              │ plugin     │ 1.2.0      │ 3 days ago         │
│ my-custom-workflow   │ local      │ (untracked)│ 12 days ago        │
│ deploy-helper        │ project    │ a3f29c1    │ 2 days ago         │
│ commit               │ plugin     │ 2.0.1      │ 1 week ago         │
└──────────────────────┴────────────┴────────────┴───────────────────┘

[!] 1 update available: commit (2.0.1 → 2.1.0)

For local (untracked) skills, manager surfaces the lack of version history — a natural prompt toward publisher.

2. Bulk Operations

Manager adds value over raw /plugin commands by orchestrating multi-plugin operations:

• Update all: "Update all my skills" — runs updates across all installed plugins in one pass, shows a consolidated summary of what changed (including RELEASE-NOTES.md diffs where available)
• Post-install nudge: After any install, offer to run doctor on the newly installed plugin — the security gate moment. User can decline.

Manager does not wrap individual /plugin install or /plugin remove — those work fine as-is via Claude Code's built-in commands.

3. Periodic Update Nudge (via Claude Code hook)

Manager can help the user set up a Claude Code hook (~/.claude/hooks/) that checks for plugin updates at session start. The hook runs outside of the skill system and feeds its output back into the session.

• Hook setup is optional and user-initiated ("set up update notifications")
• The hook reads ~/.claude/upskill-state.json to determine when to check (respects nudgeConfig.enabled and nudgeConfig.intervalSessions)
• Manager explains what the hook does before installing it
• Skills are passive instructions, not code — the hook is how proactive behavior works

4. Watermark Management

If watermark.enabled: true in state file (opt-in, default false), manager ensures user-owned skills have the maintained-with frontmatter field. If the user disables it, manager can strip existing watermarks. Never touches third-party skills.

---

What manager Must Never Do

• Never modify skill files directly beyond watermark management — that's doctor's job
• Never surface security findings — that's doctor and auditor's job
• Never install hooks without explaining what they do and getting user confirmation
• Never add watermark to third-party skills

---

When to Use (trigger signals for SKILL.md description)

• User wants to see what skills or plugins are installed
• User asks what's loaded, what version something is, or what's available
• User asks about skill sources (plugin vs. local vs. project)
• User wants to update all plugins at once
• User wants to set up or configure update notifications

---

State File (manager is the primary writer)

{
  "version": "1",
  "sessionsUntilNextNudge": 10,
  "lastUpdateCheck": "2026-01-15T10:30:00Z",
  "installedPlugins": {
    "author/plugin-name": {
      "installedVersion": "1.2.0",
      "lastChecked": "2026-01-15T10:30:00Z",
      "latestKnownVersion": "1.2.0"
    }
  },
  "nudgeConfig": {
    "intervalSessions": 10,
    "enabled": true
  },
  "watermark": {
    "enabled": false
  }
}

---

Quality Gate

Before this skill is considered done:

• Passes doctor --curator with zero CRITICAL or HIGH findings
• Output table format matches the example above
• Shows all three skill sources (plugin, local, project)
• Hook setup works and respects nudgeConfig
• State file created correctly on first use
• Token footprint target: ~300 tokens (verify with character count)

[ngouy]

Review update — deferred to v1.1+

Following a critical design review (#5), manager has been deferred to v1.1+. v1 focuses on publisher and doctor as the two highest-value skills.

Changes to manager's design (captured in VISION.md via #5):

• Install/remove/update wrappers cut. These just duplicated built-in /plugin install, /plugin remove, /plugin update commands. Manager no longer wraps them.
• Kept: Unified inventory (the unique value — one list across plugins, global skills, and project skills) and bulk update orchestration.
• Periodic nudge now via Claude Code hook. Skills are passive instructions and can't run at session start. Manager helps the user set up an optional hook instead.
• Project-level .claude/skills/ is first-class. The inventory shows three sources: plugin, local (global), project. This was a gap in the original spec.
• Watermark management simplified. Watermark is now opt-in (default false), asked during publisher scaffold.

Open questions resolved:

• Q1 (update detection): Hook-based, reads state file, checks GitHub API
• Q2 (installed plugin paths): Still needs confirmation during brainstorm
• Q4 (untracked UX): Show (untracked), natural prompt toward publisher
• Q5 (watermark stripping): Ask user before stripping existing watermarks