Skip to main content
skill CX Codex

code-clone-assistant — Claude Code skill

code-clone-assistant detects duplicate code using PMD CPD and Semgrep, guides refactoring of DRY violations. Catches both exact clones and similar patterns.

MIT 139 installs ★ 3 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill code-clone-assistant -a claude-code
Open on GitHub

What code-clone-assistant does

The skill combines two detection engines to find different types of duplication. PMD CPD identifies exact copies—code where variables may be renamed but structure stays the same. Semgrep locates patterns with variations, where logic is similar but details differ. Together they surface roughly three times more violations than either tool alone.

Workflow: PMD CPD scans files first and reports exact duplicates, then Semgrep checks patterns against rules, and results are analyzed together. The skill distinguishes between duplication safe to consolidate and intentional patterns to preserve—test fixtures, SQL templates without include mechanisms, or experiment directories meant to remain immutable.

Requires PMD CPD v7.17.0+ and Semgrep v1.140.0+ installed. The skill operates through Read, Grep, Bash, Edit, and Write tools.

What it helps with

  • locate copy-pasted code across a codebase
  • identify DRY principle violations
  • prioritize code duplication by refactoring readiness
  • distinguish accidental duplication from intentional patterns

Example prompts for the agent

  • Find all code clones in src/ using PMD CPD and Semgrep
  • Check which duplicates in api/ can be merged into a shared function
  • Scan sql/ for repeated patterns, respecting exceptions declared in CLAUDE.md

How to install code-clone-assistant

1Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill code-clone-assistant -a claude-code

2Manually: put the files in place

~/.claude/skills/code-clone-assistant/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/code-clone-assistant/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about code-clone-assistant

How do I install code-clone-assistant in Claude Code?

Run npx skills add terrylica/cc-skills --skill code-clone-assistant -a claude-code, then open ~/.claude/skills/code-clone-assistant/SKILL.md.

What does code-clone-assistant do?

It detects duplicate code in two ways: PMD CPD finds exact copies, Semgrep catches similar patterns. It helps refactor code and reduce duplication across your project.

What do I need to use this skill?

You need PMD CPD v7.17.0+ and Semgrep v1.140.0+ installed. The skill uses Read, Grep, Bash, Edit, and Write tools.

Source text

SKILL.md · MIT
---
name: code-clone-assistant
description: Detect and refactor code duplication with PMD CPD. TRIGGERS - code clones, DRY violations, duplicate code.
allowed-tools: Read, Grep, Bash, Edit, Write
---

# Code Clone Assistant

Detect code clones and guide refactoring using PMD CPD (exact duplicates) + Semgrep (patterns).

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## Tools

- **PMD CPD v7.17.0+**: Exact duplicate detection
- **Semgrep v1.140.0+**: Pattern-based detection

**Tested**: October 2025 - 30 violations detected across 3 sample files
**Coverage**: ~3x more violations than using either tool alone

---

## When to Use This Skill

Use this skill when:

- Finding duplicate code in a codebase
- Detecting DRY violations
- Refactoring similar code patterns
- Identifying copy-paste code

---

## Why Two Tools?

PMD CPD and Semgrep detect different clone types:

| Aspect       | PMD CPD                          | Semgrep                          |
| ------------ | -------------------------------- | -------------------------------- |
| **Detects**  | Exact copy-paste duplicates      | Similar patterns with variations |
| **Scope**    | Across files ✅                  | Within/across files (Pro only)   |
| **Matching** | Token-based (ignores formatting) | Pattern-based (AST matching)     |
| **Rules**    | ❌ No custom rules               | ✅ Custom rules                  |

**Result**: Using both finds ~3x more DRY violations.

### Clone Types

| Type   | Description                     | PMD CPD         | Semgrep     |
| ------ | ------------------------------- | --------------- | ----------- |
| Type-1 | Exact copies                    | ✅ Default      | ✅          |
| Type-2 | Renamed identifiers             | ✅ `--ignore-*` | ✅          |
| Type-3 | Near-miss with variations       | ⚠️ Partial      | ✅ Patterns |
| Type-4 | Semantic clones (same behavior) | ❌              | ❌          |

---

## Quick Start Workflow

```bash
# Step 1: Detect exact duplicates (PMD CPD)
pmd cpd -d . -l python --minimum-tokens 20 -f markdown > pmd-results.md

# Step 2: Detect pattern violations (Semgrep)
semgrep --config=clone-rules.yaml --sarif --quiet > semgrep-results.sarif

# Step 3: Analyze combined results (Claude Code)
# Parse both outputs, prioritize by severity

# Step 4: Refactor (Claude Code with user approval)
# Extract shared functions, consolidate patterns, verify tests
```

---

---

## Accepted Exceptions (Known Intentional Duplication)

Not all code duplication is a problem. Some codebases deliberately use copy-and-adapt patterns where refactoring would be harmful. When running clone detection, **always check for accepted exceptions before recommending refactoring**.

### When Duplication Is Acceptable

