Using Forge Skills

---
name: using-forge-skills
description: Use when starting a session, when you need to discover which forge skill applies to the current task, when uncertain which skill to invoke for a request, or when a session begins and the pipeline should be loaded.
---

# Using Forge Skills

## Overview

Forge Skills is a planning-first engineering skill library. Skills encode structured workflows — not reference docs. This meta-skill maps your task to the right skill and explains the full .forge/ handoff chain.

## Skill Discovery

```
Task arrives
    │
    ├── Raw idea, not yet pressure-tested? ────────→ idea-griller
    ├── Ready to write a spec/PRD? ────────────────→ spec-driven-development
    ├── Have prd.md, need architecture? ───────────→ architecture-and-contracts
    ├── Establishing brand foundations / voice? ───→ brand-and-identity
    ├── Design REST endpoints / API contracts? ────→ api-design
    ├── Schema / migrations / query design? ───────→ database-design
    ├── Establish design tokens / component lib? ──→ design-system
    ├── Modal vs sheet / expand vs nav decisions? ─→ interaction-patterns
    ├── Catalog components before a UI sprint? ────→ component-library
    ├── Define page templates + responsive plan? ──→ page-composition
    ├── Charts / dashboards / data displays? ──────→ data-visualization
    ├── Research competitors / positioning? ───────→ competitive-analysis
    ├── Will this scale / capacity planning? ──────→ scalability-analysis
    ├── Security / compliance / PII / SOC 2? ──────→ security-and-compliance
    ├── Go-to-market / how to sell this? ──────────→ gtm-strategy
    ├── Validate decisions / get external input? ──→ cross-validation
    ├── Have architecture, need tasks? ────────────→ planning-and-task-breakdown
    ├── 3+ independent tasks, run in parallel? ────→ parallel-execution-strategy
    ├── Need realistic demo / test data? ──────────→ seed-data-and-fixtures
    ├── Define test pyramid / coverage targets? ───→ testing-strategy
    ├── Have tasks.yaml, implementing? ────────────→ incremental-implementation
    │     └── Need test-first discipline? ──────────→ tdd
    ├── Error handling / retries / resilience? ────→ error-handling-and-resilience
    ├── Logging / monitoring / alerts? ────────────→ observability
    ├── Latency / cost / LLM budgets? ─────────────→ performance-and-cost-optimization
    ├── Outage / postmortem / runbook? ────────────→ incident-response-and-postmortems
    ├── Something broke or behaves wrong? ─────────→ debugging-and-recovery
    ├── Bug triage → GitHub issue + fix plan? ─────→ triage-issue
    ├── Code ready for review? ────────────────────→ code-review-and-quality
    ├── Tech debt / refactor / rewrite plan? ──────→ refactoring-and-tech-debt
    ├── WCAG / a11y / keyboard / screen reader? ───→ accessibility
    ├── UI quality pass before demo/ship? ─────────→ visual-polish
    ├── Doc rot / README / changelog discipline? ──→ documentation-hygiene
    ├── Sales / investor demo script? ─────────────→ demo-narrative
    ├── Committing / branching? ───────────────────→ git-workflow
    ├── Deploying or launching? ───────────────────→ shipping-and-launch
    ├── Redact / prepare for external sharing? ────→ redaction-and-cleanup
    ├── Creating or editing a forge-skill? ────────→ writing-skills
    ├── Upstream artifact changed — what's stale? ─→ forge-sync
    └── Stress-testing a design? ──────────────────→ (relentless questioning — ask one branch per turn)
```

## The Forge Pipeline

```
/grill → /spec → /architect → /plan → /build → /review → /ship
```

Each stage consumes the previous stage's artifact. Join mid-pipeline if the artifact already exists. The full `.forge/` artifact chain is in `AGENTS.md` (20+ artifacts; the design phase fans out across architecture, api-design, database-design, and the UI chain brand-and-identity → design-system → component-library → page-composition + data-visualization + interaction-patterns).

The **UI skill chain** runs in order: `brand-and-identity → design-system → component-library → page-composition → data-visualization`. `visual-polish` runs after `/build`, before `/ship`.

## Agent Team

