pjt222/agent-almanac

# GitHub Repository: pjt222/agent-almanac

**URL:** https://github.com/pjt222/agent-almanac
**Author:** pjt222
**Description:** Agent Almanac — a curated reference of executable skills, specialist agents, and teams for AI-assisted development, with interactive visualization
**Homepage:** https://pjt222.github.io/agent-almanac/
**Language:** R

## Stats
- Stars: 21
- Forks: 3
- Open Issues: 17
- Commits: 548
- Created: 2025-06-06T13:36:37Z
- Updated: 2026-06-18T10:01:54Z
- Pushed: 2026-06-18T15:47:00Z

## README
<p align="center">
  <img src="viz/public/logo-transparent.png" alt="Agent Almanac" width="256">
</p>

# Agent Almanac

[![npm version](https://img.shields.io/npm/v/agent-almanac.svg)](https://www.npmjs.com/package/agent-almanac)
[![Validate Skills](https://github.com/pjt222/agent-almanac/actions/workflows/validate-skills.yml/badge.svg)](https://github.com/pjt222/agent-almanac/actions/workflows/validate-skills.yml)
[![Update READMEs](https://github.com/pjt222/agent-almanac/actions/workflows/update-readmes.yml/badge.svg)](https://github.com/pjt222/agent-almanac/actions/workflows/update-readmes.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Sponsor](https://img.shields.io/github/sponsors/pjt222?style=flat&logo=GitHub-Sponsors&logoColor=%23EA4AAA&label=Sponsor)](https://github.com/sponsors/pjt222)

A library of executable skills, specialist agents, and pre-built teams for [Claude Code](https://docs.anthropic.com/en/docs/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](https://agentskills.io).

## At a Glance

<!-- AUTO:START:stats -->
- **361 skills** across 65 domains — structured, executable procedures
- **72 agents** — specialized Claude Code personas covering development, review, compliance, and more
- **17 teams** — predefined multi-agent compositions for complex workflows
- **29 guides** — human-readable workflow, infrastructure, and reference documentation
- **Interactive visualization** — force-graph explorer with 361 R-generated skill icons and 9 color themes
<!-- AUTO:END:stats -->

## How It Works

| Building Block | Location | Purpose |
|----------------|----------|---------|
| **[Skills](skills/README.md)** | `skills/<skill-name>/SKILL.md` | Executable procedures (*how*) |
| **[Agents](agents/README.md)** | `agents/<name>.md` | Specialized personas (*who*) |
| **[Teams](teams/README.md)** | `teams/<name>.md` | Multi-agent compositions (*who works together*) |
| **[Guides](guides/README.md)** | `guides/<name>.md` | Human-readable reference (*context*) |

Ask Claude Code to review your R package, and the [r-package-review](teams/r-package-review.md) 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](https://agentskills.io) and work with any tool that reads markdown:

| Tool | Integration | Details |
|------|-------------|---------|
| **Claude Code** | Full (skills, agents, teams) | Plugin install or `.claude/` symlinks |
| **Codex (OpenAI)** | Skills | Symlink into `.agents/skills/` |
| **Cursor** | Skills | Map to `.cursor/rules/*.mdc` files |
| **Gemini CLI, Aider, etc.** | Skills | Point context to any `SKILL.md` file |

Agents and teams use Claude Code's subagent architecture. For other tools, skills are the primary integration surface. See [skills/README.md](skills/README.md#consuming-skills-from-different-systems) for setup instructions.

## Quick Start

Choose a path. Full per-OS runbook with prereqs, verification, and updating: [Installation guide](guides/installation.md).

### 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)

```bash
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:START:plugin-discovery -->
Auto-discovers all 361 skills and 72 agents. Teams require activation via [TeamCreate](guides/creating-agents-and-teams.md). Windows / macOS variants in the [Installation guide](guides/installation.md#phase-1--plugin-install-claude-code-native).
<!-- AUTO:END:plugin-discovery -->

### Path 3 — Global CLI (cross-framework)

```bash
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](cli/README.md).

### Verify

```bash
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](guides/installation.md#troubleshooting).

### Explore visually

```bash
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](guides/installation.md#visualization-pipeline-viz). See [viz/README.md](viz/README.md) for build internals.

## Directory Map

<!-- AUTO:START:dirmap -->
```
agent-almanac/
  .claude-plugin/  Plugin manifest for Claude Code plugin installation
  skills/          361 executable procedures across 65 domains
  agents/          72 specialist personas
  teams/           17 multi-agent compositions with 8 coordination patterns
  guides/          29 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
```
<!-- AUTO:END:dirmap -->

## Guides

New here? Start with [Understanding the System](guides/understanding-the-system.md). See [all guides](guides/README.md) for the full categorized list.

<!-- AUTO:START:guides -->
**Workflow**

- [Understanding the System](guides/understanding-the-system.md) — Entry point: what skills, agents, and teams are, how they compose, and how to invoke them
- [Creating Skills](guides/creating-skills.md) — Authoring, evolving, and reviewing skills following the agentskills.io standard
- [Creating Agents and Teams](guides/creating-agents-and-teams.md) — Designing agent personas, composing teams, and choosing coordination patterns
- [Creating Workflows](guides/creating-workflows.md) — Authoring code-driven orchestration workflows — the meta contract, the agent/parallel/pipeline/phase primitives, and the capability rule
- [Running a Code Review](guides/running-a-code-review.md) — Multi-agent code review using review teams for R packages and web projects
- [Managing a Scrum Sprint](guides/managing-a-scrum-sprint.md) — Running Scrum sprints with the scrum-team: planning, dailies, review, and retro
- [Visualizing Workflows with putior](guides/visualizing-workflows-with-putior.md) — End-to-end putior workflow visualization from annotation to themed Mermaid diagrams
- [Running Tending](guides/running-tending.md) — AI meta-cognitive tending sessions with the tending team
- [Running a Translation Campaign](guides/running-a-translation-campaign.md) — End-to-end guide for translating all skills, agents, teams, and guides into supported locales using the translation-campaign team
- [Unleash the Agents](guides/unleash-the-agents.md) — Structured multi-agent consultation at three tiers for open-ended hypothesis generation
- [Team Assembly Prompt Patterns](guides/team-assembly-prompt-patterns.md) — How to phrase requests to Claude Code for multi-agent team work at every level of specificity
- [Production Coordination Patterns](guides/production-coordination-patterns.md) — Real-world multi-agent orchestration patterns: barrier synchronization, silence budgets, health checks, degraded-wave policies, and cost-aware scheduling
- [AgentSkills Alignment](guides/agentskills-alignment.md) — Standards compliance audits using the agentskills-alignment team for format validation, spec drift detection, and registry integrity
- [Edge Computing Deployment](guides/edge-computing-deployment.md) — 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](guides/self-continuation-loops-playbook.md) — Choose among ScheduleWakeup, CronCreate loops, and loop.md; select sentinels; plan for the 7-day age-out

**Infrastructure**

- [Installation](guides/installation.md) — OS-aware install runbook covering plugin install, global CLI, prereqs, verification, and updating across Linux, macOS, Windows, WSL2, and Codespaces
- [Setting Up Your Environment](guides/setting-up-your-environment.md) — WSL2 setup, shell config, MCP server integration, and Claude Code configuration
- [Symlink Architecture](guides/symlink-architecture.md) — How symlinks enable multi-project discovery of skills, agents, and teams through Claude Code
- [R Package Development](guides/r-package-development.md) — Package structure, testing, CRAN submission, pkgdown deployment, and renv management

**Reference**

- [Quick Reference](guides/quick-reference.md) — Command cheat sheet for agents, skills, teams, Git, R, and shell operations
- [Agent Best Practices](guides/agent-best-practices.md) — Design principles, quality assurance, and maintenance guidelines for writing effective agents
- [Agent Configuration Schema](guides/agent-configuration-schema.md) — YAML frontmatter field definitions, validation rules, and JSON Schema for agent files
- [Content Styleguide](guides/content-styleguide.md) — Canonical markdown formatting conventions for skills, agents, teams, and guides — tables, code fences, headings, lists, and links
- [The Caveman Spellbook](guides/caveman-spellbook.md) — 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](guides/extracting-project-essence.md) — Multi-perspective framework for extracting skills, agents, and teams from any codebase using the metal skill
- [Epigenetics-Inspired Activation Control](guides/epigenetics-activation-control.md) — Runtime activation profiles controlling which agents, skills, and teams are expressed, grounded in molecular epigenetics
- [Understanding the Synoptic Mind](guides/understanding-the-synoptic-mind.md) — The adaptic concept — panoramic synthesis through simultaneous multi-domain awareness, theoretical foundations, and practical use
- [Agent Memory Hygiene](guides/agent-memory-hygiene.md) — Three-layer model — weights, retrieval, behavior — for diagnosing what kind of forgetting a memory problem actually needs and applying the right tool
<!-- AUTO:END:guides -->

## Translations

<!-- AUTO:START:translations -->
| Locale | Language | Skills | Agents | Teams | Guides | Total |
|---|---|---|---|---|---|---|
| de | Deutsch | 358/361 | 3/72 | 1/17 | 4/29 | 366/479 (76.4%) |
| zh-CN | 简体中文 | 358/361 | 3/72 | 1/17 | 4/29 | 366/479 (76.4%) |
| ja | 日本語 | 358/361 | 3/72 | 1/17 | 4/29 | 366/479 (76.4%) |
| es | Español | 358/361 | 3/72 | 1/17 | 4/29 | 366/479 (76.4%) |
| caveman-lite | Caveman Lite | 352/361 | 0/72 | 0/17 | 0/29 | 352/479 (73.5%) |
| caveman | Caveman | 352/361 | 0/72 | 0/17 | 0/29 | 352/479 (73.5%) |
| caveman-ultra | Caveman Ultra | 352/361 | 0/72 | 0/17 | 0/29 | 352/479 (73.5%) |
| wenyan-lite | 文言文輕 | 352/361 | 0/72 | 0/17 | 0/29 | 352/479 (73.5%) |
| wenyan | 文言文 | 352/361 | 0/72 | 0/17 | 0/29 | 352/479 (73.5%) |
| wenyan-ultra | 文言文極 | 352/361 | 0/72 | 0/17 | 0/29 | 352/479 (73.5%) |
<!-- AUTO:END:translations -->

See [i18n/README.md](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:

<!-- AUTO:START:plugin-table -->
| Component | Discovery | Count |
|-----------|-----------|-------|
| Skills | `skills/*/SKILL.md` | 361 |
| Agents | `agents/*.md` | 72 |
| Teams | Bundled but not auto-discovered | 17 |
<!-- AUTO:END:plugin-table -->

Teams are not a plugin-native content type — they require activation via `TeamCreate` (see [Creating Agents and Teams](guides/creating-agents-and-teams.md)).

For step-by-step plugin install (POSIX + Windows + macOS variants, prereqs, verification, troubleshooting), see the [Installation guide](guides/installation.md).

## Contributing

Contributions welcome! Each content type has its own guide:

- **Skills** — [skills/README.md](skills/README.md) for format and consumption
- **Agents** — [agents/README.md](agents/README.md) for template and best practices
- **Teams** — [teams/README.md](teams/README.md) for coordination patterns
- **Guides** — [guides/README.md](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](https://github.com/sponsors/pjt222).

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

## License

MIT License. See [LICENSE](LICENSE) for details.