install-almanac-content

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