skills/skills/update-skills/SKILL.md

name, author, version, description

name	author	version	description
update-skills	ours	0.2.1	Full uplift cycle for an existing skills installation: git pull, conditionally rebuild MCP servers, install skills, show version diff, suggest reload. Trigger on "update skills", "sync skills", "обнови skills", "обнови всё", or when the user wants to bring their skills up to date. Cross-platform (PowerShell on Windows, bash on Linux/macOS). Does NOT handle greenfield bootstrap — that's project-bootstrap's job.

update-skills

One command to bring your skills installation fully up to date — repo, MCP servers, skills, and version diff.

When this runs

On explicit trigger — when the user says any of: update skills, sync skills, обнови skills, обнови всё, update skills, or close variants asking to refresh the skills catalog.

Never automatically at session start (that's pulling-before-work's job for the git part). This skill is for the full uplift cycle — git + build + install + diff — which is heavier and intentional.

Process

1. Detect platform

Determine which script to run:

• Windows (PowerShell): pwsh ~/projects/skills/scripts/update.ps1
• Linux / macOS: bash ~/projects/skills/scripts/update.sh

Use the active-platform skill's detection if available. Otherwise:

• If $env:OS is Windows_NT or IsWindows is true → PowerShell path.
• Otherwise → bash path.

If the repo is at a non-default location, adjust the path accordingly (the user may have cloned to ~/projects/skills or another directory — check git -C <path> rev-parse --is-inside-work-tree if unsure).

2. Run the update script

Execute the appropriate script. Show the output to the user — it contains version diffs and reload hints.

If the script exits non-zero, stop and show the error. Common failures:

• git pull --ff-only fails → the repo has diverged or there's no upstream. The user must resolve manually.
• MCP build fails → show the error, suggest running npm run build / pip install -e . manually.

3. Offer to reload MCP servers

If the script output mentions "MCP servers rebuilt" or "source changed":

MCP servers were rebuilt. Run /reload-mcp to reload them.

If no MCP changes:

Skills updated. Start a new session (or /clear) for changes to take full effect.

Both agents pick up the new catalog on their next session: Claude Code reads ~/.claude/skills natively; pi reads ~/.agents/skills natively (default scan path — no settings needed). See "Install targets" below.

4. Offer to run new setup skills

If the script detected new setup-* skills that aren't yet installed:

New setup skills available: <list>. Want me to run any of them?

The user decides — never auto-run setup skills.

Install targets (dual, agent-neutral)

The canon is the git repo — skills/<name>/SKILL.md. install.sh / install.ps1 install into both agent dirs (identical copies, synced by the script — no drift):

Target	Agent	Why
~/.claude/skills	Claude Code	Claude Code reads this natively; custom skill dirs are NOT configurable in Claude Code (only plugin skillsPaths)
~/.agents/skills	pi	pi reads this natively (default scan path); the agent-neutral .agents/ namespace is our convention

$CLAUDE_SKILLS_DIR / $env:CLAUDE_SKILLS_DIR overrides only the claude target (for testing/CI). pi must NOT have ~/.claude/skills in its settings skills array — that was the old vendor-locked setup; pi loads ~/.agents/skills by default. Verify with pi --help / a fresh session listing skills.

What the scripts do

The update scripts (scripts/update.sh and scripts/update.ps1) handle:

1. git pull --ff-only in ~/projects/skills/ (stash if dirty, pop after).
2. Conditionally rebuild projects-meta-mcp — if ~/projects/.common/lib/projects-meta-mcp/ has a .git directory and source changed (git pull fetched new commits), run npm run build.
3. Conditionally rebuild interns-mcp — same pattern, pip install -e ..
4. Install all skills via install.sh / install.ps1.
5. Show version diff — before/after version: frontmatter for each skill.
6. Print reload hints — /reload-mcp if MCP changed, new session otherwise.

Out of scope

• Greenfield bootstrap — use project-bootstrap for first-time setup on a new machine.
• --prune flag — removing skills not in skills/ from the install targets (both ~/.claude/skills/ and ~/.agents/skills/). Tracked separately in [install-ps1].
• Hermes-side update — hermes-installer-skill handles the Hermes/Linux factory path.
• Auto-run setup skills — the user decides which new setup skills to configure.

Cross-agent applicability

Pure orchestration — calls platform scripts, no Claude-specific tool references. Hermes-mappable as mode: skip (Claude-Code-only; Hermes uses hermes-installer-skill instead).