Agent skill

refactor-squatters

Detect squatters: modules and packages that occupy namespace positions they do not semantically own. Identifies utility dumps, stuttery siblings, axis violations, layer bleeding, and semantic diffusion — common structural smells introduced by agentic programming.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/squatters

Metadata

Additional technical details for this skill

author
Jordan Godau
scripts 
[
    "detect.sh",
    "detect.ps1"
]
keywords
squatters namespace integrity wrong home misplaced utility dump common helpers utils stutter sibling axis violation layer bleeding semantic diffusion homeless concept
references 
[
    "01_GOAL.md",
    "02_DEFINITIONS.md",
    "03_INVARIANTS.md",
    "04_HEURISTICS.md",
    "05_PROCEDURE.md",
    "06_REMEDIATION.md",
    "07_OUTPUT.md"
]

SKILL.md

Instructions

Read all references in references/ before using this skill.

What is a Squatter?

A squatter is a module or package that occupies a namespace position it does not semantically own.

In real estate, squatters occupy property without legal claim. In codebases, squatters occupy import paths without conceptual legitimacy. They exist because:

  1. Agentic programming prioritizes "make it work" over "make it belong"
  2. Domain modeling was deferred — the code landed somewhere expedient
  3. Compensatory naming masked the misplacement (e.g., las_fields.py instead of las/fields.py)

Squatters degrade navigability. A developer (or agent) cannot guess where code lives because the filesystem lies about ownership.

Central Invariant

Every module should be importable from a path that a domain expert would guess correctly.

If a module name compensates for weak structure, or sits beside a package it should be inside, the filesystem is lying about the domain model.

Signals

  • Reviewing package structure after significant growth
  • Noticing common/, utils/, or helpers/ packages
  • Seeing modules with underscore prefixes matching sibling package names (e.g., las_fields.py beside las/)
  • Finding single-function modules that only wrap a foreign dependency
  • Observing imports that cross architectural layers upward

References

Directory: references/

  • 01_GOAL.md — What this skill accomplishes
  • 02_DEFINITIONS.md — Vocabulary for squatters and namespace violations
  • 03_INVARIANTS.md — Rules that determine violations
  • 04_HEURISTICS.md — Detection patterns and signals
  • 05_PROCEDURE.md — Step-by-step audit process
  • 06_REMEDIATION.md — Refactoring directions (hypotheses, not mandates)
  • 07_OUTPUT.md — Report format and severity classification

Scripts

Directory: scripts/

  • detect.sh: Scan for structural smells (macOS/Linux/WSL)
  • detect.ps1: Scan for structural smells (Windows)

Usage

bash
# Scan a package for squatters
.codex/skills/refactor/squatters/scripts/detect.sh pulsar/api

# Scan with specific pattern focus
.codex/skills/refactor/squatters/scripts/detect.sh pulsar/api --pattern utility-dump
.codex/skills/refactor/squatters/scripts/detect.sh pulsar/api --pattern stuttery-sibling

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results