> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codealive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Skills & Plugins

> Install CodeAlive skills for intelligent codebase exploration patterns

## Overview

CodeAlive offers three integration methods that complement each other:

<CardGroup cols={3}>
  <Card title="MCP Server" icon="plug">
    **Provides tools.** Gives your agent direct access to the v3 Tool API set via the Model Context Protocol: `get_data_sources`, `semantic_search`, `grep_search`, repository ontology/tree/read tools, `fetch_artifacts`, `get_artifact_relationships`, ArtifactQuery tools, and stateless `chat`.
  </Card>

  <Card title="Agent Skill" icon="graduation-cap">
    **Teaches workflows.** Teaches your agent effective query patterns, cost-aware tool selection, and multi-step exploration workflows.
  </Card>

  <Card title="Claude Code Plugin" icon="puzzle-piece">
    **Bundles everything.** Includes the skill plus authentication hooks and a code exploration subagent. Claude Code only.
  </Card>
</CardGroup>

The skill and MCP server work best together: the MCP server provides the tools, and the skill teaches the agent how to use them effectively.

## Installing the Skill

<Steps>
  <Step title="Via Installer (Recommended)">
    The universal installer auto-detects your agents and installs the skill:

    ```bash theme={null}
    npx @codealive/installer
    ```

    Select "CodeAlive Skill" when prompted. See the [Installation Guide](/installation) for details.
  </Step>

  <Step title="Via npx">
    Install the skill directly using the skills CLI:

    ```bash theme={null}
    npx skills add CodeAlive-AI/codealive-skills@codealive-context-engine
    ```

    This works with any agent that supports the [skills.sh](https://skills.sh/) standard.
  </Step>

  <Step title="Manual Installation">
    Copy the `skills/codealive-context-engine` folder into your agent's skills directory:

    | Agent          | Project scope       | User scope                    |
    | -------------- | ------------------- | ----------------------------- |
    | Claude Code    | `.claude/skills/`   | `~/.claude/skills/`           |
    | Cursor         | `.cursor/skills/`   | `~/.cursor/skills/`           |
    | GitHub Copilot | `.github/skills/`   | `~/.copilot/skills/`          |
    | Windsurf       | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
    | Gemini CLI     | `.gemini/skills/`   | `~/.gemini/skills/`           |
    | Codex          | `.codex/skills/`    | `~/.codex/skills/`            |
    | Goose          | `.goose/skills/`    | `~/.config/goose/skills/`     |
    | Amp            | `.agents/skills/`   | `~/.config/agents/skills/`    |
    | Roo Code       | `.roo/skills/`      | `~/.roo/skills/`              |
    | OpenCode       | `.opencode/skill/`  | `~/.config/opencode/skill/`   |
    | OpenClaw       | `skills/`           | `~/.openclaw/skills/`         |
  </Step>
</Steps>

## Installing the Claude Code Plugin

For Claude Code users, the plugin provides the best experience — it includes the skill plus Claude-specific enhancements.

<Steps>
  <Step title="Add the Marketplace">
    In Claude Code, run:

    ```
    /plugin marketplace add CodeAlive-AI/codealive-skills
    ```
  </Step>

  <Step title="Install the Plugin">
    ```
    /plugin install codealive@codealive-marketplace
    ```
  </Step>
</Steps>

The plugin includes:

* The CodeAlive Context Engine skill
* Authentication hooks for automatic API key injection
* A code exploration subagent for guided analysis

<Tip>
  Already using the plugin in Claude Code and want another agent (for example Codex CLI) to load the same skill files? See [Share the plugin with Codex CLI](/integrations/share-plugin-with-codex) for a symlink-based bridge that follows every `claude plugin update`.
</Tip>

## Setup & Authentication

After installing, run the interactive setup:

```bash theme={null}
python setup.py
```

This will ask for your [API key](https://app.codealive.ai/settings/api-keys), verify it, and store it securely in your OS credential store.

For self-hosted CodeAlive, set `CODEALIVE_BASE_URL` to your deployment origin, for example `https://codealive.yourcompany.com`. `https://host/api` is also accepted and normalized automatically.

### API Key Resolution Order

1. `CODEALIVE_API_KEY` environment variable
2. OS credential store:

| Platform | Store              | Manual command                                                             |
| -------- | ------------------ | -------------------------------------------------------------------------- |
| macOS    | Keychain           | `security add-generic-password -a "$USER" -s "codealive-api-key" -w "KEY"` |
| Linux    | Secret Service     | `secret-tool store --label="CodeAlive API Key" service codealive-api-key`  |
| Windows  | Credential Manager | `cmdkey /generic:codealive-api-key /user:codealive /pass:"KEY"`            |

## Available Tools

The skill provides local scripts for the complete Tool API v3 workflow plus an offline version check:

| Tool                       | Script             | Speed   | Cost | Best For                                                                               |
| -------------------------- | ------------------ | ------- | ---- | -------------------------------------------------------------------------------------- |
| **List Data Sources**      | `datasources.py`   | Instant | Free | Discovering indexed repos and workspaces                                               |
| **Semantic Search**        | `search.py`        | Fast    | Low  | Finding relevant artifacts by meaning                                                  |
| **Grep Search**            | `grep.py`          | Fast    | Low  | Exact text and regex matches with line previews                                        |
| **Fetch Artifacts**        | `fetch.py`         | Fast    | Low  | Retrieving full content for search results                                             |
| **Artifact Relationships** | `relationships.py` | Fast    | Low  | Expanding call graph, inheritance, and references for one artifact                     |
| **Chat with Codebase**     | `chat.py`          | Slow    | High | Synthesized answers, architectural explanations                                        |
| **Get Version**            | `get_version.py`   | Instant | Free | Return the installed skill version as JSON without authentication or a network request |

Check the installed version locally:

```bash theme={null}
python scripts/get_version.py
# {"name": "codealive-context-engine", "version": "3.0.0"}
```

**Cost guidance:** `semantic_search` and `grep_search` should be the default starting point. Chat invokes an LLM on the server side, is stateless in v3, can take substantially longer than retrieval, and is usually unnecessary unless you specifically request a synthesized answer after search.

## Supported Agents

The skill works with 30+ agents that support the [skills.sh](https://skills.sh/) standard, including:

Cursor, GitHub Copilot, Windsurf, Gemini CLI, Codex, Goose, Amp, Roo Code, OpenCode, OpenClaw, Claude Code, and many more.

## Troubleshooting

<AccordionGroup>
  <Accordion title="API key not configured">
    Run the setup script:

    ```bash theme={null}
    python setup.py
    ```

    Or set the environment variable:

    ```bash theme={null}
    export CODEALIVE_API_KEY="your_key"
    ```
  </Accordion>

  <Accordion title="Skill not detected by agent">
    1. Verify the skill files are in the correct directory for your agent
    2. Check that the `SKILL.md` file exists in the skill folder
    3. Restart your agent
  </Accordion>

  <Accordion title="Python not found">
    The skill requires Python 3.8+. No third-party packages are needed — it uses only the standard library.
  </Accordion>

  <Accordion title="Credential store errors">
    If the OS credential store fails:

    * macOS: Ensure Keychain Access is unlocked
    * Linux: Install `libsecret-tools` (`sudo apt install libsecret-tools`)
    * Windows: Run as Administrator
    * Fallback: Use the `CODEALIVE_API_KEY` environment variable
  </Accordion>
</AccordionGroup>

<Tip>
  For more solutions, see the [Troubleshooting Guide](/troubleshooting).
</Tip>

## Related Resources

<CardGroup cols={2}>
  <Card title="Installation Guide" icon="download" href="/installation">
    Universal installer for all components
  </Card>

  <Card title="MCP Integration" icon="plug" href="/integrations/mcp">
    Set up the MCP server for direct tool access
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/CodeAlive-AI/codealive-skills">
    Skills source code
  </Card>

  <Card title="skills.sh" icon="globe" href="https://skills.sh">
    Agent skills standard
  </Card>
</CardGroup>