Getting Started
Agent Skill
Use jscpd with AI coding assistants to automatically detect and refactor code duplications.
Overview
jscpd ships two agent skills for skills.sh that teach AI coding assistants (Claude, Copilot, Gemini, Cursor, and others) how to detect and eliminate code duplication:
- jscpd — tool reference skill. Covers all CLI options, the AI reporter output format, and configuration file syntax.
- dry-refactoring — refactoring workflow skill. A guided process for reading clone output, choosing the right extraction strategy, applying the refactor, and verifying the clone is eliminated.
Installation
Terminal
# Install both skills
npx skills add kucherenko/jscpd
# Or install individually
npx skills add kucherenko/jscpd --skill jscpd
npx skills add kucherenko/jscpd --skill dry-refactoring
Once installed, ask your agent to "find and fix code duplication" and it will invoke jscpd with the right options and act on the results.
jscpd Skill
The jscpd skill instructs the agent to:
- Run jscpd with the
aireporter on the target path - Parse the detected clone pairs (file paths + line ranges)
- Report back with a summary of duplications
Key Options
| Option | Description |
|---|---|
--reporters ai | Use the AI-optimized reporter (compact clone list) |
--reporters html | Generate HTML report |
--min-tokens N | Minimum tokens for a duplication (default: 50) |
--min-lines N | Minimum lines for a duplication (default: 5) |
--ignore "glob" | Ignore patterns (comma-separated) |
--format "list" | Limit to specific languages |
--store "type" | Accepted for compatibility; external stores not available in v5 (detection is fast enough) |
--store-path "path" | Accepted for compatibility; not used in v5 |
--noTips | Disable tips in output (also suppressed by --silent) |
--skipComments | Alias for --mode weak (strip comments before detection) |
--formats-names "map" | Map filenames to formats |
--mode "mode" | Detection quality: strict, mild, weak |
--blame | Blame authors of duplications from git |
--silent | Do not write detection progress and results to console |
--absolute | Use absolute paths in reports |
--ignoreCase | Ignore case of symbols in code (experimental) |
--exitCode N | Exit code when duplications are detected |
--verbose | Show full information during detection process |
Example Configuration
.jscpd.json
{
"threshold": 0,
"reporters": ["ai"],
"ignore": ["**/node_modules/**", "**/dist/**", "**/*.min.*"],
"format": ["typescript", "javascript"],
"minLines": 5,
"minTokens": 50,
"output": "./reports/jscpd"
}
dry-refactoring Skill
The dry-refactoring skill guides the agent through eliminating duplications:
- Run jscpd with
--reporters aion the target path - Parse each clone line to identify the two duplicated locations (file + line range)
- Read both code fragments from the source files
- Understand what the duplicated code does
- Design a refactoring — extract a shared function, class, module, or constant
- Apply the refactoring — update both locations and all other usages
- Re-run jscpd to confirm the clone is eliminated
- Repeat for remaining clones, highest-impact first
Refactoring Strategies
| Strategy | When to use |
|---|---|
| Extract function | Duplicate is a block of logic |
| Extract module/utility | Duplicate spans multiple files in different domains |
| Extract constant/config | Duplicate is repeated data or configuration |
| Template/base class | Duplicate has a repeated class shape |
Tips
- Start with clones that have the highest line count — most impact
- A clone between test files may indicate a missing test helper
- Clones across unrelated modules may signal a missing shared utility
- Use
--min-lines 10to filter noise and focus on meaningful duplications
How It Uses the AI Reporter
The skills use the ai reporter, which produces compact, token-efficient output:
Terminal
npx jscpd --reporters ai ./src
Example output:
Clones:
src/utils/ auth.ts:10-25 ~ helpers.ts:40-55
src/utils/auth.ts 30-45 ~ 80-95
---
2 clones · 3.1% duplication
This format uses ~79% fewer tokens than the default reporter, keeping context usage low while giving the agent everything it needs to locate and fix each duplication.
More Information
- Skill page: skills.sh/kucherenko/jscpd
- AI Reporter docs: Reporters
- Configuration: Configuration