Agent Almanac

A library of executable skills, specialist agents, and pre-built teams for Claude Code and compatible AI tools. Define repeatable engineering procedures once and have AI agents execute them with built-in validation and error recovery. Compose specialists into review teams that catch issues a single reviewer would miss. Built on the Agent Skills open standard.

At a Glance

• 371 skills across 66 domains — structured, executable procedures
• 75 agents — specialized Claude Code personas covering development, review, compliance, and more
• 22 teams — predefined multi-agent compositions for complex workflows
• 35 guides — human-readable documentation across workflow, infrastructure, reference, design, and investigation
• Interactive visualization — force-graph explorer with 371 R-generated skill icons and 9 color themes

How It Works

Ask Claude Code to review your R package, and the r-package-review team activates 4 agents — each following specialized skills for code quality, architecture, security, and best practices — then synthesizes their findings into a single report.

Works with

Skills follow the Agent Skills open standard and work with any tool that reads markdown:

Agents and teams use Claude Code's subagent architecture. For other tools, skills are the primary integration surface. See skills/README.md for setup instructions.

Quick Start

Choose a path. Full per-OS runbook with prereqs, verification, and updating: Installation guide.

Path 1 — Reference a skill (zero install)

> "Follow skills/commit-changes/SKILL.md to stage and commit my changes"

Path 2 — Claude Code plugin (recommended)

git clone https://github.com/pjt222/agent-almanac.git ~/dev/agent-almanac

# One-time local marketplace setup
mkdir -p ~/.claude-marketplace/{plugins,.claude-plugin}
cat > ~/.claude-marketplace/.claude-plugin/marketplace.json << 'EOF'
{
  "name": "local",
  "owner": { "name": "self" },
  "plugins": [{
    "name": "agent-almanac",
    "source": "./plugins/agent-almanac",
    "category": "development"
  }]
}
EOF
ln -s ~/dev/agent-almanac ~/.claude-marketplace/plugins/agent-almanac

claude plugin marketplace add ~/.claude-marketplace
claude plugin install agent-almanac@local

Auto-discovers all 371 skills and 75 agents. To use a team, read its definition in teams/<name>.md and spawn each listed member as a subagent via the Agent tool (subagent_type), coordinating them with SendMessage under the session's single implicit team. Windows / macOS variants in the Installation guide.

Path 3 — Global CLI (cross-framework)

Requires Node.js 22.12.0 or newer. The floor was raised when the CLI moved to commander 15. npm install only warns on an engine mismatch rather than failing, so on Node 18 or 20 the install appears to succeed and the CLI then cannot start — check with node --version first.

npm install -g agent-almanac
agent-almanac detect              # show frameworks in cwd
agent-almanac install commit-changes

Reaches 12+ frameworks: Claude Code, Cursor, Codex, Gemini, Aider, OpenCode, Windsurf, Vibe, Hermes, OpenClaw. See cli/README.md.

Verify

cd ~/dev/agent-almanac
npm install && npm test           # repo integrity + README freshness
claude plugin list | grep agent-almanac

In a fresh Claude Code session, type /commit-changes — should resolve. Empty result → see Installation troubleshooting.

Explore visually

cd viz && npm install && bash build.sh && npm run dev
# Open http://localhost:5173 for the interactive force-graph explorer

Requires R 4.5.x or Docker; per-OS R paths in the Installation guide. See viz/README.md for build internals.

Directory Map

agent-almanac/
  .claude-plugin/  Plugin manifest for Claude Code plugin installation
  skills/          371 executable procedures across 66 domains
  agents/          75 specialist personas
  teams/           22 multi-agent compositions with 8 coordination patterns
  guides/          35 human-readable reference docs
  viz/             Interactive force-graph explorer with R-generated icons
  tests/           30 test scenarios for validation
  i18n/            Translations (10 locales: de, zh-CN, ja, es, caveman-lite, caveman, caveman-ultra, wenyan-lite, wenyan, wenyan-ultra)
  cli/             Universal installer CLI (npm install -g agent-almanac)
  scripts/         Build and CI automation
  sessions/        Tending session archives

Guides

New here? Start with Understanding the System. See all guides for the full categorized list.

Workflow

