Kind: foundation
Effort: L · Risk: med
Source: paulirish/dotfiles (run 2026-08-23)
Decision: spike
Problem
Using one skill on another machine means cloning the entire personal dotfiles repo.
Current state (this repo)
Skills are consumed by symlink: ~/.claude/skills and home/.gemini/antigravity-cli/skills point into home/.agents/skills, and deploy.sh is what puts them there. The unit of sharing is the whole repo — a fresh VM, a work machine or a collaborator gets everything or nothing. home/.agents/rules/workflow.md already asserts that reusable artifacts must be committed into the package they serve, parameterized and scrubbed; today the only package on offer is this entire tree.
Their approach
agents/ is a self-contained versioned package — @paulirish/agents, with its own package.json, tsconfig.json, README, .npmignore and dependency set — installable one skill at a time via npx skills add paulirish/dotfiles/agents --skill <name>, with no dotfiles involved.
Difference that matters
The unit of distribution. This is foundation rather than leaf because home/.agents would stop being purely a deploy source and become a published artifact with a version, a changelog and a compatibility contract — which in turn constrains how freely rules and skills can be renamed, the very thing check-copilot-instructions and check-pi-agents exist to police.
Translation into this repo
Add package metadata under home/.agents (or a thin agents/ wrapper) so the vercel skills CLI can resolve a single skill by name from this repo, without disturbing the symlink deploy path that manifest and deploy.sh already own. The two must coexist: local deploy stays the primary consumer.
Pilot slice
Pick the one skill with zero coupling to this repo — prose-register or code-review-register, both pure prose with no scripts — add the minimal metadata, and verify it installs into a scratch directory from a clean checkout. Explicitly not find-inspiration: its triage-issues.py hardcodes REPO = "nonrational/dotfiles" and would need parameterizing first. Reversible — the metadata is additive; delete it if the CLI cannot resolve a nested path.
Spike question
Can the vercel skills CLI install a single skill from a nested path in this repo (nonrational/dotfiles/home/.agents), or does it require the package at a repo root? If nested paths do not resolve, the cost jumps from adding metadata to restructuring the tree that manifest and four harness symlinks depend on. Second half: what compatibility contract does publishing impose on renaming rules and skills, given that renames here have already broken the copilot and Pi mirrors twice?
Kind: foundation
Effort: L · Risk: med
Source: paulirish/dotfiles (run 2026-08-23)
Decision: spike
Problem
Using one skill on another machine means cloning the entire personal dotfiles repo.
Current state (this repo)
Skills are consumed by symlink:
~/.claude/skillsandhome/.gemini/antigravity-cli/skillspoint intohome/.agents/skills, anddeploy.shis what puts them there. The unit of sharing is the whole repo — a fresh VM, a work machine or a collaborator gets everything or nothing.home/.agents/rules/workflow.mdalready asserts that reusable artifacts must be committed into the package they serve, parameterized and scrubbed; today the only package on offer is this entire tree.Their approach
agents/is a self-contained versioned package —@paulirish/agents, with its ownpackage.json,tsconfig.json, README,.npmignoreand dependency set — installable one skill at a time vianpx skills add paulirish/dotfiles/agents --skill <name>, with no dotfiles involved.Difference that matters
The unit of distribution. This is foundation rather than leaf because
home/.agentswould stop being purely a deploy source and become a published artifact with a version, a changelog and a compatibility contract — which in turn constrains how freely rules and skills can be renamed, the very thingcheck-copilot-instructionsandcheck-pi-agentsexist to police.Translation into this repo
Add package metadata under
home/.agents(or a thinagents/wrapper) so the vercelskillsCLI can resolve a single skill by name from this repo, without disturbing the symlink deploy path thatmanifestanddeploy.shalready own. The two must coexist: local deploy stays the primary consumer.Pilot slice
Pick the one skill with zero coupling to this repo —
prose-registerorcode-review-register, both pure prose with no scripts — add the minimal metadata, and verify it installs into a scratch directory from a clean checkout. Explicitly notfind-inspiration: itstriage-issues.pyhardcodesREPO = "nonrational/dotfiles"and would need parameterizing first. Reversible — the metadata is additive; delete it if the CLI cannot resolve a nested path.Spike question
Can the vercel
skillsCLI install a single skill from a nested path in this repo (nonrational/dotfiles/home/.agents), or does it require the package at a repo root? If nested paths do not resolve, the cost jumps from adding metadata to restructuring the tree thatmanifestand four harness symlinks depend on. Second half: what compatibility contract does publishing impose on renaming rules and skills, given that renames here have already broken the copilot and Pi mirrors twice?