flooooooooooowflooooooooooow/flow-skills/skills/flow-compiler-dev/SKILL.md

flow-compiler-dev

Skill1 starsChanged 3 months agoMITView on GitHub

Change the Flow compiler, runtime, or standard library. Use for adding a language feature, fixing a compiler defect, touching code generation, working on the self-hosted Stage-A compiler, adding a backend, or any change inside the Flow repository itself.

In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- flow-audioSkill
- flow-autodiffSkill
- flow-basicsSkill
- flow-debugSkill
- flow-dynamicsSkill
- flow-effectsSkill
- flow-graphicsSkill
- flow-perfSkill
- flow-setupSkill
- flow-stdlibSkill
- flow-verifySkill
- flow-wasmSkill

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific
could be automatic: a setting could enforce it

Distinctive:
Never hand-edit generated C.
line 63
Distinctive:
Check parity with a differential test: same program, two backends, same output.
line 91
Distinctive:
Add it as a failing test before touching the fix.
line 96
Distinctive:
Run the focused test, then the suite it belongs to.
line 99
Very specific:
Keep the change to the goal.
line 104

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Working on Flow itself

Where things live

Path	Holds
`flow`	The command driver, a shell script
`compiler/src/`	Self-hosted Stage-A compiler, written in Flow
`compiler/bootstrap/`	Checked-in C bootstrap, generated
`compiler/host/`, `compiler/fixtures/`	Host glue and test fixtures
`src/flow/`	Full Python compiler and tooling
`runtime/`	Native runtime: graphics, audio, recorder, WASM shims
`lib/stdlib/`	Standard library
`tests/unit/`	Python-level compiler tests
`tests/runtime/`	Compile-and-run Flow tests
`tests/lang/`	Language surface tests
`tests/integration/`	Cross-component checks
`docs/project/self-hosting.md`	The self-hosting contract
`docs/project/architecture-writeup.md`	How the compiler is put together

Key files in compiler/src/: parser.flow, resolve.flow, cgen.flow, ast.flow, driver.flow, dynamics_dsl.flow, fir_analysis.flow, fir_opts.flow, jsgen.flow, fmt.flow.

Read the contract first

cat docs/project/self-hosting.md
cat docs/project/architecture-writeup.md
cat docs/project/pattern-adoption.md
cat compiler/README.md
cat CONTRIBUTING.md

Two compilers must agree on what the language means. A change in one that is not mirrored in the other splits the language quietly.

Implement features as vertical slices

Take one construct all the way through rather than building a layer at a time:

Grammar and parse.
AST node.
Resolution and type check.
Lowering to C, and any other backend that claims the feature.
A runtime test that executes it and asserts a result.
A focused document, or an edit to the existing one.

A parsed construct that nothing lowers is a trap. If you ship one, mark it clearly as parsed only.

Bootstrap discipline

compiler/bootstrap/ holds checked-in generated C. When Stage-A source changes in a way that affects it, regenerate and commit the result in the same change. A stale bootstrap produces failures that look like unrelated compiler bugs.

Never hand-edit generated C. Fix the generator.

The loop

# after changing compiler/src/
flow test --strict --verbose
flow test-lang
flow test-runtime
flow test-python
flow test-all          # before proposing the change

Inspect what your change generated:

FLOW_HOST=python flow compile tests/lang/some_case.flow
cat build/some_case.c
FLOW_HOST=python flow explain tests/lang/some_case.flow

Backends

docs/ covers C, MLIR, WASM, Metal, WGSL, and SPIR-V paths. Adding a backend does not get to change what a program means. If a backend cannot express a construct, fail clearly rather than approximating it silently, and record the gap.

Check parity with a differential test: same program, two backends, same output.

Fixing a defect

Reproduce with the smallest possible file.
Add it as a failing test before touching the fix.
Find the earliest wrong stage. See the flow-debug skill.
Fix at that stage.
Run the focused test, then the suite it belongs to.
Report the reproduction, the cause, the fix, and the passing command.

Scope

Keep the change to the goal. Unrelated cleanup swept into a focused patch makes review harder and hides the real change. If you find something else worth fixing, note it in docs/project/Questions.md and move on.

Design decisions belong to the human. When a choice affects language meaning, write the options and a recommendation into docs/project/Questions.md and wait for an answer rather than picking one.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free