Skills System

Skills are self-contained context modules that provide deep domain knowledge, step-by-step workflows, and guardrails for specific tasks. They are the second tier of the progressive disclosure model — loaded on demand when you invoke /skill-name in Claude Code.

What Skills Solve

The root CLAUDE.md file cannot contain everything. Billing alone has pricing models, subscription lifecycle, Stripe integration patterns, webhook handling, currency rules, and tax configuration. Loading all of that context for every task — including tasks that have nothing to do with billing — wastes the agent's context window and reduces response quality.

Skills solve this by encapsulating deep domain knowledge and loading it only when needed. Each skill provides three things:

1. Domain context — The mental model, architecture, and key files for a specific area
2. Step-by-step workflow — A checklist the agent follows to complete common tasks
3. Guardrails — Rules that prevent the most common mistakes in that domain

When you type /docs/billing in Claude Code, the agent loads the billing skill's context and operates with full knowledge of the billing architecture. When you type /new-feature, it loads the feature scaffolding workflow with checklists for both backend and frontend.

Where Skills Live

.claude/skills/                  # 14 project-level skills
├── api-contracts/SKILL.md
├── billing/SKILL.md
├── create-workplan/SKILL.md
├── debug/SKILL.md
├── domain-model/SKILL.md
├── implement-wu/SKILL.md
├── multi-tenancy/SKILL.md
├── new-api-endpoint/SKILL.md
├── new-feature/SKILL.md
├── new-migration/SKILL.md
├── refactor/SKILL.md
├── review-code/SKILL.md
├── troubleshooting/SKILL.md
└── write-tests/SKILL.md

backend/.claude/skills/          # 1 backend-specific skill
└── billing-engine/SKILL.md

Each skill is a directory containing a SKILL.md file. Project-level skills in .claude/skills/ are accessible from anywhere in the project. Stack-specific skills in backend/.claude/skills/ are loaded only when working in the backend directory.

Shipped Skills

SaaS4Builders ships 15 skills organized into four categories.

Development Workflows

Skills that guide the implementation of new code:

Domain Knowledge

Skills that provide deep context about specific areas of the codebase:

Quality and Debugging

Skills for maintaining code quality and diagnosing issues:

Project Management

Skills for planning and executing structured development:

Skill Anatomy

Every skill follows the same structure. Here is the anatomy of the /docs/billing skill — one of the most comprehensive skills in the project.

Frontmatter

The YAML frontmatter at the top of every SKILL.md file defines metadata:

---
name: billing
description: "Billing architecture: Stripe integration, subscriptions, invoices,
  webhooks, currency. Use when working on any billing feature, payment flow,
  or subscription logic."
---

The fields:

Some skills include additional metadata:

Skills with context: fork run as isolated sub-agents. This gives them their own context window and tool permissions, preventing accidental scope creep during complex workflows like /implement-wu.

Mental Model

The opening section establishes the domain context — the key invariants the agent must internalize before writing any code:

## Mental Model

- **V1 = `stripe_managed`**: Stripe is the invoicing authority for ALL pricing types
- Internal billing engine exists but runs as **shadow/validation only** — not authoritative
- The SaaS is the seller of record (Stripe is NOT a Merchant of Record)
- Subscription state changes happen ONLY via Stripe webhooks — never from internal logic
- All billing behavior is routed through Domain Contracts (PaymentGateway interface)

This section is the most important part of a skill. It establishes what is true, what is not, and what the boundaries are. An agent that internalizes these invariants will not generate code that violates them.

Critical Rules

Explicit guardrails stated as hard rules:

## Critical Rules — V1 Invariants

- NEVER generate authoritative invoices internally — Stripe generates all invoices in V1
- NEVER treat shadow calculations as the billing source of truth
- NEVER mutate subscription state without a webhook trigger
- NEVER call Stripe SDK directly from Actions — use Domain Contracts
- NEVER store money as floats — always `amount_cents` (int) + `currency` (string)
- NEVER allow FX conversion — one currency per invoice, immutable

These rules prevent the most frequent AI mistakes in the billing domain. Each rule exists because an AI agent (or a developer) made exactly this mistake at some point.

Workflow Steps

Skills like /new-feature and /implement-wu include step-by-step checklists. Here is the backend checklist from /new-feature:

## Backend Checklist

### 1. Database Layer
- [ ] Migration with `tenant_id` if scoped (see `/new-migration`)
- [ ] Model with `BelongsToTenant` trait (if scoped)
- [ ] Factory with realistic data

### 2. Application Layer
- [ ] Action in `Application/<Domain>/Actions/` — wraps in `DB::transaction()`
- [ ] Query in `Application/<Domain>/Queries/` — read-only, Spatie QueryBuilder
- [ ] Input DTO in `Application/<Domain>/DTO/` — `readonly class`

### 3. HTTP Layer
- [ ] FormRequest with `authorize()`, `rules()`, `toDto()`
- [ ] Resource — snake_case keys, money as `amount_cents` + `currency`
- [ ] Controller — thin, delegates to Actions/Queries only

### 4. Routes & Tests
- [ ] Route in `routes/api.php` with correct middleware
- [ ] Feature tests: happy path, 401, 403, 404, 422, tenant isolation
- [ ] Unit tests for Actions/Queries
- [ ] Quality: `pint --dirty` + `phpstan analyse` + `test --filter=<Entity>`

