Skip to content

Commit 721ae01

Browse files
BartWaardenburgBartWaardenburg
committed
feat: initial fallow-skills with dead code & duplication analysis skill
Agent skills for finding and removing dead code, unused dependencies, and code duplication in JS/TS projects using fallow. Includes complete CLI reference, gotchas with WRONG/CORRECT examples, and workflow recipes for CI, monorepos, migration, and incremental adoption.
0 parents  commit 721ae01

11 files changed

Lines changed: 1917 additions & 0 deletions

File tree

‎.claude-plugin/marketplace.json‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"name": "fallow",
3+
"version": "1.0.0",
4+
"description": "Agent skills for finding and removing dead code, unused dependencies, and code duplication in JavaScript/TypeScript projects using fallow",
5+
"author": {
6+
"name": "Bart Waardenburg",
7+
"url": "https://github.com/bartwaardenburg"
8+
},
9+
"homepage": "https://github.com/fallow-rs/fallow-skills",
10+
"repository": {
11+
"type": "git",
12+
"url": "https://github.com/fallow-rs/fallow-skills.git"
13+
},
14+
"license": "MIT",
15+
"keywords": [
16+
"fallow",
17+
"dead-code",
18+
"unused-exports",
19+
"unused-dependencies",
20+
"code-duplication",
21+
"javascript",
22+
"typescript",
23+
"codebase-hygiene",
24+
"static-analysis",
25+
"lint"
26+
]
27+
}

‎.claude-plugin/plugin.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"name": "fallow-skills",
3+
"version": "1.0.0",
4+
"description": "Agent skills for finding and removing dead code, unused dependencies, and code duplication in JavaScript/TypeScript projects using fallow",
5+
"author": {
6+
"name": "Bart Waardenburg",
7+
"url": "https://github.com/bartwaardenburg"
8+
},
9+
"homepage": "https://github.com/fallow-rs/fallow-skills",
10+
"repository": {
11+
"type": "git",
12+
"url": "https://github.com/fallow-rs/fallow-skills.git"
13+
},
14+
"license": "MIT",
15+
"plugins": [
16+
{
17+
"name": "fallow",
18+
"path": "."
19+
}
20+
]
21+
}

‎.github/workflows/validate.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Validate
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
validate:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
15+
- name: Validate JSON files
16+
run: |
17+
echo "Validating JSON files..."
18+
for f in $(find . -name "*.json" -not -path "./node_modules/*"); do
19+
echo " Checking $f"
20+
python3 -c "import json; json.load(open('$f'))" || exit 1
21+
done
22+
echo "All JSON files are valid."
23+
24+
- name: Validate SKILL.md frontmatter
25+
run: |
26+
echo "Validating SKILL.md files..."
27+
for f in $(find . -name "SKILL.md"); do
28+
echo " Checking $f"
29+
head -1 "$f" | grep -q "^---$" || { echo "ERROR: $f missing frontmatter"; exit 1; }
30+
awk '/^---$/{n++; next} n==1{print}' "$f" | grep -q "^name:" || { echo "ERROR: $f missing 'name' in frontmatter"; exit 1; }
31+
awk '/^---$/{n++; next} n==1{print}' "$f" | grep -q "^description:" || { echo "ERROR: $f missing 'description' in frontmatter"; exit 1; }
32+
done
33+
echo "All SKILL.md files are valid."
34+
35+
- name: Check for hardcoded paths
36+
run: |
37+
echo "Checking for hardcoded paths..."
38+
if grep -rn "/Users/" --include="*.md" --include="*.json" .; then
39+
echo "ERROR: Found hardcoded user paths"
40+
exit 1
41+
fi
42+
echo "No hardcoded paths found."
43+
44+
- name: Check version sync
45+
run: |
46+
echo "Checking version sync..."
47+
MARKETPLACE_VERSION=$(python3 -c "import json; print(json.load(open('.claude-plugin/marketplace.json'))['version'])")
48+
PLUGIN_VERSION=$(python3 -c "import json; print(json.load(open('.claude-plugin/plugin.json'))['version'])")
49+
if [ "$MARKETPLACE_VERSION" != "$PLUGIN_VERSION" ]; then
50+
echo "ERROR: Version mismatch - marketplace.json ($MARKETPLACE_VERSION) != plugin.json ($PLUGIN_VERSION)"
51+
exit 1
52+
fi
53+
echo "Versions in sync: $MARKETPLACE_VERSION"

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.DS_Store
2+
node_modules/
3+
*.log

