Install Almanac Content

Use agent-almanac CLI to install skills, agents, teams into any supported agentic framework.

When Use

• Setting up new project, need to install agentic skills, agents, teams
• Installing all skills from specific domain (r-packages, devops)
• Targeting multiple frameworks simultaneously (Claude Code, Cursor, Copilot)
• Creating or syncing declarative agent-almanac.yml manifest for reproducible setups
• Auditing installed content for broken symlinks or stale references

Inputs

• Required: Content to install -- one or more skill, agent, team IDs (create-skill, r-developer, r-package-review)
• Optional: --domain <domain> -- install all skills from domain instead of naming individual IDs
• Optional: --framework <id> -- target specific framework (default: auto-detect all)
• Optional: --with-deps -- also install agent skills + team agents+skills
• Optional: --dry-run -- preview changes without writing to disk
• Optional: --global -- install to global scope instead of project scope
• Optional: --force -- overwrite existing content
• Optional: --source <path> -- explicit path to agent-almanac root (default: auto-detect)

Steps

Step 1: Detect Frameworks

Run framework detection to see which agentic tools present in current project:

agent-almanac detect

Scans working directory for configuration files + directories (.claude/, .cursor/, .github/copilot-instructions/, .agents/) + reports which frameworks active.

Got: Output lists one or more detected frameworks with adapter status. No frameworks detected? Universal adapter (.agents/skills/) used as fallback.

If fail: CLI not found? Ensure installed + on PATH. Detection returns nothing but you know framework is present? Use --framework <id> to specify explicit. Run agent-almanac list --domains to verify CLI can reach registries.

Step 2: Search for Content

Find skills, agents, teams by keyword:

agent-almanac search <keyword>

Browse by category:

agent-almanac list --domains          # List all domains with skill counts
agent-almanac list -d r-packages      # List skills in a specific domain
agent-almanac list --agents           # List all agents
agent-almanac list --teams            # List all teams

Got: Search results or filtered lists display matching content with IDs + descriptions.

If fail: No results appear? Try broader keywords. Verify almanac root reachable: agent-almanac list should show full skill count. Can't find root? Pass --source /path/to/agent-almanac.

Step 3: Install Content

Install one or more items by name:

# Install specific skills
agent-almanac install create-skill write-testthat-tests

# Install all skills from a domain
agent-almanac install --domain devops

# Install an agent with its skills
agent-almanac install --agent r-developer --with-deps

# Install a team with its agents and their skills
agent-almanac install --team r-package-review --with-deps

# Target a specific framework
agent-almanac install create-skill --framework cursor

# Preview without writing
agent-almanac install --domain esoteric --dry-run

# Install to global scope
agent-almanac install create-skill --global

CLI resolves content from registries, selects appropriate adapter for each detected framework, writes files to framework-specific paths (.claude/skills/ for Claude Code, .cursor/rules/ for Cursor).

Got: Output confirms number of items installed + target framework(s). Installed content appears in correct framework directory.

If fail: Items not found? Verify ID matches name field in registry (skills/_registry.yml, agents/_registry.yml, teams/_registry.yml). Files already exist + installation skipped? Use --force to overwrite.

Step 4: Verify Installation

Run health check on all installed content:

agent-almanac audit

Audit specific framework or scope:

agent-almanac audit --framework claude-code
agent-almanac audit --global

See what currently installed:

agent-almanac list --installed

Got: Audit reports all installed items healthy with no broken references. --installed listing shows each item with type + framework.

If fail: Audit reports broken items? Reinstall with --force. Symlinks broken? Verify almanac source path hasn't moved. Run agent-almanac install <broken-id> --force to repair.

Step 5: Manage with Manifest (Optional)

Reproducible setups → use declarative agent-almanac.yml manifest:

# Generate a starter manifest
agent-almanac init

Creates agent-almanac.yml in current directory with detected frameworks + placeholder content lists. Edit file to declare desired skills, agents, teams:

