CodeLoop

9 agent skills for software engineering. Plain markdown — works with any model, any harness that supports the Agent Skills standard. Designed to be forked and adapted.

Skills

Skill	What it's for	What comes out
clarify	Nail down requirements one question at a time	Q&A log, user stories, glossary, decisions, research notes
overview	Understand how code fits into the system	Inline explanation with context
structure	Find shallow modules, propose deepening refactors	Candidate list ranked by strength
proto	Test a design choice by building the minimum throwaway	A finding — the code is discarded
spec	Write up what was discussed as an actionable spec	records/specs/<YYYY-MM-DD>-<slug>.md with Q-refs
slice	Break a spec into serial-numbered tasks with dependency descriptions	records/tasks/<YYYY-MM-DD>-<spec-slug>-<task-slug>.md
tdd	Build or fix something test-first, one slice at a time	Passing tests and working code
diagnose	Find the root cause of a bug or regression, report it	Diagnosis pointing to the relevant code
handoff	Compact the session so another agent can continue	records/handoffs/<YYYY-MM-DD>-<slug>.md

Skill relationships

Each skill is an entry point — pick the one that matches your situation. Skills that need prerequisites will tell you.

START ─── What's the situation?
  │
  ├─ "I don't know what I want yet"
  │   └─→ clarify
  │
  ├─ "I want to understand existing code"
  │   └─→ overview → (or structure)
  │
  ├─ "The codebase hurts and I want to refactor"
  │   └─→ structure → (or proto) → spec → slice → tdd
  │
  ├─ "Something's broken"
  │   └─→ diagnose → tdd (or structure if the fix is architectural)
  │
  ├─ "I need to decide between two approaches"
  │   └─→ proto
  │
  ├─ "Requirements are clear, time to plan"
  │   └─→ spec → slice → tdd
  │
  └─ "I need to switch sessions or hand off"
      └─→ handoff

Several skills have built-in guardrails that redirect you if you're not ready:

• spec → run clarify first if requirements are unclear
• slice → run clarify first if the spec is unclear
• tdd → run diagnose first if the bug isn't root-caused
• proto → run clarify first if there's no clear question
• structure → starts with a clarify phase of its own
• overview → suggests structure if it finds shallow modules or untestable interfaces
• diagnose → suggests structure or tdd as follow-ups depending on whether the fix is architectural

Records

Skills read and write to a shallow records/ directory at the repo root, created lazily on first use:

records/
├── glossary.md
├── decisions/
│   └── 2026-05-29-totp-over-sms.md
├── questions/
│   └── 2026-05-29-two-factor-auth.md
├── research/
│   └── 2026-05-29-totp-library-comparison.md
├── specs/
│   └── 2026-05-29-two-factor-auth.md
├── tasks/
│   └── 2026-05-29-two-factor-auth-totp-setup.md
└── handoffs/
    └── 2026-05-29-two-factor-auth.md

Use one directory per record type, with no deeper nesting:

• records/glossary.md
• records/decisions/<YYYY-MM-DD>-<slug>.md
• records/questions/<YYYY-MM-DD>-<slug>.md
• records/research/<YYYY-MM-DD>-<slug>.md
• records/specs/<YYYY-MM-DD>-<slug>.md
• records/tasks/<YYYY-MM-DD>-<spec-slug>-<task-slug>.md
• records/handoffs/<YYYY-MM-DD>-<slug>.md

Specs and task files have a **Status** field: active, done, or dropped. Update it as you go. Glossary, decision, question, research, and handoff records do not use lifecycle status.

Record flow

Records are how skills pass context to each other without requiring a long conversation:

• clarify writes glossary.md, decisions/*.md, questions/*.md, and optionally research/*.md → spec reads them to write the spec
• spec writes specs/<YYYY-MM-DD>-<slug>.md → slice reads it to produce tasks
• slice writes tasks/<YYYY-MM-DD>-<spec-slug>-*.md with serial numbers (T1, T2…) and dependency descriptions → tdd picks up individual tasks
• structure reads glossary.md and decisions/*.md → may write new entries → spec picks them up
• overview reads glossary.md and decisions/*.md for vocabulary and rationale
• handoff reads all of the above and writes a pointer document

Skills don't need a long conversation thread. When you chain them together, the records give continuity without repeating yourself.

Acknowledgments

Adapted from Matt Pocock's skills library.