# Fallow Skills

Fallow Skills provides agent skills for the Fallow codebase analyzer, enabling AI agents to find and remove dead code, unused dependencies, code duplication, and complexity hotspots in JavaScript and TypeScript projects. The skills work with any agent supporting the Agent Skills specification, including Claude Code, Cursor, GitHub Copilot, Windsurf, Gemini CLI, and 30+ others.

Fallow is a Rust-native static analysis tool with 84 built-in framework plugins (Next.js, Vite, Jest, Storybook, etc.), zero configuration requirements, and sub-second performance. The skills teach agents which commands to run, what flags to use, how to interpret JSON output, and how to avoid common pitfalls when performing codebase analysis.

## Dead Code Analysis

The `dead-code` command analyzes projects for unused files, exports, dependencies, types, and class/enum members. It supports 14 issue types with filter flags and outputs machine-readable JSON for agent consumption.

```bash
# Full dead code analysis with JSON output
fallow dead-code --format json --quiet 2>/dev/null || true

# Output structure:
# {
#   "schema_version": 3,
#   "total_issues": 12,
#   "unused_files": [{ "path": "src/old.ts" }],
#   "unused_exports": [{ "path": "src/utils.ts", "name": "unusedFn", "line": 42, "actions": [...] }],
#   "unused_types": [{ "path": "src/types.ts", "name": "OldType", "line": 10 }],
#   "unused_dependencies": [{ "name": "lodash", "line": 5 }],
#   "circular_dependencies": [{ "cycle": ["src/a.ts", "src/b.ts", "src/a.ts"], "line": 3 }]
# }

# Filter to specific issue types
fallow dead-code --format json --quiet --unused-exports 2>/dev/null || true
fallow dead-code --format json --quiet --unused-files --unused-deps 2>/dev/null || true

# PR check: only analyze files changed since main branch
fallow dead-code --format json --quiet --changed-since main --fail-on-issues 2>/dev/null || true

# Production-only analysis (excludes test files)
fallow dead-code --format json --quiet --production 2>/dev/null || true

# Single workspace package in monorepo
fallow dead-code --format json --quiet --workspace my-package 2>/dev/null || true
```

## Code Duplication Detection

The `dupes` command finds code clones across the project with four detection modes: strict (exact match), mild (syntax normalized), weak (different literals), and semantic (renamed variables).

```bash
# Default duplication scan (mild mode)
fallow dupes --format json --quiet 2>/dev/null || true

# Output structure:
# {
#   "schema_version": 3,
#   "total_clones": 15,
#   "total_lines_duplicated": 230,
#   "duplication_percentage": 4.2,
#   "clone_groups": [
#     {
#       "instances": [
#         { "path": "src/a.ts", "start_line": 10, "end_line": 25 },
#         { "path": "src/b.ts", "start_line": 40, "end_line": 55 }
#       ],
#       "tokens": 120,
#       "lines": 16
#     }
#   ]
# }

# Semantic mode detects renamed variables
fallow dupes --format json --quiet --mode semantic 2>/dev/null || true

# Cross-directory only, fail at 5% threshold
fallow dupes --format json --quiet --skip-local --threshold 5 2>/dev/null || true

# Only check duplication in changed files
fallow dupes --format json --quiet --changed-since main 2>/dev/null || true

# Trace clones at a specific location
fallow dupes --format json --quiet --trace src/utils.ts:42 2>/dev/null || true
```

## Auto-Fix Unused Code

The `fix` command automatically removes unused exports and dependencies. Always use `--dry-run` first to preview changes, then `--yes` to apply (required in non-TTY environments like agent subprocesses).

