How do I install the Refactor Squatters skill?

Run npx skillmds add majiayu000/refactor-squatters in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Refactor Squatters safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Refactor Squatters?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Refactor Squatters free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.

Who published Refactor Squatters?

majiayu000 (@majiayu000) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Refactor Squatters by majiayu000 — Agent Skill

Name: Refactor Squatters
Rating: 4.2 (5 reviews)
Author: majiayu000

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.

majiayu000 6dd90b0 2 files · 3.4 KB Updated Sep 9, 2026 567 repo stars

File contents

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:

Agentic programming prioritizes "make it work" over "make it belong"
Domain modeling was deferred — the code landed somewhere expedient
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

# 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

---name: refactor-squattersdescription: 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.license: MIT--- # 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 ```

Frequently asked questions