The agent follows these steps sequentially, checking each item as it goes. The checklist ensures nothing is missed — especially tenant isolation tests, which are easy to forget.

Common Mistakes

Anti-patterns the agent must avoid. From the billing skill:

## Common Mistakes

- Generating internal invoices as if they were authoritative (V1 = shadow only)
- Calling `Stripe\*` classes directly from Actions instead of through
  `PaymentGateway` contract
- Hardcoding tax rates instead of using `TaxProviderInterface`
- Assuming `platform_managed` mode is active (it's planned post-V1, not wired yet)
- Modifying subscription currency after creation (immutable once set)

References

Pointers to internal convention files the skill depends on. The agent reads these automatically when it needs deeper context during implementation:

## References

- Billing architecture document — Source of truth for billing philosophy
- Subscription lifecycle document — State machine and transitions
- Currency rules document — Currency invariants and formatting
- Webhook patterns document — Webhook handling and idempotency
- Tax integration document — Stripe Tax configuration

Each reference points to a file in the repository's docs/ directory. When the agent encounters a billing task, it loads these automatically to get the full domain context beyond what the skill's Mental Model section provides.

How Skills Work in Practice

Basic Invocation

When you type /docs/billing in Claude Code, the agent loads the skill's context and responds with the key invariants:

You: /docs/billing

Claude Code loads .claude/skills/docs/billing/SKILL.md and responds:

"I've loaded the billing skill context. Key invariants:
 - V1 = stripe_managed mode (Stripe is invoicing authority)
 - All billing goes through Domain Contracts (PaymentGateway interface)
 - Subscription state changes only via webhooks

 What would you like to work on?"

Invocation with Arguments

Some skills accept arguments. The /implement-wu skill takes a milestone and Work Unit ID:

You: /implement-wu M6 WU-B03

Claude Code:
1. Reads the M6 workplan to find WU-B03's specification
2. Reads the tracking file to check WU-B03's status and dependencies
3. Verifies all prerequisite WUs are completed
4. Presents a plan with files to create, patterns to follow, and tests to write
5. Waits for your approval before writing any code

The agent does not start coding until you approve the plan. This is enforced by the skill's workflow — Phase 2 explicitly requires user validation before proceeding to Phase 3.

Combining Skills

You can invoke multiple skills in a session. For example:

1. /docs/billing — Load the billing domain context
2. Ask the agent to create a new webhook handler
3. /write-tests — Load test patterns to write thorough tests for the handler

The agent accumulates context across skill invocations, building a comprehensive understanding of the task.

Creating a Custom Skill

When you add a new domain to the boilerplate, create a skill so AI agents can work effectively in that domain.

Step 1 — Create the Directory

mkdir -p .claude/skills/your-skill-name
touch .claude/skills/your-skill-name/SKILL.md

Step 2 — Write the Frontmatter

---
name: your-skill-name
description: "What this skill does. Include keywords for discovery."
argument-hint: "[optional-argument]"
context: fork
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
---

Set context: fork for skills that execute multi-step workflows (like /implement-wu). Omit it for skills that only provide context (like /docs/billing).

Step 3 — Define the Content

Follow this template:

# Skill Title

## Mental Model
Key invariants and domain context. What is always true in this domain?
What assumptions can the agent make?

## Critical Rules
Hard rules stated as NEVER/MUST/ALWAYS. Each rule prevents a specific
class of mistake.

## Code Architecture
Where the relevant code lives. Directory structure, key classes,
data flow.

## Workflow
Step-by-step checklist for common tasks in this domain.
Use checkboxes for actionable steps.

## Common Mistakes
Anti-patterns to avoid. Each mistake should be one the agent (or a
developer) would plausibly make without the skill's guidance.

## References
Pointers to convention files and documentation the skill depends on.

Example — A Custom Analytics Skill

Here is a realistic skill for a hypothetical analytics domain you might add to the project:

---
name: analytics
description: "Analytics event tracking patterns and dashboard queries.
  Use when implementing tracking, event schemas, or dashboard features."
argument-hint: "[event-or-query]"
---

# Analytics System

## Mental Model

- Events are immutable append-only records — never update or delete
- Every event includes `tenant_id`, `user_id`, and `occurred_at`
- Event names use dot notation: `billing.subscription.created`
- Dashboard queries are pre-aggregated — never scan raw events at runtime

## Critical Rules

- NEVER track PII (emails, names, IP addresses) in event properties
- NEVER query raw events for dashboard rendering — use materialized aggregates
- NEVER create events without a corresponding schema in `Domain/Analytics/Schemas/`
- ALWAYS include `tenant_id` — events without tenant scope are rejected

## Code Architecture

- Event schemas: `app/Domain/Analytics/Schemas/`
- Event dispatch: `app/Application/Analytics/Actions/TrackEvent.php`
- Aggregation: `app/Application/Analytics/Queries/`
- Dashboard API: `app/Http/Controllers/Api/V1/Analytics/`

## Common Mistakes

- Tracking PII in event properties (GDPR violation)
- Querying raw events in dashboard endpoints (performance disaster)
- Forgetting tenant_id on events (breaks isolation)
- Using mutable event properties (events are append-only)

What's Next

• Workplan Execution — The structured execution pattern that /implement-wu and /create-workplan support
• CLAUDE.md Configuration — The base context system that skills extend
• AI-Assisted Development Overview — The three pillars of AI-first DX