• Understanding the System — Entry point: what skills, agents, and teams are, how they compose, and how to invoke them
• Creating Skills — Authoring, evolving, and reviewing skills following the agentskills.io standard
• Creating Agents and Teams — Designing agent personas, composing teams, and choosing coordination patterns
• Creating Workflows — Authoring code-driven orchestration workflows — the meta contract, the agent/parallel/pipeline/phase primitives, and the capability rule
• Coordinating Peer Sessions — Working safely when a second interactive session shares your worktree — declaring path scope before the first edit, index etiquette, and what the guard cannot see
• Running a Code Review — Multi-agent code review using review teams for R packages and web projects
• Managing a Scrum Sprint — Running Scrum sprints with the scrum-team: planning, dailies, review, and retro
• Visualizing Workflows with putior — End-to-end putior workflow visualization from annotation to themed Mermaid diagrams
• Running Tending — AI meta-cognitive tending sessions with the tending team
• Running a Translation Campaign — End-to-end guide for translating all skills, agents, teams, and guides into supported locales using the translation-campaign team
• Unleash the Agents — Structured multi-agent consultation at three tiers for open-ended hypothesis generation
• Team Assembly Prompt Patterns — How to phrase requests to Claude Code for multi-agent team work at every level of specificity
• Production Coordination Patterns — Real-world multi-agent orchestration patterns: barrier synchronization, silence budgets, health checks, degraded-wave policies, and cost-aware scheduling
• AgentSkills Alignment — Standards compliance audits using the agentskills-alignment team for format validation, spec drift detection, and registry integrity
• Edge Computing Deployment — Install agent-almanac skills on edge LLMs (Gemma 4 via AI Edge Gallery) with distilled content, token budgets, and offline bundles
• Self-Continuation Loops Playbook — Choose among ScheduleWakeup, CronCreate loops, and loop.md; select sentinels; plan for the 7-day age-out
• Headless WebGL Verification — Proving a WebGL/GPGPU/WebAudio app rendered in headless Chromium — SwiftShader/ANGLE flags, capability probes, pixel-luminance assertions, HMR traps
• Driving the Copilot Review Loop — Converging a PR to a clean GitHub Copilot review pass — thread IDs, the fix/reply/resolve/re-request cascade, and reading the bot's verdict

Infrastructure

• Installation — OS-aware install runbook covering plugin install, global CLI, prereqs, verification, and updating across Linux, macOS, Windows, WSL2, and Codespaces
• Setting Up Your Environment — WSL2 setup, shell config, MCP server integration, and Claude Code configuration
• Symlink Architecture — How symlinks enable multi-project discovery of skills, agents, and teams through Claude Code
• R Package Development — Package structure, testing, CRAN submission, pkgdown deployment, and renv management
• WSL Maintenance & Claude Code Reference — WSL2 vhdx disk reclamation, Claude Code permission modes, and periodic security-scan greps for a WSL-based dev environment
• Protecting GitHub Repositories — Honest threat model, tiered checklist, rulesets vs branch protection, and the CI-bot bypass problem for hardening a public GitHub repo

Reference

• Quick Reference — Command cheat sheet for agents, skills, teams, Git, R, and shell operations
• Agent Best Practices — Design principles, quality assurance, and maintenance guidelines for writing effective agents
• Agent Configuration Schema — YAML frontmatter field definitions, validation rules, and JSON Schema for agent files
• Content Styleguide — Canonical markdown formatting conventions for skills, agents, teams, and guides — tables, code fences, headings, lists, and links
• Choosing an HTR/OCR Engine — Decision framework for selecting a handwritten-text-recognition engine — deployment model, API entitlement, vision-LLM vs dedicated HTR, CER pitfalls
• The Caveman Spellbook — Six grunt-level compression modes for agent-almanac content — a homage to JuliusBrussee/caveman, from lite filler-stripping to extreme classical Chinese abbreviation

Design

• Extracting Project Essence — Multi-perspective framework for extracting skills, agents, and teams from any codebase using the metal skill
• Epigenetics-Inspired Activation Control — Runtime activation profiles controlling which agents, skills, and teams are expressed, grounded in molecular epigenetics
• Understanding the Synoptic Mind — The adaptic concept — panoramic synthesis through simultaneous multi-domain awareness, theoretical foundations, and practical use
• Agent Memory Hygiene — Three-layer model — weights, retrieval, behavior — for diagnosing what kind of forgetting a memory problem actually needs and applying the right tool

Investigation

• Reverse-Engineering a CLI Harness — Five-phase methodology for legitimate integration research against a closed-source CLI harness — baseline, flag discovery, dark-launch detection, wire capture, redaction discipline

Translations

See i18n/README.md for the translation contributor guide.

Plugin Packaging

Agent-almanac is packaged as a Claude Code plugin at .claude-plugin/plugin.json. When installed, Claude Code auto-discovers all skills and agents:

Teams are not a plugin-native content type — activate a team by reading teams/<name>.md and spawning each listed member as a subagent via the Agent tool (subagent_type), coordinating them with SendMessage under the session's single implicit team (see Creating Agents and Teams). TeamCreate is a gated FleetView/cloud fallback, not the path for ordinary interactive sessions.

For step-by-step plugin install (POSIX + Windows + macOS variants, prereqs, verification, troubleshooting), see the Installation guide.

Contributing

Contributions welcome! Each content type has its own guide:

• Skills — skills/README.md for format and consumption
• Agents — agents/README.md for template and best practices
• Teams — teams/README.md for coordination patterns
• Guides — guides/README.md for categories and template

Update the relevant _registry.yml when adding content, then run npm run update-readmes.

Support

If Agent Almanac makes your AI tools more capable, consider sponsoring its development.

Reliable AI assistance requires structured knowledge — and maintaining that structure is work that the models themselves cannot do.

License

MIT License. See LICENSE for details.