Paperthin: Teaching AI Agents to Delete Code by Encoding Design Patterns as Markdown
Hook
Every LLM coding assistant knows how to add code. Almost none know when to throw it away and start over. Paperthin fixes this by making 'rewrite from scratch' a reflex instead of a last resort.
Context
If you've worked with AI coding assistants for more than a month, you've seen the pattern: clean codebase degrades into a maze of redundant utilities, half-implemented abstractions, and documentation spread across eight different markdown files. The agent is helpful—too helpful. It patches instead of redesigning. It adds error handling instead of questioning why the error exists. It writes documentation wherever you ask, with no concept of single-source-of-truth.
The standard fix is to write better prompts or add custom instructions. But prompts are ephemeral, and custom instructions are vendor-locked. If you've carefully tuned your GitHub Copilot setup, none of that knowledge transfers to Claude or Cursor. Worse, there's no way to share these hard-won patterns with your team as versioned, reviewable artifacts. Paperthin approaches this differently: it encodes design patterns as markdown files that live in your project, treating software hygiene as a distribution problem rather than a prompting problem.
Technical Insight
Paperthin's core abstraction is the skill file—a markdown document with YAML frontmatter that any filesystem-aware LLM can read and execute. Here's what a simplified skill looks like:
---
name: re0
invocation: model
mode: write
scope: artifact
---
# re0: Rewrite From Zero
When refactoring a file, module, or component:
1. Create a timestamped folder: `re0-work-{ISO8601}/`
2. Move current implementation to `re0-work-{timestamp}/v0-original/`
3. Write EVIDENCE.md capturing:
- What worked in the original
- What failed and why
- Constraints that must be preserved
4. Rewrite from scratch in `re0-work-{timestamp}/v1-rewrite/`
5. Compare. If v1 is better, promote it. If not, try v2.
6. Delete the re0-work folder when done.
**Key principle:** Preserve lessons, discard implementation.
The frontmatter is the critical piece. invocation: model means the agent can apply this pattern autonomously when it detects refactoring opportunities. mode: write grants modification permissions. scope: artifact limits the blast radius to a single file or module. Contrast this with a read-only audit skill:
---
name: readchk
invocation: user
mode: read
scope: project
---
This skill can only analyze—the agent physically cannot apply fixes, which prevents the classic pitfall of auditing tools that 'helpfully' auto-correct their own findings and mask underlying issues.
Distribution happens via symlinks. Run npx paperthin install in your project, and it creates .paperthin/skills/ populated with symlinks to globally installed skill files. Your agent's context window now includes these patterns. When Claude reads your project structure, it sees SKILL-re0.md and SKILL-debloat.md alongside your source code. The skills become part of the project's ontology.
The taxonomy that makes this work breaks maintenance into four dimensions. Depth skills (re0, debloat, dedash) operate on single artifacts, driving toward minimal viable implementation. Breadth skills (ssotize) enforce consistency across artifacts—they detect when the same concept is documented in three different READMEs and force consolidation. Coil skills (re0-loop, re0-memo) handle temporal accumulation, treating each iteration as a learning cycle that preserves insights while discarding cruft. Mesh skills (prism, factchk) run multi-perspective verification, checking claims from both 'assume this is wrong' and 'assume this is right' directions to catch hallucinations.
The most radical pattern is re0-loop, which structures agent work as explicit rewrite cycles:
# Cycle Structure
## Phase 1: Evidence Gathering
- Create `re0-work-{timestamp}/EVIDENCE.md`
- Document: current approach, failure modes, constraints
- No implementation yet
## Phase 2: Rewrite
- Build v1 in isolated folder
- Compare against evidence
- If failed, document why and try v2
## Phase 3: Promotion
- Move successful version to main codebase
- Archive evidence
- Delete re0-work folder
This inverts normal LLM behavior. Instead of 'read file, make edits, save file,' it's 'read file, throw it away, write new file from lessons learned.' The timestamped folder structure prevents the agent from falling back to incremental patching—there's no original file to edit, only a clean slate and a list of constraints.
The autobahn pattern deserves special attention because it documents something most teams handle with whispered Slack messages. When you need an agent to work on code that trips content filters (security tools, crypto libraries, anything involving user data), autobahn creates an explicit exclusion zone:
1. Identify scope that triggers guardrails
2. Move it to AUTOBAHN-EXCLUDED.md
3. Run agent on remaining code at full strength
4. Manually handle excluded scope
5. Log what was excluded and why
This makes the safety/capability trade-off visible in version control instead of hidden in prompt engineering. Your team can review what's being excluded and decide if it's appropriate.
What makes these skills portable is that they have no runtime dependencies. An agent doesn't 'call' re0 like a function—it reads the markdown, understands the pattern, and applies it. This works because frontier LLMs have gotten good enough at instruction-following that a well-structured markdown document is sufficient to encode behavior. The skill file is simultaneously human documentation and machine-executable specification.
Gotcha
The entire system depends on your agent actually reading and following the skill files, which is nowhere near 100% reliable. In testing with Claude 3.5 Sonnet, skills with invocation: model get applied maybe 60-70% of the time when the situation calls for them. The agent needs to: notice the skill file exists, read it in context, recognize the current task matches the skill's domain, and choose to follow it instead of its base instincts. That's a lot of conditions. If you're using a less capable model, or working in a large project where the skill files get pushed out of context, effectiveness drops hard.
The symlink-based installation breaks in predictable ways. Windows requires elevated privileges for symlinks by default. Corporate laptops with restrictive security policies block them entirely. The --user flag for global npm installs creates symlinks in user directories that some agents can't reach. There's no graceful degradation—if symlinks fail, you get nothing, and troubleshooting involves checking OS permissions and shell environments. The workaround is manually copying skill files into .paperthin/skills/, which defeats the auto-update mechanism when skill definitions improve upstream. For a tool focused on hygiene and clean patterns, the distribution layer is surprisingly messy.
Verdict
Use if: You're already doing serious work with filesystem-aware coding assistants (Claude, Cursor, Continue) and have noticed your codebase accumulating agent-generated bloat. You want portable, version-controlled design patterns that work across different LLM tools without rewriting them as vendor-specific configs. You're comfortable with the fact that skills are suggestions, not guarantees, and you'll review agent output anyway. You maintain open-source projects where consistent documentation structure is worth encoding as executable patterns. Skip if: You're building deterministic agent systems that need reliable tool-calling APIs—markdown suggestions won't cut it. You work in environments where symlinks are blocked or you need everything to 'just work' without OS-level permission debugging. Your team hasn't yet standardized on which coding assistants to use, because explaining 'these markdown files teach the AI good habits' is a harder sell than 'install this linter.' You expect framework-level features like composition, telemetry, or guaranteed execution order.