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 |