Playbook

Typesafe markdown
for AI agents

Compile-time validated skills, agents, and docs for Claude Code. Catch broken imports, dead links, and stale examples before they reach your AI.

Get started

$ bun add -d @playfast/playbook
1Add "playbook": "./playbook" to package.json
2Create .skill.md files in the playbook directory
3Run bunx @playfast/playbook build
Scroll to explore

Features

{typescript}

Type-checked code blocks

Code examples in skills are executed at build time. If an import breaks or a type changes, the build fails — your AI never sees stale docs.

```{typescript}
import { pipe } from "effect"
// Runs at build. Fails if API changed.
```
repo://

Validated repo:// links

Link to source files with compile-time validation. Symbol references resolve to exact line numbers. Dead links fail the build.

See [config](repo://src/config.ts#DbPool)
// Resolved to line 42 at build time
{embed}

File embedding

Inline source code at build time. Symbol and line-range fragments supported.

{shell}

Shell execution

Run shell commands at build. Output is inlined. Non-zero exit fails the build.

errors

Rich diagnostics

Miette-style errors with source context, line numbers, and actionable suggestions.

skill

.skill.md

Reusable AI capabilities compiled to Claude Code slash commands. Frontmatter controls model, tools, and triggers.

---
name: deploy
description: "Deploy to prod"
claude:
  model: sonnet
  allowed-tools: Bash, Read
---
agent

.agent.md + .doc.md

Agent definitions with tool access and autonomous instructions. Docs are injected into context when relevant.

---
name: reviewer
description: "Code review agent"
claude:
  agent: true
---

Documentation

Playbook Config

// playbook.config.ts
import { defineConfig } from "@playfast/compiler-core"
import { repoResolver, typedCodeBlocks, embed } from "@playfast/compiler-plugins"
import { claudeTarget } from "@playfast/compiler-claude"

export default defineConfig({
  plugins: [
    repoResolver(),
    typedCodeBlocks(),
    embed(),
  ],
  generator: claudeTarget(),
})

Skill Frontmatter

Control how Claude Code uses each skill with typed frontmatter:

---
name: my-skill
description: "When to trigger this skill"
claude:
  model: sonnet              # model override
  allowed-tools: Read, Edit  # tool restrictions
---

repo:// Links

repo://src/config.ts — validated file link

repo://src/config.ts#DbPool — symbol reference, resolves to line number

repo://src/config.ts#L10-L25 — line range (emits unstable warning)

Serve & Portal

Run the local server to connect this portal to your project's skill graph:

bunx @playfast/playbook serve

The portal connects to localhost:4400 via Local Network Access. Pass ?port=XXXX in the URL to use a different port.

@playfast/playbook