source: /path/to/agent-almanac
frameworks:
  - claude-code
  - cursor
skills:
  - create-skill
  - domain:r-packages
agents:
  - r-developer
teams:
  - r-package-review

Then install everything declared in manifest:

agent-almanac install

Reconcile installed state with manifest (install missing, remove extra):

agent-almanac sync
agent-almanac sync --dry-run  # Preview first

Got: Running install with no arguments reads manifest + installs all declared content. Running sync brings installed state into alignment with manifest, adding missing items + removing undeclared.

If fail: sync reports "No agent-almanac.yml found"? Run agent-almanac init first. Manifest resolves to 0 items? Check skill/agent/team IDs match registry entries exact. Comment lines starting with # ignored.

Step 6: Manage Teams as Campfires (Optional)

Campfire commands provide warm, team-oriented alternative to install --team:

# Browse all available team circles
agent-almanac campfire --all

# Inspect a specific circle (members, practices, pattern)
agent-almanac campfire tending

# See shared agents between teams (hearth-keepers)
agent-almanac campfire --map

# Gather a team (install with arrival ceremony)
agent-almanac gather tending
agent-almanac gather tending --ceremonial    # Show each skill arriving
agent-almanac gather tending --only mystic,gardener  # Partial gathering

# Check fire health (burning / embers / cold)
agent-almanac tend

# Scatter a team (uninstall with farewell)
agent-almanac scatter tending

Campfire state tracked in .agent-almanac/state.json (git-ignored, local to project). Fires have thermal states: burning (used within 7 days), embers (within 30 days), cold (30+ days). Running tend warms all fires + reports health.

Shared skills protected during scatter — if skill needed by another gathered fire, stays installed. Shared agents walk between fires rather than being duplicated.

All campfire commands support --quiet (standard reporter output) + --json (machine-parseable) for scripting.

Got: Teams gathered + managed with state tracking. campfire --all shows fire states. tend reports health.

If fail: Campfire state corrupted? Delete .agent-almanac/state.json + re-gather teams. gather fails? Check team name matches entry in teams/_registry.yml.

Checks

• agent-almanac detect shows expected frameworks
• agent-almanac list --installed shows all intended content
• agent-almanac audit reports no broken items
• Installed skills resolve in target framework (/skill-name works in Claude Code)
• Using manifest → agent-almanac sync --dry-run reports no changes needed

Pitfalls

• Forgetting --with-deps for agents + teams: Installing agent without --with-deps installs only agent definition, not referenced skills. Agent present but unable to follow skill procedures. Always use --with-deps for agents + teams unless already installed dependencies separately.
• Manifest drift: After manual install or remove content, manifest falls out of sync with actual installed state. Run agent-almanac sync periodically, or always install through manifest to keep aligned.
• Scope confusion (project vs global): Content installed with --global goes to ~/.claude/skills/ (or equivalent); project-scope content goes to .claude/skills/ in current directory. Skill not found? Check whether installed in wrong scope.
• Stale source path: agent-almanac repository moved or renamed? --source path in manifests + auto-detection breaks. Update source field in agent-almanac.yml or re-run agent-almanac init.
• Framework not detected: Detector looks for specific files + directories. Freshly initialized project may not have these yet. Use --framework <id> explicit until project has expected structure, or rely on universal adapter.
• Campfire thermal state confusion: Fires go cold after 30 days without use. Running agent-almanac tend resets timer for all gathered fires. Fire shows as "cold" → still fully installed — thermal state reflects recency of use, not installation health.

See Also

• create-skill -- author new skills to add to almanac before installing
• configure-mcp-server -- set up MCP servers that agents may need after installation
• write-claude-md -- configure CLAUDE.md to reference installed skills
• audit-discovery-symlinks -- diagnose symlink issues for Claude Code skill discovery
• design-cli-output -- terminal output patterns used by CLI reporter + campfire ceremony