Vibes

agent-dotfiles

Dotfiles for AI coding agents: one versioned repo that makes any machine, running any supported harness, behave like the same agent.

Portable Agent Skills form the common core and remain individually installable. Canonical instructions, hooks, agents, settings, and MCP declarations are the other managed layers, deployed at user scope via APM plus a thin sync wrapper. Product requirements: docs/PRD.md; technical design: docs/SPEC.md.

Install Skills

Browse the collection and select individual skills:

npx skills add jonhill90/agent-dotfiles

Install a specific skill:

npx skills add jonhill90/agent-dotfiles --skill primer

First-class harnesses: Claude Code, Codex, GitHub Copilot, Pi — all four sync-managed and eval-verified; breakage on any of them blocks release. Other Agent Skills-compatible harnesses may work through the same installer.

Repository Model

apm.yml          APM package manifest (user-scope deployment)
.apm/            APM source tree — symlinks into the canonical directories
skills/          Portable Agent Skills source
instructions/    Canonical global agent instructions + per-harness overlays
agents/          Reusable agent definitions
hooks/           Canonical hook scripts, harness-agnostic
settings/        Wrapper-owned config fragments (claude, pi, mcp)
docs/            Living product, architecture, memory, and eval documentation
.claude/         Claude-specific repo-development configuration and hooks
.github/         GitHub Copilot instructions and repository automation

Canonical content lives in the top-level directories. Deployment is installer-owned: apm install -g places skills/instructions/agents at user scope and scripts/sync.py apply covers what APM does not (Pi projection, settings merges, teardown). The committed symlink matrix is retired (SPEC §2).

Core Workflow Skills

Skill	Purpose
using-tmux	Operate persistent interactive terminal sessions safely
create-skill	Design and validate portable skills with progressive disclosure

Additional skills integrate with GitHub, Azure DevOps, Linear, and Obsidian. Install them selectively to avoid overlapping triggers and unnecessary context. primer and closing-the-loop remain independently installable but are not part of the default APM package because the baseline evals did not justify their static description cost.

The behavioral layer is deliberately minimal: loop discipline lives in the canonical instructions, and skills are added only when a failing eval justifies them (baseline-first rule — see docs/SPEC.md §4). Each kept tool skill has acceptance checks under tests/evals/acceptance/.

Authoring Contract

Each skill lives at skills/<name>/SKILL.md:

skills/example-skill/
├── SKILL.md
├── scripts/       Optional deterministic helpers
├── references/    Optional detail loaded on demand
└── assets/        Optional output resources

Portable skills use name and description frontmatter. The directory name must match name. Keep the core instructions concise and move detail into directly linked references.

Validate the repository:

python3 scripts/validate_repository.py
python3 -m unittest discover -s tests -v

Distribution Direction

Two installation layers are intentional:

• npx skills installs independent public skills.
• APM installs the whole repo as a user-scope package (apm install -g), the backbone of the personal sync design (SPEC §1).

Content Boundaries

• Generic personal workflow improvements should originate here.
• Project-specific deployment and operational policy remains in its project.
• Employer repository material is research input only and is not copied, migrated, or adapted into this repository.

See docs/provenance-manifest.md for every adopt/adapt/author/reject decision (and its predecessor, docs/migration-audit.md, for the original skill migration).

See AGENTS.md for contribution rules.