Install Almanac Content

Use the

agent-almanac

CLI to install skills, agents, and teams into any supported agentic framework.

When to Use

• Setting up a new project and need to install agentic skills, agents, or teams
• Installing all skills from a specific domain (e.g.,

  r-packages

  ,

  devops

  )
• Targeting multiple frameworks simultaneously (Claude Code, Cursor, Copilot, etc.)
• Creating or syncing a 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, or team IDs (e.g.,

  create-skill

  ,

  r-developer

  ,

  r-package-review

  )
• Optional:

  --domain <domain>

  -- install all skills from a domain instead of naming individual IDs
• Optional:

  --framework <id>

  -- target a specific framework (default: auto-detect all)
• Optional:

  --with-deps

  -- also install agent skills and 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)

Procedure

Step 1: Detect Frameworks

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

agent-almanac detect

This scans the working directory for configuration files and directories (

.claude/

,

.cursor/

,

.github/copilot-instructions/

,

.agents/

, etc.) and reports which frameworks are active.

Expected: Output lists one or more detected frameworks with their adapter status. If no frameworks are detected, the universal adapter (

.agents/skills/

) is used as fallback.

On failure: If the CLI is not found, ensure it is installed and on PATH. If detection returns nothing and you know a framework is present, use

--framework <id>

to specify it explicitly. Run

agent-almanac list --domains

to verify the CLI can reach the registries.

Step 2: Search for Content

Find skills, agents, or teams by keyword:

agent-almanac search <keyword>

To 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

Expected: Search results or filtered lists display matching content with IDs and descriptions.

On failure: If no results appear, try broader keywords. Verify the almanac root is reachable:

agent-almanac list

should show the full skill count. If it cannot find the 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

The CLI resolves the content from the registries, selects the appropriate adapter for each detected framework, and writes files to the framework-specific paths (e.g.,

.claude/skills/

for Claude Code,

.cursor/rules/

for Cursor).

Expected: Output confirms the number of items installed and the target framework(s). Installed content appears in the correct framework directory.

On failure: If items are not found, verify the ID matches the

name

field in the registry (

skills/_registry.yml

,

agents/_registry.yml

,

teams/_registry.yml

). If files already exist and installation is skipped, use

--force

to overwrite.

Step 4: Verify Installation

Run a health check on all installed content:

agent-almanac audit

To audit a specific framework or scope:

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

To see what is currently installed:

agent-almanac list --installed

Expected: Audit reports all installed items as healthy with no broken references. The

--installed

listing shows each item with its type and framework.

On failure: If the audit reports broken items, reinstall them with

--force

. If symlinks are broken, verify the almanac source path has not moved. Run

agent-almanac install <broken-id> --force

to repair.

Step 5: Manage with a Manifest (Optional)

For reproducible setups, use a declarative

agent-almanac.yml

manifest:

# Generate a starter manifest
agent-almanac init

This creates

agent-almanac.yml

in the current directory with detected frameworks and placeholder content lists. Edit the file to declare desired skills, agents, and 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 the manifest:

agent-almanac install

To reconcile installed state with the manifest (install missing, remove extra):

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

Expected: Running

install

with no arguments reads the manifest and installs all declared content. Running

sync

brings the installed state into alignment with the manifest, adding missing items and removing undeclared ones.

On failure: If

sync

reports "No agent-almanac.yml found", run

agent-almanac init

first. If the manifest resolves to 0 items, check that skill/agent/team IDs match the registry entries exactly. Comment lines starting with

#

are ignored.

Step 6: Manage Teams as Campfires (Optional)

The campfire commands provide a 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 is tracked in

.agent-almanac/state.json

(git-ignored, local to the project). Fires have thermal states: burning (used within 7 days), embers (within 30 days), cold (30+ days). Running

tend

warms all fires and reports their health.

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

All campfire commands support

--quiet

(standard reporter output) and

--json

(machine-parseable) for scripting.

Expected: Teams are gathered and managed with state tracking.

campfire --all

shows fire states.

tend

reports health.

On failure: If campfire state is corrupted, delete

.agent-almanac/state.json

and re-gather teams. If

gather

fails, check that the team name matches an entry in

teams/_registry.yml

.

Validation

• 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 the target framework (e.g.,

  /skill-name

  works in Claude Code)
• If using a manifest,

  agent-almanac sync --dry-run

  reports no changes needed

Common Pitfalls

• Forgetting

  --with-deps

  for agents and teams: Installing an agent without

  --with-deps

  installs only the agent definition, not its referenced skills. The agent will be present but unable to follow its skill procedures. Always use

  --with-deps

  for agents and teams unless you have already installed the dependencies separately.
• Manifest drift: After manually installing or removing content, the manifest falls out of sync with the actual installed state. Run

  agent-almanac sync

  periodically, or always install through the manifest to keep them aligned.
• Scope confusion (project vs global): Content installed with

  --global

  goes to

  ~/.claude/skills/

  (or equivalent), while project-scope content goes to

  .claude/skills/

  in the current directory. If a skill is not found, check whether it was installed in the wrong scope.
• Stale source path: If the agent-almanac repository is moved or renamed, the

  --source

  path in manifests and auto-detection will break. Update the

  source

  field in

  agent-almanac.yml

  or re-run

  agent-almanac init

  .
• Framework not detected: The detector looks for specific files and directories. A freshly initialized project may not have these yet. Use

  --framework <id>

  explicitly until the project has the expected structure, or rely on the universal adapter.
• Campfire thermal state confusion: Fires go cold after 30 days without use. Running

  agent-almanac tend

  resets the timer for all gathered fires. If a fire shows as "cold," it is still fully installed — the thermal state reflects recency of use, not installation health.

Related Skills

• create-skill

  -- author new skills to add to the almanac before installing them

• 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 the CLI's reporter and campfire ceremony