‎CLAUDE.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# fallow-skills
2+
3+
Agent skills for finding and removing dead code, unused dependencies, and code duplication in JavaScript/TypeScript projects using [fallow](https://github.com/fallow-rs/fallow).
4+
5+
## Repository Structure
6+
7+
```
8+
.claude-plugin/
9+
marketplace.json # Marketplace metadata
10+
plugin.json # Plugin metadata
11+
fallow-analysis/ # Dead code & duplication analysis skill
12+
SKILL.md # Skill entry point
13+
references/
14+
cli-reference.md # Complete CLI specs and output formats
15+
gotchas.md # Common pitfalls and edge cases
16+
patterns.md # Workflow recipes for CI, monorepos, migration
17+
.github/
18+
workflows/
19+
validate.yml # CI validation
20+
```
21+
22+
## Creating a New Skill
23+
24+
1. Create a directory with a kebab-case name (e.g. `fallow-ci/`)
25+
2. Add a `SKILL.md` with YAML frontmatter:
26+
- `name` (required): kebab-case skill name
27+
- `description` (required): Third-person, includes trigger phrases, 1-2 sentences
28+
3. Add a `references/` directory for supplementary documentation
29+
4. Update `.claude-plugin/plugin.json` if adding to the plugin
30+
31+
### SKILL.md Requirements
32+
33+
- Under 500 lines — keep focused, put details in references
34+
- Include "When to Use" and "When NOT to Use" sections
35+
- Include step-by-step workflows for common tasks
36+
- Use progressive disclosure: SKILL.md links to reference files, references don't chain
37+
- No hardcoded file paths
38+
39+
### Reference Files
40+
41+
- `cli-reference.md` — command specs, flags, output formats
42+
- `gotchas.md` — common pitfalls with WRONG/CORRECT examples
43+
- `patterns.md` — recipes and common workflows
44+
45+
### Naming Conventions
46+
47+
- Directories: kebab-case (`fallow-analysis`)
48+
- Skill names: kebab-case (`fallow-analysis`)
49+
- Reference files: kebab-case (`cli-reference.md`)
50+
51+
## Quality Standards
52+
53+
- Description must include trigger phrases ("Use when asked to...")
54+
- Every gotcha must include correct vs incorrect example
55+
- Workflows must be numbered step-by-step
56+
- Destructive operations (auto-fix) must note dry-run requirement
57+
- All commands tested against the actual fallow CLI before documenting
58+
59+
## PR Checklist
60+
61+
- [ ] SKILL.md has valid YAML frontmatter with `name` and `description`
62+
- [ ] No hardcoded file paths
63+
- [ ] Skill is under 500 lines
64+
- [ ] "When to Use" and "When NOT to Use" sections present
65+
- [ ] All JSON files are valid
66+
- [ ] marketplace.json and plugin.json versions are in sync

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Bart Waardenburg
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# fallow-skills
2+
3+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
4+
[![CI](https://github.com/fallow-rs/fallow-skills/actions/workflows/validate.yml/badge.svg)](https://github.com/fallow-rs/fallow-skills/actions/workflows/validate.yml)
5+
6+
Agent skills for finding and removing dead code, unused dependencies, and code duplication in JavaScript/TypeScript projects using [fallow](https://github.com/fallow-rs/fallow). Works with any agent that supports the [Agent Skills](https://agentskills.io) specification — Claude Code, Cursor, OpenAI Codex, Windsurf, GitHub Copilot, Gemini CLI, Amp, and more.
7+
8+
## Features
9+
10+
- **11 dead code issue types** — unused files, exports, dependencies, types, enum/class members, and more
11+
- **4 duplication detection modes** — strict, mild, weak, and semantic clone detection
12+
- **Step-by-step workflows** for CI setup, monorepo analysis, migration, and incremental adoption
13+
- **Gotcha documentation** covering agent-specific pitfalls and correct usage patterns
14+
- **Companion skill** to the [fallow](https://github.com/fallow-rs/fallow) CLI and [fallow-docs](https://docs.fallow.tools)
15+
16+
## Prerequisites
17+
18+
Fallow must be installed in the target project. The fastest way:
19+
20+
```bash
21+
npm install -g fallow
22+
```
23+
24+
Or run without installing:
25+
26+
```bash
27+
npx fallow check
28+
```
29+
30+
See the [fallow installation guide](https://docs.fallow.tools/installation) for all options.
31+
32+
## Installation
33+
34+
### Claude Code
35+
36+
```bash
37+
/install fallow-rs/fallow-skills
38+
```
39+
40+
### Cursor
41+
42+
Clone into Cursor's skills directory:
43+
44+
```bash
45+
git clone https://github.com/fallow-rs/fallow-skills.git ~/.cursor/skills/fallow-skills
46+
```
47+
48+
### OpenAI Codex
49+
50+
Clone into the Codex skills directory:
51+
52+
```bash
53+
git clone https://github.com/fallow-rs/fallow-skills.git ~/.agents/skills/fallow-skills
54+
```
55+
56+
### Windsurf
57+
58+
Clone into the Windsurf skills directory:
59+
60+
```bash
61+
git clone https://github.com/fallow-rs/fallow-skills.git ~/.codeium/windsurf/skills/fallow-skills
62+
```
63+
64+
### GitHub Copilot / VS Code
65+
66+
Clone into your project or user skills directory:
67+
68+
```bash
69+
git clone https://github.com/fallow-rs/fallow-skills.git ~/.agents/skills/fallow-skills
70+
```
71+
72+
### Gemini CLI
73+
74+
```bash
75+
gemini skills install https://github.com/fallow-rs/fallow-skills.git
76+
```
77+
78+
### Amp
79+
80+
Clone into the Amp skills directory:
81+
82+
```bash
83+
git clone https://github.com/fallow-rs/fallow-skills.git ~/.config/agents/skills/fallow-skills
84+
```
85+
86+
### Other Agents
87+
88+
Clone or copy the skill directory into your agent's skills location. This skill follows the open [Agent Skills](https://agentskills.io) specification and works with any compatible agent.
89+
90+
## Available Skills
91+
92+
| Skill | Description |
93+
|---|---|
94+
| [fallow-analysis](fallow-analysis/) | Find dead code, unused dependencies, and code duplication in JS/TS projects |
95+
96+
## What's Included
97+
98+
### fallow-analysis
99+
100+
Covers all fallow CLI commands for dead code and duplication analysis:
101+
102+
| Category | Key Operations |
103+
|---|---|
104+
| Dead Code Detection | Find unused files, exports, types, dependencies, enum/class members |
105+
| Duplication Detection | Find code clones with 4 detection modes (strict, mild, weak, semantic) |
106+
| Auto-Fix | Remove unused exports and dependencies with dry-run preview |
107+
| CI Integration | GitHub Actions, SARIF upload, baseline comparison, PR-scoped checks |
108+
| Migration | Auto-migrate from knip and jscpd configurations |
109+
| Monorepo Support | Per-workspace analysis with cross-package resolution |
110+
| Debugging | Trace export usage chains, file edges, and dependency usage |
111+
112+
### Reference Documentation
113+
114+
Each skill includes structured reference files:
115+
116+
- **[CLI Reference](fallow-analysis/references/cli-reference.md)** — complete command and flag specifications, output formats, config file format
117+
- **[Gotchas](fallow-analysis/references/gotchas.md)** — common pitfalls, edge cases, and correct usage patterns
118+
- **[Patterns](fallow-analysis/references/patterns.md)** — workflow recipes for CI, monorepos, migration, incremental adoption, and more
119+
120+
## Example Prompts
121+
122+
Once installed, you can use natural language:
123+
124+
- "Find all dead code in this project"
125+
- "Are there any unused dependencies?"
126+
- "Find code duplication in the codebase"
127+
- "Clean up unused exports"
128+
- "Set up a CI check for dead code"
129+
- "Migrate my knip config to fallow"
130+
- "Why is this export flagged as unused?"
131+
- "Check if this PR introduces dead code"
132+
- "Find unused files in the payments package"
133+
134+
## Contributing
135+
136+
See [CLAUDE.md](CLAUDE.md) for repository structure, skill creation guidelines, and quality standards.
137+
138+
## Related
139+
140+
- [fallow](https://github.com/fallow-rs/fallow) — The Rust-native dead code analyzer
141+
- [fallow-docs](https://docs.fallow.tools) — Official documentation
142+
- [fallow VS Code extension](https://marketplace.visualstudio.com/items?itemName=fallow.fallow-vscode) — Real-time dead code diagnostics in your editor
143+
144+
## License
145+
146+
MIT — see [LICENSE](LICENSE) for details.

0 commit comments

Comments
 (0)