Using Agent Skills

Agent Skills is a collection of engineering workflow skills organized by development phase. This meta-skill helps you discover and apply the right skill.

Skill Discovery

When a task arrives, identify the development phase and apply the corresponding skill:

Task arrives
    │
    ├── Don't know what you want yet? ──────→ interview-me
    ├── Have a rough concept, need variants? → idea-refine
    ├── New project/feature/change? ──→ spec-driven-development
    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
    ├── Implementing code? ────────────→ incremental-implementation
    │   ├── UI work? ─────────────────→ frontend-ui-engineering
    │   ├── API work? ────────────────→ api-and-interface-design
    │   ├── Need better context? ─────→ context-engineering
    │   ├── Need doc-verified code? ───→ source-driven-development
    │   └── Stakes high / unfamiliar? ──→ doubt-driven-development
    ├── Writing/running tests? ────────→ test-driven-development
    │   └── Browser-based? ───────────→ browser-testing-with-devtools
    ├── Something broke? ──────────────→ debugging-and-error-recovery
    ├── Reviewing code? ───────────────→ code-review-and-quality
    │   ├── Too complex? ─────────────→ code-simplification
    │   ├── Security concerns? ───────→ security-and-hardening
    │   └── Performance concerns? ────→ performance-optimization
    ├── Committing/branching? ─────────→ git-workflow-and-versioning
    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
    ├── Deprecating/migrating? ────────→ deprecation-and-migration
    ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
    ├── Adding logs/metrics/alerts? ───→ observability-and-instrumentation
    └── Deploying/launching? ─────────→ shipping-and-launch

Core Operating Behaviors

1. Surface Assumptions

Before implementing anything non-trivial, explicitly state your assumptions:

ASSUMPTIONS I'M MAKING:
1. [assumption about requirements]
2. [assumption about architecture]
3. [assumption about scope]
→ Correct me now or I'll proceed with these.

2. Manage Confusion Actively

When you encounter inconsistencies:

1. STOP. Do not proceed with a guess.
2. Name the specific confusion.
3. Present the tradeoff or ask the clarifying question.
4. Wait for resolution before continuing.

3. Push Back When Warranted

You are not a yes-machine. When an approach has clear problems:

• Point out the issue directly
• Explain the concrete downside
• Propose an alternative
• Accept the human's decision if they override

4. Enforce Simplicity

Before finishing any implementation, ask:

• Can this be done in fewer lines?
• Are these abstractions earning their complexity?
• Would a staff engineer look at this and say "why didn't you just..."?

5. Maintain Scope Discipline

Touch only what you're asked to touch. Do NOT:

• "Clean up" code orthogonal to the task
• Refactor adjacent systems as a side effect
• Add features not in the spec

6. Verify, Don't Assume

Every skill includes a verification step. A task is not complete until verification passes.

Lifecycle Sequence

For a complete feature:

1.  interview-me                → Extract what the user actually wants
2.  idea-refine                 → Refine vague ideas
3.  spec-driven-development     → Define what we're building
4.  planning-and-task-breakdown → Break into verifiable chunks
5.  context-engineering         → Load the right context
6.  source-driven-development   → Verify against official docs
7.  incremental-implementation  → Build slice by slice
8.  test-driven-development     → Prove each slice works
9.  code-review-and-quality     → Review before merge
10. code-simplification         → Reduce unnecessary complexity
11. git-workflow-and-versioning → Clean commit history
12. documentation-and-adrs      → Document decisions
13. deprecation-and-migration   → Retire old systems when needed
14. shipping-and-launch         → Deploy safely

Quick Reference

Phase	Skill	Summary
Define	interview-me	Surface what the user actually wants
Define	idea-refine	Refine ideas through divergent/convergent thinking
Define	spec-driven-development	Requirements before code
Plan	planning-and-task-breakdown	Decompose into verifiable tasks
Build	incremental-implementation	Thin vertical slices
Build	source-driven-development	Verify against official docs
Build	doubt-driven-development	Adversarial review of non-trivial decisions
Build	context-engineering	Right context at the right time
Build	frontend-ui-engineering	Production-quality UI
Build	api-and-interface-design	Stable interfaces with clear contracts
Verify	test-driven-development	Failing test first, then make it pass
Verify	browser-testing-with-devtools	Runtime verification
Verify	debugging-and-error-recovery	Reproduce → localize → fix → guard
Review	code-review-and-quality	Five-axis review
Review	code-simplification	Reduce complexity while preserving behavior
Review	security-and-hardening	OWASP prevention, least privilege
Review	performance-optimization	Measure first, optimize only what matters
Ship	git-workflow-and-versioning	Atomic commits, clean history
Ship	ci-cd-and-automation	Automated quality gates
Ship	deprecation-and-migration	Remove old systems safely
Ship	documentation-and-adrs	Document the why
Ship	observability-and-instrumentation	Logs, metrics, traces
Ship	shipping-and-launch	Pre-launch checklist, rollback