Configuration files
Markdown + YAML frontmatter format, auto-discovery, project-vs-user precedence.
Canonical contract:
packages/sdk/docs.md— "Configuration files (v1.5+)" + ADR D74-D78, D150-D158.
The SDK reads several config files from .theokit/ (project) and ~/.theokit/ (user). The format is Markdown + YAML frontmatter — same shape as SKILL.md / Claude Code (ADR D74).
File formats
Agents (.theokit/agents/<name>.md)
---
name: weather-bot
model:
id: openai/gpt-4o-mini
tools:
- get_weather
---
You are a concise weather assistant. Use the get_weather tool when relevant.The body is the system prompt; the frontmatter is options.
Skills (.theokit/skills/<name>.md)
---
name: morning-routine
description: Generate the morning briefing.
---
1. Check calendar for today.
2. Summarize unread emails.
3. Post to Slack #team.Personalities (.theokit/personalities/<name>.md)
---
name: coder
description: Terse, code-first persona.
tools:
- shell
- read_file
---
You answer in code, with minimal prose. Always show working snippets.ADR D161 enforces lowercase-only slug + Zod-validated frontmatter.
One file = one entity (ADR D75)
The SDK does NOT support multi-entity files (no agents.json with N agents inside). Each agent / skill / personality is its own .md. To disable, rename to <name>.md.disabled.
Validation
Every frontmatter is Zod-validated on load (ADR D76, D10). Invalid files emit a typed ConfigurationError — they don't break other files.
Backward compat
The legacy JSON format (.theokit/agents.json etc.) still works but emits a deprecation warning. Sunset planned for v2.0 / Q2 2027 (ADR D77). Use the migration CLI:
pnpm exec theokit-migrate-configPerforms atomic write + timestamped backup (ADR D78).
Auto-discovery (context files)
Beyond explicit config, the SDK auto-discovers context files via walk-up-to-git-root (ADR D151) — no import needed:
| File | Source |
|---|---|
.theokit/THEO.md | Project-specific |
CLAUDE.md | Claude Code standard |
AGENTS.md | Multi-tool standard |
GEMINI.md | Gemini Code Assist |
.cursor/rules/*.mdc | Cursor IDE |
Merge is concat-by-priority (ADR D152) — not first-match-wins. All files contribute, ordered by priority.
@import syntax (ADR D156)
CLAUDE.md and GEMINI.md support @path/to/include.md — the SDK resolves with 5-hop limit + per-import size cap.
Size caps (ADR D155)
Per-file 40k, aggregate 120k. Over-limit → tie-break truncation, telemetry counter incremented (ADR D159).
API reference
The configuration system is mostly transparent — you don't import a "config loader". The SDK reads files on Agent.create / Skill.list / Personality.list.