# Agent Skills

> Teach your coding agent to run fallow with the right commands and flags and to read the output correctly. Install the skills in Claude Code, Cursor, Windsurf, Gemini CLI, and other agents that support the Agent Skills specification.

> Page index of all docs: https://fallow.tools/llms.txt
> Docs MCP server (search and read the docs): https://fallow.tools/docs/mcp
> HTML version of this page: https://fallow.tools/docs/integrations/agent-skills/

With the fallow skills installed, your coding agent runs the right fallow command for a request and reads the output correctly. It does not guess from general knowledge. The skills tell the agent:

- when to run each command
- which flags to use
- how to read the output
- how to avoid common pitfalls

They cover codebase health, cleanup analysis, circular dependencies, duplication, and complexity hotspots.

> **Info:** Skills work together with the CLI and MCP integrations. Skills tell the agent *how* to use fallow. The CLI and MCP give the agent the *tools*.

## 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 |
| **Setup skill** | `fallow-setup` sets up code-quality tooling for a JavaScript or TypeScript project. It detects the existing tools, runs `fallow recommend`, installs fallow, runs `fallow agent install`, and adds a CI gate with a baseline |
| **CLI reference** | Commands, flags, output formats, and configuration |
| **Gotchas** | Common pitfalls with correct and incorrect examples, for example `fix --yes` in non-TTY |
| **Workflow patterns** | Recipes for CI pipelines, monorepo analysis, migrating from knip/jscpd, and incremental adoption |
| **Commit gate** | Claude Code plugin only. A `PreToolUse` hook runs `fallow audit` before `git commit` and `git push`, and blocks the command on a `fail` verdict |

The commit gate of the plugin runs only in a project that uses fallow: a project with a fallow config file, or with a `fallow` dependency in `package.json`. It does nothing when `fallow agent install` already registered a gate for Claude Code or Codex. To turn it off, set `FALLOW_PLUGIN_GATE=off` in the environment of Claude Code.

## Installation

> **Tip:** If your project already has fallow installed from npm, you can skip the manual steps. [`fallow agent install`](https://fallow.tools/docs/cli/agent/) writes the `fallow` and `fallow-setup` skills where Claude Code, Codex, and Cursor look for them. It also writes the MCP registration, an `AGENTS.md` task map, and the commit and push gate. Add `--dry-run` to see the plan first.

#### Claude Code

```bash
/plugin marketplace add fallow-rs/fallow-skills
/plugin install fallow@fallow-skills
```

#### Cursor

```bash
git clone https://github.com/fallow-rs/fallow-skills.git ~/.cursor/skills/fallow-skills
```

#### OpenAI Codex

```bash
codex plugin marketplace add fallow-rs/fallow-skills
codex plugin add fallow@fallow-skills
```

In the Codex desktop app, this plugin also adds the [Fallow app](https://fallow.tools/docs/integrations/codex-app/): a code health dashboard, a thread tab, composer attachments, and a config editor.

#### Windsurf

```bash
git clone https://github.com/fallow-rs/fallow-skills.git ~/.codeium/windsurf/skills/fallow-skills
```

#### GitHub Copilot

```bash
git clone https://github.com/fallow-rs/fallow-skills.git .github/skills/fallow-skills
```

#### Gemini CLI

```bash
gemini skills install https://github.com/fallow-rs/fallow-skills.git
```

#### Amp

```bash
git clone https://github.com/fallow-rs/fallow-skills.git ~/.config/agents/skills/fallow-skills
```

> **Note:** Inside a Claude Code session, fallow can write one `<claude-code-hint />` line that asks Claude Code to offer the fallow plugin. Fallow writes the line to stderr, and only for human output without `--quiet`, outside CI, and when the project and the user have no fallow plugin or skill for Claude Code. The hint has no effect until the official Claude Code marketplace lists the plugin. Set [`FALLOW_CLAUDE_CODE_HINT=off`](https://fallow.tools/docs/configuration/environment/) to turn it off.

The skills follow the open [Agent Skills](https://agentskills.io) specification, so any compatible agent can use them.

## What agents can do after installation

After you install the skills, your agent can handle requests like these:

- **Find cleanup opportunities**: "Find all unused exports in this project". The agent runs `fallow dead-code --format json --quiet --unused-exports` and summarizes the findings.
- **Clean up dependencies**: "Are there any unused dependencies?" The agent runs a targeted analysis and suggests removals.
- **Detect duplication**: "Find code duplication in the codebase". The agent runs `fallow dupes` with the right mode and explains the clone families.
- **Auto-fix**: "Remove unused exports". The agent does a dry run first and shows the proposed changes. Then it applies them with `--yes`.
- **CI setup**: "Set up a code quality gate in CI". The agent writes a GitHub Actions workflow with baselines.
- **Debug false positives**: "Why is this export flagged?" The agent uses `--trace` to find the cause and suggests a suppression if needed.

## 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 how to use fallow | Typed tool calling in agent frameworks | Any environment with a shell |

> **Tip:** Use all three together. Install the skill so the agent knows how to use fallow. Configure MCP for typed tool calls. Keep fallow in PATH as a CLI fallback.

## See also

- [Agent integration](https://fallow.tools/docs/integrations/mcp/): CLI and MCP integration for AI agents.
- [Adopt Fallow in an existing repo](https://fallow.tools/docs/adoption/#8-clean-up-with-an-agent): The agent-driven cleanup workflow and copy-paste prompt.
- [CI integration](https://fallow.tools/docs/integrations/ci/): Find codebase issues in your CI pipeline.
- [VS Code extension](https://fallow.tools/docs/integrations/vscode/): Real-time feedback for human developers.