.agents

Centralized configuration for AI coding agents. Manages shared and agent-specific configs for Claude Code and Pi.

Setup

git clone [email protected]:ivanrvpereira/.agents.git ~/.agents
~/.agents/bin/sync --bootstrap
npx skills update -g  # restore external skills

Structure

AGENTS.md          # Project knowledge base (symlinked as CLAUDE.md context)
_agents.md         # Shared agent instructions (symlinked to both agents)
_claude.md         # Claude wrapper (@AGENTS.md + Exa tools)
CLAUDE.md          # Project-level CLAUDE.md (@AGENTS.md)
.skill-lock.json   # Tracks external skills for updates
bin/sync           # Unified symlink manager
bin/add-skill      # Validate a local skill before syncing
skills/            # Shared skills (Claude symlinks; Pi auto-discovers)
claude/            # Claude Code configs (settings, commands, scripts)
pi/                # Pi configs (settings, extensions, skills)

Usage

# Sync configs to agent directories
bin/sync

# Preview changes
bin/sync --dry-run

# Sync + install Claude Code plugins
bin/sync --bootstrap

# Remove stale symlinks
bin/sync --prune

# Validate a local skill before syncing
bin/add-skill my-skill

# Add an external skill
npx skills add owner/repo -g

# Update all external skills
npx skills update -g

Skills

All skills live in skills/. They are symlinked to Claude Code and auto-discovered by Pi from ~/.agents/skills (since Pi v0.54.0).

Local (hand-crafted)

Skill	Description
`agents-md`	Generate/review AGENTS.md files
`brainstorming`	Explore intent and design before creative work
`crwl`	Web crawling with Crawl4AI CLI
`git-commit`	Conventional, focused, reviewable git commits
`hcloud`	Hetzner Cloud infrastructure via hcloud CLI
`handoff`	Write or update HANDOFF.md for a fresh agent
`marp`	Slide presentations from Markdown
`marker`	Parse documents (PDF, images, PPTX, DOCX, XLSX, HTML, EPUB) to markdown via marker-pdf
`prd`	Generate Product Requirements Documents
`receiving-code-review`	Process code review feedback rigorously
`requesting-code-review`	Request review before completing major work
`skill-creator`	Guide for creating new skills
`using-git-worktrees`	Isolate feature work with git worktrees

Remote (via `npx skills`, tracked in `.skill-lock.json`)

Skill	Description	Source
`deep-research`	Multi-source research with citation tracking and verification	199-biotechnologies/claude-deep-research-skill
`dev-browser`	Browser automation with persistent page state	SawyerHood/dev-browser
`frontend-design`	Design and implement production-ready frontend interfaces	mitsuhiko/agent-stuff
`github`	GitHub operations via `gh` CLI (issues, PRs, CI runs, API)	mitsuhiko/agent-stuff
`mermaid`	Create and edit Mermaid diagrams with validation	mitsuhiko/agent-stuff
`sentry`	Fetch and analyze Sentry issues, events, and logs	mitsuhiko/agent-stuff
`summarize`	Fetch a URL or convert files (PDF/DOCX/HTML) to Markdown	mitsuhiko/agent-stuff
`tmux`	Remote control tmux sessions for interactive CLIs	mitsuhiko/agent-stuff
`uv`	Python package and script management with `uv`	mitsuhiko/agent-stuff
`vercel-composition-patterns`	React composition patterns (compound components, render props, context)	vercel-labs/agent-skills
`vercel-react-best-practices`	React and Next.js performance optimization guidelines	vercel-labs/agent-skills
`web-design-guidelines`	Review UI for accessibility, design, and UX best practices	vercel-labs/agent-skills

To update remote skills: npx skills update -g

Adding a new skill

Create a directory under skills/ with a SKILL.md file:

skills/my-skill/
└── SKILL.md

Then run bin/sync to link it into Claude Code. Pi discovers ~/.agents/skills directly.

Adding agent-specific content

Claude Code: Add files under claude/ (commands, scripts)
Pi: Add extensions under pi/extensions/, skills under pi/skills/