| Pattern                                         | Why Acceptable                                                                                                                                                                                                    | Example                                                            |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Generation-per-directory experiments**        | Each generation is an immutable, self-contained experiment. Sharing code across generations would break provenance and make past experiments non-reproducible.                                                    | SQL templates, sweep scripts where each `gen{NNN}/` is independent |
| **SQL templates with placeholder substitution** | SQL has no import/include mechanism. Templates use `sed` placeholder replacement (`__PLACEHOLDER__`), not function calls. Extracting shared CTEs into separate files would break the single-file execution model. | ClickHouse sweep templates sharing signal detection + metrics CTEs |
| **Protocol/schema boilerplate**                 | Serialization formats, API contracts, and wire protocols require exact structure in each location. Abstracting them hides the contract.                                                                           | NDJSON telemetry line construction in wrapper scripts              |
| **Test fixtures and golden files**              | Test data intentionally duplicates production patterns to verify behavior. Sharing fixtures creates brittle cross-test dependencies.                                                                              | Test setup code, expected output snapshots                         |

### How to Report Accepted Exceptions

When clone detection finds duplication that matches an accepted exception pattern:

1. **Report it** — always show the user what was found (lines, tokens, files)
2. **Flag as accepted** — explicitly state it matches a known exception pattern
3. **Explain why** — cite the specific reason refactoring is not recommended
4. **Do NOT recommend refactoring** — this is the key difference from actionable findings

**Example output format**:

```
Code Clone Analysis Results

PMD CPD Findings:
  Clone 1: 115 lines (575 tokens) — base_bars → signals CTEs
    gen610_template.sql:33 ↔ gen710_template.sql:38
    Status: ACCEPTED EXCEPTION (generation-per-directory experiment)
    Reason: Each generation is immutable. Shared CTEs would break
            experiment provenance and reproducibility.

  Clone 2: 36 lines (478 tokens) — metrics aggregation
    gen610_template.sql:207 ↔ gen710_template.sql:244
    Status: ACCEPTED EXCEPTION (SQL template without include mechanism)

Actionable Findings: 0
Accepted Exceptions: 2
```

### Project-Level Exception Configuration

Projects can declare accepted exception patterns in their `CLAUDE.md`:

```markdown
## Code Clone Exceptions

- `sql/gen*_template.sql` — generation-per-directory experiments (immutable)
- `scripts/gen*/` — copy-and-adapt sweep scripts (no shared infrastructure)
- `tests/fixtures/` — intentional duplication for test isolation
```

When this section exists in a project's `CLAUDE.md`, the code-clone-assistant should check it before classifying findings.

---

## Reference Documentation

For detailed information, see:

- [Detection Commands](./references/detection-commands.md) - PMD CPD and Semgrep command details
- [Complete Workflow](./references/complete-workflow.md) - Detection, analysis, and presentation phases
- [Refactoring Strategies](./references/refactoring-strategies.md) - Approaches for addressing violations

---

## Troubleshooting

| Issue                      | Cause                        | Solution                                         |
| -------------------------- | ---------------------------- | ------------------------------------------------ |
| PMD CPD not found          | Not installed or not in PATH | `brew install pmd` or download from PMD releases |
| Semgrep timeout            | Large codebase scan          | Use `--exclude` to limit scope                   |
| No duplicates detected     | minimum-tokens too high      | Lower `--minimum-tokens` value (try 15)          |
| Too many false positives   | minimum-tokens too low       | Increase `--minimum-tokens` (try 30+)            |
| Language not recognized    | Wrong `-l` flag              | Check PMD CPD supported languages list           |
| SARIF parse error          | Semgrep output malformed     | Upgrade Semgrep to latest version                |
| Memory error on large repo | Java heap too small          | Set `PMD_JAVA_OPTS=-Xmx4g`                       |
| Missing clone rules file   | Custom rules not created     | Create `clone-rules.yaml` or use default config  |


## Post-Execution Reflection

After this skill completes, check before closing:

1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

© terrylica · MIT · terrylica/cc-skills

Similar skills

All skills for Code review and refactoring →

From the same set79

The whole set →
adaptive-wfo-epoch adaptive-wfo-epoch sets how many epochs to train on each walk-forward fold, ranking candidates by walk-forward efficiency rather than one fixed number for the whole run. CX Codex +1 146installs log-reader log-reader reads MetaTrader 5 log files and Print() output straight from UTF-16LE daily logs without checking the Experts tab manually. CX Codex +1 145installs adr-code-traceability The adr-code-traceability skill links code to Architecture Decision Records with file headers or inline comments. Use it when an implementation choice needs a clear connection to its decision record. CX Codex +1 144installs mlflow-python mlflow-python is a Claude Code skill for logging backtest parameters and metrics in MLflow, searching experiment runs, and retrieving metric history via the Python API. CX Codex +1 139installs article-extractor article-extractor downloads technical articles and documentation from mql5.com for reference or training datasets. Useful for collecting MQL5 code examples by URL or author. CX Codex +1 138installs glossary-management glossary-management is a Claude Code skill that maintains a terminology glossary and connects it to Vale. It runs for glossary edits, term additions, validation, and sync requests. CX Codex +1 138installs gmail-access The gmail-access skill connects the agent to a Gmail command-line client so it can pull messages, search a mailbox, save what it finds and stage drafts. Handy when the thread you need sits next to the code you are working on. CX Codex +1 137installs skill-architecture skill-architecture guides skill creation and updates, YAML structure checks, and common troubleshooting. Task templates help you choose a workflow before editing files. CX Codex +1 137installs

Project sponsors

Companies that keep this analytics open