Skills, guidelines, rules, hooks, tools

Five kinds of record, each on its own, with its own id:

Kind	What it does
guideline	advice shown to an AI when a prompt or edit matches it
rule	a check on what lands (protected paths, a pattern, file size, secrets)
hook	runs before an AI's shell command, edit or tool call: allow, deny, ask, add context, or run a tool
tool	a command an AI can call, with typed inputs
skill	a named selection of any of the above

A record can be in many skills or none. Mix and match.

Where records live

Flag	Layer
(none)	the nearest `.dream/`
`-global`	`~/.dreams`, for every project
`-dir d`	`d/.dream/`, for that folder and below

The closer folder wins. Every add takes -skill s (also select it in skill s, made if missing). A value @file reads the file.

Built-in skills

dream skill list

ai-data-science	-	not installed	(dream skill add ai-data-science)
algorithms	-	not installed	(dream skill add algorithms)
angular	-	not installed	(dream skill add angular)
...
vue	-	not installed	(dream skill add vue)

The skills installed here, then the built-in ones not installed. Built in: ai-data-science, algorithms, angular, backend, c-cpp, cloud, databases, devops, dotnet, elixir, embedded-rust, flutter, git, go, kotlin, networking, php, python, react, react-native, ruby, rust, security, svelte, swift, testing, typescript, ux, vue.

dream skill add react

dream: skill react 2026-10-17: 470 of its 470 records added to /home/you/web (the rest were there)

react	2026-10-17	65 guidelines, 12 tools, 393 tests	/home/you/web	used by -

Installs a skill's records in this project; skill list then shows what it holds and where. -global installs it for every project. No network.

dream skill rm react

dream: skill react removed from /home/you/web with 470 records it installed

Removes the skill and the records nothing else uses.

dream init offers the skills that match the folder; dream init -skills react,ux picks them. A skill with tools may ask to run their setup (npm ci); say no and it prints the command.

Guideline

dream guideline add go-wrap-errors -statement "Wrap errors with context" \
  -fix 'return fmt.Errorf("load: %w", err)' \
  -good 'return fmt.Errorf("load: %w", err)' -bad 'return err' -scope '**/*.go'

dream: guideline go-wrap-errors stored without vectors, found by words only (no embedding helper running; `dream start` keeps the models loaded (`dream setup` downloads them first)); once one runs, dream guideline embed backfills them
dream: guideline go-wrap-errors added to /home/you/app

Without the helper a guideline matches by words only. Once it runs:

dream guideline embed

dream: 3 vectors added for 1 guidelines in /home/you/app

Adds the meaning vectors the guidelines lack.

Flag	Meaning
`-statement s`	required; the advice
`-fix f`	how to fix it
`-good code`, `-bad code`	examples; repeat for more
`-scope globs`	files it applies to
`-frameworks`, `-apis`, `-tags`	where else it matches
`-check-kind regex\|ast\|tool -check p`	a mechanical check
`-enforced-by ids`	rules or tools that enforce it
`-book b -section s -source path`	where it comes from
`-no-embed`	store without meaning vectors

Rule

dream rule add pattern -id no-python -paths '**/*.py' -reason "No Python in this repo"

dream: rule no-python added to /home/you/app

Kinds: protected_paths, pattern, max_file_bytes, secrets. Flags: -id, -paths, -pattern re, -limit n, -reason r, -fix f, -severity deny|warn.

Secret rules are built in; dream rule list shows them with yours:

builtin-secret-anthropic built-in  used by -  No Anthropic API key in source: anything committed is public
builtin-secret-aws   built-in  used by -  No AWS access key in source: anything committed is public
...
no-python            /home/you/app  used by -  No Python in this repo

Hook

dream hook add no-python-edit -on edit -paths '**/*.py' -deny "No Python in this repo" -enforces no-python

dream: hook no-python-edit added to /home/you/app

Flag	Meaning
`-on shell,edit,tool:<name>`	when it runs
`-command p,..`	shell commands it matches
`-paths g,..`	edited paths it matches
`-content re`	edited content it matches
`-deny r` / `-ask r` / `-context t`	refuse, ask the person, or add text
`-run argv` / `-runs tool ids`	run a command or tool records
`-enforces rule ids`	the rules it enforces
`-severity deny\|warn`	how hard

Try it:

dream hook check -edit web/b.py -content "print(1)"

deny
  deny hook no-python-edit (/home/you/app): No Python in this repo

dream hook check -shell "npm publish"

Prints allow, ask or deny and the record that decided.

Tool

dream tool add gofmt-check -description "List Go files gofmt would change" \
  -run 'gofmt -l {path}' -input 'path:string:required:file or folder' -effects read -timeout 30s

dream: tool gofmt-check added to /home/you/app

-input name:type[:required][:desc] repeats. {field} in -run is replaced by the input. -enforces ids -pattern <lint rule> ties a linter rule to guidelines.

dream tool run gofmt-check -in path=.

main.go

Runs it. AI tools see tool records through dream mcp.

Per folder

dream hook add web-ask-shell -on shell -command "npm publish" -ask "Publishing? Check the version first" -dir web

dream: hook web-ask-shell added to /home/you/app/web

Applies in web/ and below only.

cd web
dream hook off no-python-edit

dream: hook no-python-edit turned off in /home/you/app/web

dream hook list

web-ask-shell        /home/you/app/web  used by -  Publishing? Check the version first
no-python-edit       /home/you/app/web [off]  used by -

Turns a record from a farther layer off for this folder. Guidelines have no off; use rm.

Your own skill

dream skill new go-team -description "Our Go rules"
dream skill include go-team guideline/go-wrap-errors tool/gofmt-check hook/no-python-edit
dream skill exclude go-team hook/no-python-edit
dream skill show go-team

go-team	-
guideline/go-wrap-errors	Wrap errors with context
	fix: return fmt.Errorf("load: %w", err)
tool/gofmt-check	List Go files gofmt would change

Makes a skill; selects records (guideline, rule, hook, tool, test, skill); drops one; lists it. skill new also takes -version, -detect file[:json.key] (when init offers it) and -install dir:argv.

Test a skill

dream skill test add go-t1 -mode prompt -input "how should I return an error from load" -expect go-wrap-errors -skill go-team
dream skill test add go-t2 -mode edit -path a.go -input "func Load(id string, ctx context.Context) error" -expect go-ctx-first -heldout -skill go-team
dream skill test go-team

skill go-team: 1 tests, precision@3 1.00, recall@3 1.00
record       fired right wrong missed
go-wrap-errors     1     1     0      0

Scoring needs the helper (dream start); without it: no embedding helper running. A test is a prompt or an edit and the guidelines it should surface (-expect) or not (-reject). No -expect: nothing should surface. -heldout keeps it for dream skill test -heldout.

dream skill build -o go-team.db go-team
dream skill add -from go-team.db go-team

dream: skill go-team -: 3 records (1 guidelines), 0 tool files, no vectors, in go-team.db

Writes the skill and its records into one file; installs it elsewhere. Built while the helper runs, the file carries meaning vectors too.

List, show, remove

dream tool list

gofmt-check          /home/you/app  used by skill:go-team  List Go files gofmt would change

guideline|rule|hook|tool list shows one merged list over every layer that applies here: id, layer (a folder, global or built-in), who uses it, and what it says. show <id> prints one. rm <id> removes it.

Next: Members, plans, chat.