```bash
# Step 1: Preview what will be removed
fallow fix --dry-run --format json --quiet 2>/dev/null || true

# Output structure:
# {
#   "changes": [
#     { "path": "src/utils.ts", "action": "remove_export", "name": "unusedFn", "line": 42 },
#     { "path": "package.json", "action": "remove_dependency", "name": "lodash" }
#   ],
#   "total_changes": 2
# }

# Step 2: Apply changes (--yes is required in agent/CI environments)
fallow fix --yes --format json --quiet 2>/dev/null || true

# Step 3: Verify the fix worked
fallow dead-code --format json --quiet 2>/dev/null || true
```

## Function Complexity Analysis

The `health` command analyzes function complexity using cyclomatic and cognitive metrics, calculates file maintainability scores, identifies hotspots (complex + frequently changing files), and generates refactoring recommendations.

```bash
# Full complexity analysis
fallow health --format json --quiet 2>/dev/null || true

# Output includes findings array:
# {
#   "findings": [
#     {
#       "path": "src/parser.ts",
#       "name": "parseExpression",
#       "line": 42,
#       "cyclomatic": 28,
#       "cognitive": 22,
#       "line_count": 95,
#       "exceeded": "both"
#     }
#   ]
# }

# Project health score with letter grade (A/B/C/D/F)
fallow health --format json --quiet --score 2>/dev/null || true

# CI gate: fail if score below 70
fallow health --format json --quiet --min-score 70 2>/dev/null || true

# Top 10 most complex functions
fallow health --format json --quiet --top 10 2>/dev/null || true

# Per-file maintainability index
fallow health --format json --quiet --file-scores 2>/dev/null || true

# Hotspot analysis (complex + frequently changing files)
fallow health --format json --quiet --hotspots --since 6m 2>/dev/null || true

# Ranked refactoring recommendations
fallow health --format json --quiet --targets 2>/dev/null || true
```

## Changed-File Quality Gate (Audit)

The `audit` command provides a combined dead-code + complexity + duplication check for changed files, returning a verdict (pass/warn/fail). Purpose-built for PR quality gates and reviewing AI-generated code.

```bash
# Auto-detect base branch
fallow audit --format json --quiet 2>/dev/null || true

# Output structure:
# {
#   "verdict": "fail",
#   "changed_files_count": 12,
#   "base_ref": "main",
#   "summary": {
#     "dead_code_issues": 2,
#     "complexity_findings": 1,
#     "duplication_clone_groups": 0
#   },
#   "dead_code": { ... },
#   "complexity": { ... },
#   "duplication": { ... }
# }

# Explicit base ref
fallow audit --format json --quiet --base main 2>/dev/null || true

# Production code only in a monorepo workspace
fallow audit --format json --quiet --production --workspace @app/api 2>/dev/null || true

# CI mode (SARIF + fail on issues + quiet)
fallow audit --ci 2>/dev/null || true
```

## Project Introspection

The `list` command inspects discovered files, entry points, and detected frameworks. Useful for understanding what fallow will analyze.

```bash
# List all discovered files
fallow list --files --format json --quiet 2>/dev/null || true

# List detected entry points
fallow list --entry-points --format json --quiet 2>/dev/null || true

# List active framework plugins (84 built-in)
fallow list --plugins --format json --quiet 2>/dev/null || true
```

## Debug False Positives

The trace flags help investigate why specific exports or files are flagged as unused.

```bash
# Trace an export's usage chain
fallow dead-code --format json --quiet --trace src/utils.ts:myFunction 2>/dev/null || true

# Trace all edges for a file
fallow dead-code --format json --quiet --trace-file src/utils.ts 2>/dev/null || true

# Trace where a dependency is used
fallow dead-code --format json --quiet --trace-dependency lodash 2>/dev/null || true
```

## Initialize Configuration

The `init` command creates configuration files and git hooks. Most projects work with zero configuration thanks to auto-detecting plugins.

```bash
# Create .fallowrc.json with $schema
fallow init

# Create fallow.toml instead
fallow init --toml

# Scaffold a pre-commit git hook
fallow init --hooks

# Hook using custom base branch
fallow init --hooks --base develop
```

## Migrate from Other Tools