Thirteen specialist personas available via the Task tool or dispatch:

| Agent | File | When to invoke |
|-------|------|----------------|
| **Architect** | `agents/architect.md` | Designing system structure, evaluating tech decisions |
| **Platform Architect** | `agents/platform-architect.md` | Multi-product boundaries, shared vs forked decisions, deploy topology |
| **Project Manager** | `agents/project-manager.md` | Task breakdown, dependency ordering, scope management |
| **Test Engineer** | `agents/test-engineer.md` | TDD coaching, test quality review |
| **Code Reviewer** | `agents/code-reviewer.md` | PR review, contract validation, quality gates |
| **Security Auditor** | `agents/security-auditor.md` | Threat modeling, input validation, hardening |
| **Competitive Analyst** | `agents/competitive-analyst.md` | Competitor research, positioning |
| **Compliance Officer** | `agents/compliance-officer.md` | Regulatory, privacy, certifications |
| **Reliability Engineer** | `agents/reliability-engineer.md` | Errors, observability, incidents, performance |
| **Data Engineer** | `agents/data-engineer.md` | Schema, migrations, query performance |
| **QA Engineer** | `agents/qa-engineer.md` | Test strategy, quality gates |
| **Design Engineer** | `agents/design-engineer.md` | Visual system, interaction, accessibility |
| **Brand Strategist** | `agents/brand-strategist.md` | Brand identity, voice and tone, cross-product consistency |

## Core Operating Behaviors

Apply at all times, across all skills. Behaviors 1, 4, 5, and 6 are grounded in Andrej Karpathy's principles for LLM coding and his Agentic Engineering concept (Feb 2026).

### 1. Surface Assumptions *(Karpathy: Think Before Coding)*

Before implementing anything non-trivial:

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

### 2. Manage Confusion Actively

When you encounter inconsistencies: STOP. Name the confusion. Present the tradeoff. Wait for resolution. Never silently pick one interpretation.

### 3. Push Back When Warranted

You are not a yes-machine. Name issues directly, explain concrete downside, propose an alternative, accept the human's decision if they override with full information.

### 4. Enforce Simplicity *(Karpathy: Simplicity First)*

Before finishing: Can this be done in fewer lines? Are these abstractions earning their complexity? Would a staff engineer say "why didn't you just..."?

### 5. Maintain Scope Discipline *(Karpathy: Surgical Changes)*

Touch only what you're asked to touch. Do NOT refactor adjacent code, add unasked features, delete code without approval, or remove comments you don't understand.

### 6. Verify, Don't Assume *(Karpathy: Goal-Driven Execution)*

Every skill includes a verification checklist. A task is not complete until verification passes. "It looks right" is not verification.

Full lifecycle (define → ship → operate → polish → share) and the complete `.forge/` artifact chain are documented in `AGENTS.md`. Read it for cross-phase decisions.

## Anti-Rationalization

| Thought | Why it's wrong |
|---------|----------------|
| "This is too simple for a skill" | Simple tasks are where unchecked assumptions cause the most waste |
| "I'll gather context first, then check skills" | Skills tell you HOW to gather context — check first |
| "I remember this skill" | Skills evolve. Always read the current version. |
| "The brief/PRD is close enough" | Missing artifacts break the handoff chain downstream |
| "I can skip architecture for a small feature" | Contracts protect parallel workers — skip them and work diverges |
| "Tests can come after the implementation" | Then they test implementation, not behavior |
| "I'll clean up the adjacent code while I'm here" | Scope creep disguised as helpfulness |

## Red Flags

- Starting implementation without a `.forge/prd.md`
- Writing tests after all implementation code is done
- Module list names files instead of behaviors
- Contracts written at function-level instead of module-boundary level
- Tasks in `.forge/tasks.yaml` that touch more than 2-3 modules
- PR that touches files not listed in the task's file list
- "Out of Scope" section in the PRD is empty

## Skill Rules

1. Check for an applicable skill before starting work — even a 1% chance.
2. Skills are workflows, not suggestions. Follow steps in order.
3. Multiple skills can apply — use the lifecycle sequence to choose order.
4. When in doubt, start with a spec.