For AI agents

This section is for agents (and for the people who configure them). Everything here is plain text an agent can fetch.

Fetch the language

What	URL	Format
Index of all pages (the llms.txt convention)	/llms.txt	text, links to each page as Markdown
The whole documentation in one file	/llms-full.txt	one Markdown file
Any single page as Markdown	/md/<page>.md, for example /md/language/needs.md	Markdown
Machine-readable language spec: keywords, operators, built-ins with the permission each needs, error codes with fixes, grammar	/spec.json	JSON (subtype-spec/1)
Compact reference, one screen per topic	/spec.md	Markdown
The same data from the compiler itself	sub spec --json, sub spec --markdown, sub spec --grammar	JSON / text

A good first request is /llms-full.txt: it fits in a model’s context and has every rule, every built-in and a gallery of 20 checked scripts.

When to use Subtype

Write a Subtype script instead of shell, Python or Node when a task:

• reads, writes or deletes files, runs programs, calls a network host or reads environment variables on a person’s machine, and
• a person will approve or review it (or a policy will).

The person approves one plain-words permission list instead of reading code. Subtype is a poor fit for long-running services or heavy computation.

The loop

1. Declare first. Begin the file with needs [ ... ] listing only what the script needs, as narrowly as possible (read [./src], not read [.]; run ["git status"], not run ["git"]).
2. Check. Run sub check file.sub. Every error names the call, the line and the exact change. Apply it or remove the call. Do not widen needs just to silence an error: ask whether the script really needs the permission.
3. Explain. Run sub explain file.sub and show the person the result, or read it yourself to confirm the script cannot do more than the task needs.
4. Run. sub run file.sub. The person sees the permission list and approves. --yes only when a person has already approved this exact list (the compiler can compare the manifest hash).
5. On exit code 3 or 4 (a permission was denied, or not approved): do not retry with broader permissions. Report what was denied and why the script needed it.

A prompt snippet

Put this in a system prompt, CLAUDE.md or AGENTS.md:

For scripts that touch files, run commands, use the network or read environment
variables, write Subtype (.sub) instead of shell, Python or Node.
Docs for agents: https://subtypelang.com/llms-full.txt  (spec: https://subtypelang.com/spec.json)
Workflow: write the file starting with a narrow `needs [ ... ]` header, run
`sub check`, fix every error with the fix the compiler suggests (never widen
`needs` just to silence an error), run `sub explain` and show the person the
result, then `sub run`. If a permission is denied, report it; do not retry broader.

Rules of the language an agent must not forget

• The file starts with needs [ ... ]. A missing key means none. net [] means no network.
• write does not include read. run has no shell: no |, ;, &, >, <, backticks or $(. Use a list of words or one run per program.
• Failure is a value: ? passes it up, or { } handles it. There are no exceptions.
• A Secret<T> (anything from env(...)) cannot reach print, log or a string. Compare with secret_eq.
• Errors are declared names (error Missing <: ConfigError), not Err(...).
• A function may declare a smaller needs than its caller holds, never a bigger one.

The Claude Code skill

A skill that tells Claude Code when to use Subtype and how, with verified examples, recipes for translating shell and Python, the compiler’s own reference and helper scripts.

• Download: /subtype-skill.zip
• Install: unzip into ~/.claude/skills/ (it makes ~/.claude/skills/subtype/). For one project only, use <project>/.claude/skills/.
• It contains SKILL.md (the rules and the loop), examples/ (scripts that pass sub check), references/ (a cheat sheet, recipes and the compiler’s spec), scripts/ensure-sub.sh (finds or builds sub), scripts/review.sh (check, explain and the permission hash to show a person), and an optional reminder hook.

The manifest

sub manifest file.sub prints the permission set and every call as JSON, with a SHA-256 of the permission set. Tools compare the hash with what a person already approved. sub manifest --centcom shapes it for Centcom’s approval prompt.

{ "format": "subtype-manifest/1", "needs": { "read": ["./src"], "write": ["./src"], "run": ["npm test"], "net": [] }, "hash": "sha256:..." }