install-almanac-content · diff

v1.1 to v1.1

16 added, 16 removed. Audit A to A.

---

name: install-almanac-content

locale: caveman-lite

source_locale: en

source_commit: 82c77053

translator: "Julius Brussee homage — caveman"

- translation_date: "2026-04-19"

+ translation_date: "2026-04-24"

description: >

Install skills, agents, and teams from agent-almanac into any supported

agentic framework using the CLI. Covers framework detection, content

search, installation with dependency resolution, health auditing, and

manifest-based syncing. Use when setting up a new project with agentic

capabilities, installing specific skills or entire domains, targeting

multiple frameworks simultaneously, or maintaining a declarative

manifest of installed content.

license: MIT

allowed-tools:

- Bash

- Read

- Glob

metadata:

author: Philipp Thoss

version: "1.1"

domain: general

complexity: basic

language: multi

tags:

- cli

- installation

- framework-integration

- discovery

---

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

```bash

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.

+ **Got:** 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.

+ **If fail:** 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:

```bash

agent-almanac search <keyword>

```

To browse by category:

```bash

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.

+ **Got:** 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`.

+ **If fail:** 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:

```bash

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

+ **Got:** 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.

+ **If fail:** 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:

```bash

agent-almanac audit

```

To audit a specific framework or scope:

```bash

agent-almanac audit --framework claude-code

agent-almanac audit --global

```

To see what is currently installed:

```bash

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.

+ **Got:** 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.

+ **If fail:** 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:

```bash

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

```yaml

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:

```bash

agent-almanac install

```

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

```bash

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.

+ **Got:** 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.

+ **If fail:** 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`:

```bash

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

+ **Got:** 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`.

+ **If fail:** 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

+ ## 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.

+ - **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. 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 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