The `migrate` command converts configuration from knip and jscpd to fallow format.

```bash
# Preview migration
fallow migrate --dry-run

# Auto-detect and write .fallowrc.json
fallow migrate

# Output as TOML
fallow migrate --toml

# Migrate from specific file
fallow migrate --from knip.json
```

## Incremental Adoption with Baselines

Use baselines to adopt fallow gradually in projects with existing issues. Only new issues trigger CI failures.

```bash
# Save current state as baseline
fallow dead-code --format json --quiet --save-baseline .fallow-baseline.json 2>/dev/null || true

# Later: only fail on NEW issues not in the baseline
fallow dead-code --format json --quiet --baseline .fallow-baseline.json --fail-on-issues 2>/dev/null || true

# Regression detection with tolerance
fallow dead-code --format json --quiet --save-regression-baseline 2>/dev/null || true
fallow dead-code --format json --quiet --fail-on-regression --tolerance 2% 2>/dev/null || true
```

## Inline Suppression Comments

Suppress false positives or intentionally unused code with inline comments.

```typescript
// Suppress any issue on the next line
// fallow-ignore-next-line
export const keepThis = 1;

// Suppress specific issue type
// fallow-ignore-next-line unused-export
export const keepThisToo = 2;

// Suppress all issues in a file
// fallow-ignore-file

// Suppress specific issue type file-wide
// fallow-ignore-file unused-export

// Suppress duplication findings
// fallow-ignore-next-line code-duplication
const handler = createStandardHandler(config);
```

## Configuration File Format

Fallow reads config from `.fallowrc.json`, `fallow.toml`, or `.fallow.toml`. Most projects need no configuration.

```jsonc
{
  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
  "entry": ["src/index.ts"],
  "ignorePatterns": ["**/*.generated.ts"],
  "ignoreDependencies": ["autoprefixer"],
  "rules": {
    "unused-files": "error",
    "unused-exports": "warn",
    "unused-types": "off",
    "type-only-dependencies": "error",
    "test-only-dependencies": "warn"
  },
  "duplicates": {
    "mode": "mild",
    "minTokens": 50,
    "minLines": 5,
    "threshold": 0
  }
}
```

## GitHub Actions Integration

```yaml
# Basic dead code check
- name: Dead code check
  run: npx fallow dead-code --fail-on-issues --quiet

# With SARIF upload to Code Scanning
- name: Fallow analysis
  run: npx fallow dead-code --ci > fallow.sarif
  continue-on-error: true

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: fallow.sarif

# Using the official action with PR annotations
- uses: fallow-rs/fallow@v2
  with:
    command: dead-code
    changed-since: main
    annotations: true
    fail-on-issues: true
```

## GitLab CI Integration

```yaml
include:
  - remote: 'https://raw.githubusercontent.com/fallow-rs/fallow/main/ci/gitlab-ci.yml'

fallow:
  extends: .fallow
  variables:
    FALLOW_COMMAND: "dead-code"
    FALLOW_FAIL_ON_ISSUES: "true"
    FALLOW_COMMENT: "true"      # Post MR summary comment
    FALLOW_REVIEW: "true"       # Post inline review comments
```

## Summary

Fallow Skills enables AI agents to perform comprehensive static analysis on JavaScript and TypeScript codebases. The primary use cases include: auditing projects for dead code and unused dependencies, detecting code duplication before it spreads, enforcing complexity thresholds in CI, safely auto-fixing unused exports, and setting up incremental adoption pipelines for legacy codebases with baselines.

Integration patterns follow a consistent approach: always use `--format json --quiet 2>/dev/null` for machine-readable output, append `|| true` to prevent exit code 1 (issues found) from breaking pipelines, use `--dry-run` before any `fix` operation, and leverage `--changed-since` for PR-scoped analysis. The 84 built-in framework plugins mean most projects work with zero configuration, while the rules system and inline suppression comments provide fine-grained control when needed.