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

# Agent Skills

> Install fallow analysis skills for Claude Code, Cursor, Windsurf, Gemini CLI, and other AI agents that support the Agent Skills specification.

Agent skills give AI coding agents structured knowledge about how to use fallow. Skills cover when to run each command, what flags to use, how to read the output, and how to avoid common pitfalls. Instead of relying on the agent's general knowledge, skills provide precise, up-to-date instructions for dead code analysis, circular dependency detection, duplication, and complexity hotspots.

<Info>
  Skills work alongside the CLI and MCP integrations. They tell agents *how* to use fallow effectively, while the CLI and MCP provide the *tools* to do it.
</Info>

## What's included

The [fallow-skills](https://github.com/fallow-rs/fallow-skills) package includes:

| Component             | Description                                                                                      |
| :-------------------- | :----------------------------------------------------------------------------------------------- |
| **Analysis skill**    | Workflows for unused code, duplication, complexity, boundary analysis, auto-fix, and CI setup    |
| **CLI reference**     | Complete command specs, flags, output formats, and configuration                                 |
| **Gotchas**           | Common pitfalls with correct vs. incorrect examples (e.g., `fix --yes` in non-TTY)               |
| **Workflow patterns** | Recipes for CI pipelines, monorepo analysis, migrating from knip/jscpd, and incremental adoption |

## Installation

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    /plugin marketplace add fallow-rs/fallow-skills
    /plugin install fallow-skills@fallow-rs/fallow-skills
    ```
  </Tab>

  <Tab title="Cursor">
    ```bash theme={null}
    git clone https://github.com/fallow-rs/fallow-skills.git ~/.cursor/skills/fallow-skills
    ```
  </Tab>

  <Tab title="OpenAI Codex">
    ```bash theme={null}
    git clone https://github.com/fallow-rs/fallow-skills.git ~/.agents/skills/fallow-skills
    ```
  </Tab>

  <Tab title="Windsurf">
    ```bash theme={null}
    git clone https://github.com/fallow-rs/fallow-skills.git ~/.codeium/windsurf/skills/fallow-skills
    ```
  </Tab>

  <Tab title="GitHub Copilot">
    ```bash theme={null}
    git clone https://github.com/fallow-rs/fallow-skills.git .github/skills/fallow-skills
    ```
  </Tab>

  <Tab title="Gemini CLI">
    ```bash theme={null}
    gemini skills install https://github.com/fallow-rs/fallow-skills.git
    ```
  </Tab>

  <Tab title="Amp">
    ```bash theme={null}
    git clone https://github.com/fallow-rs/fallow-skills.git ~/.config/agents/skills/fallow-skills
    ```
  </Tab>
</Tabs>

Skills follow the open [Agent Skills](https://agentskills.io) specification and work with any compatible agent.

## What agents can do after installation

Once installed, agents know how to respond to natural language requests like these:

<CardGroup cols={2}>
  <Card title="Find dead code" icon="skull-crossbones">
    "Find all unused exports in this project". Agent runs `fallow dead-code --format json --quiet --unused-exports` and summarizes findings.
  </Card>

  <Card title="Clean up dependencies" icon="box-open">
    "Are there any unused dependencies?" Agent runs targeted analysis and suggests removals.
  </Card>

  <Card title="Detect duplication" icon="copy">
    "Find code duplication in the codebase". Agent runs `fallow dupes` with the right mode and interprets clone families.
  </Card>

  <Card title="Auto-fix" icon="wrench">
    "Remove unused exports". Agent runs dry-run first, shows proposed changes, then applies with `--yes`.
  </Card>

  <Card title="CI setup" icon="shield-check">
    "Set up a dead code check in CI". Agent generates the correct GitHub Actions workflow with baselines.
  </Card>

  <Card title="Debug false positives" icon="bug">
    "Why is this export flagged?" Agent uses `--trace` to investigate and suggests suppression if needed.
  </Card>
</CardGroup>

## Workflow recipe: adopt Fallow in an existing repo

When the goal is to bring an existing codebase to a clean Fallow policy (not just audit a single PR), fallow's approach is to hand the cleanup work to the agent: fallow finds the problems, the agent fixes them in code.

Three ways to run this, pick whichever your agent supports:

1. **Install the skill** (best). `fallow-skills` ships the full adoption workflow. Once installed, the agent does not need to fetch docs URLs during use. Installation is one line per agent, above.
2. **Add the MCP server.** Combine with the skill or use standalone. The agent gets `audit`, `dead_code`, `dupes`, and `health` as structured tools with `_meta` explanations on every finding. See [MCP](/integrations/mcp).
3. **Paste the prompt below.** Self-contained fallback for agents without skill or MCP support, or for sandboxed agents that cannot fetch URLs.

<Accordion title="Copy-paste adoption prompt (self-contained)">
  ```text theme={null}
  Adopt Fallow in this repository.

  Goal:
  - use full-repo analysis first (`fallow`, `fallow dead-code`, `fallow dupes`, `fallow health`), not `fallow audit`
  - fix real dead code, duplication, and complexity issues in code
  - model intentional exceptions with the narrowest correct mechanism
  - end with no functions above the repo's chosen health thresholds, or a consciously widened threshold with written justification
  - then set up `fallow audit` as a PR gate

  Process:
  1. Run `npx fallow`, then `npx fallow dead-code`, `npx fallow dupes`, and `npx fallow health`. Use `--format json` for structured output.
  2. If no config exists, run `fallow init` and create a minimal repo policy.
  3. Fix high-confidence issues first:
     - unresolved imports
     - unlisted dependencies
     - unused files (sanity-check with `fallow list --entry-points`)
     - unused dependencies
  4. For each remaining finding, choose one path:
     - fix it in code (preferred)
     - model it in config
     - add a narrow inline exception only if it is truly one-off
  5. Match reasons to mechanisms:
     - external API: `@public` / `@internal` / `@beta` / `@alpha` JSDoc tags, or `publicPackages`
     - runtime or framework entry point: `entry`, `dynamicallyLoaded`, plugin-aware config
     - generated code: `ignorePatterns`, `health.ignore`
     - intentionally retained dependency: `ignoreDependencies`
     - intentional unused export: `@expected-unused` (preferred over inline comments because it self-cleans)
     - one-off false positive: `fallow-ignore-next-line`
     - repo-wide policy: `rules`, `health`, duplication settings, `overrides`
  6. Prefer config-level modeling over repeated suppression.
  7. Keep every exception narrow and explain why it exists in a commit message.
  8. Re-run Fallow after each batch until the repo is clean under the chosen policy.
  9. Only after repo cleanup, run `npx fallow audit` and wire it into CI.

  At the end, report:
  - code changes
  - config changes
  - exceptions added and why
  - anything left
  - the final commands and outputs that show the repo is clean
  ```
</Accordion>

## Skills vs MCP vs CLI

|                      | Skills                                | MCP                                    | CLI                                |
| :------------------- | :------------------------------------ | :------------------------------------- | :--------------------------------- |
| **What it provides** | Knowledge about *how* to use fallow   | Structured tool interface              | Direct command execution           |
| **Setup**            | One-time install per agent            | MCP server configuration               | fallow binary in PATH              |
| **Agent support**    | Any agent with skill support          | Agents with MCP support                | Any agent that runs shell commands |
| **Best for**         | Teaching agents fallow best practices | Typed tool calling in agent frameworks | Universal compatibility            |

<Tip>
  For the best experience, combine all three. Install the skill for knowledge, configure MCP for structured tool calling, and keep fallow in PATH for CLI fallback.
</Tip>

## See also

<CardGroup cols={3}>
  <Card title="Agent integration" icon="robot" href="/integrations/mcp">
    CLI and MCP integration for AI agents.
  </Card>

  <Card title="CI integration" icon="shield-check" href="/integrations/ci">
    Catch codebase issues in your CI pipeline.
  </Card>

  <Card title="VS Code extension" icon="window" href="/integrations/vscode">
    Real-time feedback for human developers.
  </Card>
</CardGroup>