Persops Install Skills
Skills live in ~/p/persops/modules/ai/skills/<name>/. Nix links each one into
the agent skill dirs; .claude-plugin/marketplace.json ships a subset to
claude.ai and cloud sessions as plugins.
Where a skill goes
- Profile (
modules/ai/skill-overrides.json, defaultall):all:~/.claude/skills,~/.agents/skills,~/.pi/agent/skills.codex:~/.agents/skillsonly. Use when the user asks for Codex-only.- Other per-skill keys:
recursive = true.
- Host gating (
modules/ai/home.nix):personalOnlySkillsstay off ergane;darwinOnlySkillsstay off amalthea. - Marketplace plugin (
.claude-plugin/marketplace.json):persops: general thinking, review, writing, PR workflow.persops-web: TypeScript, React, TUI frameworks.persops-jj: jj workflows.- Leave out machine-only skills (they need local tools, secrets, or hosts: one-password, share-page, rex, session-viewer, persops-install-skills).
- Every plugin entry keeps
"strict": false(no plugin.json; claude.ai sync rejects entries without it).
Add
jj status, then readmodules/ai/home.nix,skill-overrides.json, the marketplace, and any skill dir you will touch.- Health-check upstream (
gh repo view <owner/repo> --json pushedAt,stargazerCount,url). modules/ai/scripts/add-skill.sh [--profile all|codex] <source> [skills-add args...]- Example:
modules/ai/scripts/add-skill.sh https://github.com/shadcn/ui --skill shadcn - GitHub
blob/treeURLs must point at a skill dir or itsSKILL.md; the helper pins the commit and records it inUPSTREAM.txt. - It refuses the whole batch if any destination exists; update existing skills by hand.
- Example:
- Review the vendored files and
UPSTREAM.txt. Record local edits there aslocal_patch_<date> = .... - Add the skill to the right marketplace plugin, or note why it is machine-only.
Update, remove, rename
- Edit in place and log the change in
UPSTREAM.txt. Keepagents/openai.yamlin step withSKILL.md. - Removing: delete the dir, its
skill-overrides.jsonentry, its marketplace path, and any host-gating list entry.rg '<name>'across the repo for links from other skills (../<name>/...,$<name>) and fix them. - Renaming: same as remove + add; update the
name:frontmatter.
Verify and deploy
python3 -m json.tool .claude-plugin/marketplace.json >/dev/nulland check every marketplace path exists.make check.- Deploy to the personal hosts the controller can reach: from aglaea
make deploy TARGETS="aglaea amalthea"; from amaltheamake deploy TARGETS=amalthea, then aglaea switches on its own. Never ergane unless asked. - Check the links on each host:
~/.claude/skills/<name>,~/.agents/skills/<name>,~/.pi/agent/skills/<name>(only the dirs its profile includes; a removed skill should be gone from all three). - Commit with a Conventional Commit. Push or PR only when asked.
make deploy snapshots a path: flake, so uncommitted new skill files deploy
consistently on every target.