For agents

Give your agent the map
before it touches the code.

The .skill command turns a Preflight flow query into a SKILL.md briefing file. Claude Code loads it automatically — so your agent starts with compiler-accurate context instead of guessing.

The workflow

Preflight sits between you and the agent. Query first, brief second, prompt third.

  1. 1
    Scan your codebase Run Preflight against your source tree. It builds a compiler-accurate flow graph in seconds — no config, no annotations.
  2. 2
    Ask what you're planning to change Query the REPL in plain English. "What touches LoginResponse.token?" — Preflight shows every node: reads, writes, props, effects, sinks.
  3. 3
    Generate a skill file Run .skill LoginResponse.token refactor. Preflight writes a SKILL.md to .claude/skills/ with the full blast radius, hard constraints, and coordinated-change warnings.
  4. 4
    Direct your agent Claude Code reads the description field in the skill's frontmatter and loads it automatically when your task matches. The agent knows what it's touching before it writes a line.

The command

Inside the Preflight REPL:

preflight › .skill <Type.field> <intent>

# Examples
preflight › .skill LoginResponse.token refactor
preflight › .skill User.email remove
preflight › .skill Order.total test
preflight › .skill Payment.status review

The file is written to .claude/skills/<intent>-<type-field>/SKILL.md. The directory structure is what Claude Code expects — each skill lives in its own named folder.

Use .index to see all tracked fields before generating a skill.

The four intents

refactor

Blast radius table with every compiler-verified reference. Coordinated-change warnings for storage keys, HTTP headers, and Redux actions.

  • Every location that reads or propagates the field
  • Hard constraints: what must change atomically
  • Storage key migration warnings
  • API contract warnings if the field hits a header
remove

Ordered deletion guide — sinks first, source last. The safest sequence to remove a field without leaving orphaned reads or dead branches.

  • Deletion order: deepest propagation first
  • Migration checklist with checkboxes
  • Dead code branches flagged explicitly
  • String-literal key blind spots noted
test

Test scenarios grouped by flow kind: access, storage persistence, HTTP transmission, UI rendering, state management, effect dependencies.

  • One scenario block per distinct kind found
  • Null / missing value cases included
  • Effect dep stale-closure cases flagged
  • Dynamic-key blind spots noted
review

Per-location review checklist for a PR touching this field. Security section if the field reaches a header, storage, or env var.

  • One checkbox per location in the blast radius
  • Kind-specific review notes on each line
  • XSS / HTTPS exposure checks
  • Dead-code annotations if field is removed

What the skill file looks like

Every generated SKILL.md has a YAML frontmatter block that Claude Code reads, followed by the briefing content.

.claude/skills/refactor-loginresponse-token/SKILL.md 
---
name: refactor-loginresponse-token
description: Blast radius and constraints for refactoring
             LoginResponse.token — 5 nodes across 3 files
---

# Refactor `LoginResponse.token`

> Generated by Preflight · 2025-03-03 · 5 nodes across 3 files

## Blast radius

Every compiler-verified location that reads or propagates `LoginResponse.token`:

| Location | Kind | Code |
|----------|------|------|
| `src/api/auth.ts:41` | direct access | `const { token } = await login(creds)` |
| `src/store/auth.ts:18` | storage write | `localStorage.setItem('auth_token', token)` |
| `src/http/client.ts:23` | HTTP header | `config.headers.Authorization = \`Bearer \${...}\`` |
| `src/hooks/useAuth.ts:55` | fn return value | `return { token, user }` |
| `src/components/Avatar.tsx:67` | JSX prop | `<Avatar token={token} />` |

## Coordinated changes required

**Storage write** (`auth_token`) — `src/store/auth.ts:18`
Rename the storage key in sync, or existing sessions will read stale data.

**HTTP header** (`Authorization`) — `src/http/client.ts:23`
Coordinate the field shape change with the API contract before deploying.

## Hard constraints

- Update **all 5** locations in the blast radius atomically.
- Clear or migrate stored values — existing sessions hold the old key.
- Verify the API contract accepts the new field shape before deploying.

How Claude Code picks it up

Claude Code loads skills automatically when the description field in the frontmatter matches the current task context. You don't need to invoke it manually.

When you open a task like "refactor the auth token field", Claude Code reads the description of every skill in .claude/skills/ and loads the ones that match. The agent receives the blast radius, constraints, and coordinated-change warnings before writing a single line.

You can also invoke any skill explicitly by name:

# Manual invocation in Claude Code
/refactor-loginresponse-token

Skills persist across sessions. Regenerate after running .scan if the codebase has changed — the blast radius will be updated to reflect any new references.

Regenerating after changes

Preflight's flow graph reflects the state of your codebase at scan time. If you've made changes since the last scan, run .scan in the REPL before generating a new skill — otherwise the blast radius may be stale.

preflight › .scan
✓  541 files  ·  392 types  ·  7820 nodes  ·  7.7s

preflight › .skill LoginResponse.token refactor
✓  Skill written to
     .claude/skills/refactor-loginresponse-token/SKILL.md
     5 nodes  ·  3 files  ·  refactor