code-smells

Files (1)

• SKILL.md

SKILL.md (first lines)

# Code Smells Detection Skill

Analyze code for smells, anti-patterns, and refactoring opportunities. Read-only analysis — no code changes.

## When to Use
- Before starting a refactoring effort
- During code review to identify structural issues
- When a module "feels wrong" but you can't pinpoint why
- To assess technical debt in a specific area

## Process

1. **Determine scope**: Use `$ARGUMENTS` as target path. Default to current project root.

2. **Automated scan**: Run available tools based on project type:

   **JavaScript/TypeScript:**
   ```
   npx knip --reporter compact 2>/dev/null          # unused exports/deps
   npx depcheck 2>/dev/null                           # unused packages
   wc -l $(find <scope> -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx') | sort -rn | head -20
   ```

   **Python:**
   ```
   pylint --disable=all --enable=R,C <scope> 2>/dev/null | head -30
   wc -l $(find <scope> -name '*.py') | sort -rn | head -20
   ```

   **General (any language):**
   ```
   # Largest files (complexity indicator)
   wc -l <files> | sort -rn | head -20

   # Deep nesting
   grep -rn '^\s\{12,\}' <scope> --include='*.ts' --include='*.py' | head -20

   # Magic numbers
   grep -rn '[^a-zA-Z0-9_]\([0-9]\{3,\}\)[^a-zA-Z0-9_]' <scope> | head -20

   # TODO/FIXME/HACK markers
   grep -rn 'TODO\|FIXME\|HACK\|XXX\|WORKAROUND' <scope> | head -30
   ```

3. **Manual inspection**: Read the top 5 largest files. Look for:
   - Functions > 40 lines
   - Classes > 300 lines or 10+ methods
   - Parameter lists > 5 params
   - Nested conditions > 3 levels deep
   - Duplicated code blocks (similar structure in multiple places)
   - God objects (one module importing/used by everything)

4. **Dependency check**: Grep for circular imports:
   ```
   # Map imports to find circular references
   grep -rn "import.*from\|require(" <scope> --include='*.ts' --include='*.js'
   ```

## Severity Classification

| Severity | Criteria | Action |
|----------|----------|--------|
| **Critical** | Bugs likely, blocking testability, circular deps | Fix immediately |
| **Major** | Maintainability risk, high complexity, large duplication | Plan refactoring |
| **Minor** | Style issues, small duplication, naming inconsistency | Fix opportunistically |
| **Info** | Suggestions, potential improvements | Track for later |

## Output Format

```
## Code Smell Report: [scope]

### Quick Stats
- Files scanned: N
- Largest file: [path] (N lines)
- Deepest nesting: [path:line] (N levels)
- TODO/FIXME count: N

### Findings

#### Critical (N)
- **[Smell Type]** `path/file.ts:L` — [description]
  → Suggested: [refactoring pattern]

#### Major (N)
- **[Smell Type]** `path/file.ts:L` — [description]
  → Suggested: [refactoring pattern]

#### Minor (N)
- **[Smell Type]** `path/file.ts:L` — [description]

### Hotspot Files (most smells concentrated)
1. `path/file.ts` — N findings
2. `path/file.ts` — N findings

### Recommended Next Steps
1. [Most impactful action]
2. [Second priority]
3. Run `/refactor <scope>` to execute automated refactoring
```

## Rules
- Read-only. Never modify code.
- Verify every finding with Grep before reporting — no false positives.
- If automated tools aren't available, rely on manual inspection.
- Always include file:line references for every finding.
- Sort findings by severity, then by file (group related smells together).

From Hbin77/codex-kit, MIT.

More from Hbin77/codex-kit