SLIM Documentation

Start Getting Started

SLIM is a plain-text format for AI prompts, agent configs, and tool schemas. It replaces Markdown in AI pipelines, stripping orchestrator metadata before the LLM call and saving an average of 24.5% of LLM-facing tokens on YAML agent configs (4.4% on plain prose). We're actively working to improve these numbers — contributions welcome.

Install SLIM

SLIM has official plugins for Claude Code, Google Antigravity, VS Code, IntelliJ, and Notepad++, plus a Python parser for scripting.

Quick install (Python)

pip install slim-parser

Write your first .slm file

@slim: 2.0
@model: claude-opus-4-7
@+agent: Greeter
@+name: Alice

~ This comment is stripped before the LLM call
# Role
You are $agent. Greet $name warmly.

# Instructions
- Be concise and friendly
- Respond in one sentence

Parse and use it

from slim_parser import SLIMParser

doc = SLIMParser().parse_file("hello.slm")

# Orchestrator reads metadata
model   = doc.headers["model"]       # "claude-opus-4-7"
agent   = doc.headers["agent"]       # "Greeter"

# Send only the LLM text (stripped)
llm_text = doc.stripped_text
# → "@+agent: Greeter\n@+name: Alice\n# Role\nYou are Greeter..."

# Call the LLM
response = client.messages.create(
    model=model,
    messages=[{"role": "user", "content": llm_text}]
)

Intro Overview

Every SLIM file is divided into two strictly ordered zones:

Named sections (::NAME type) are markers within the content zone — they provide typed, injection-safe regions without a separate block zone.

Files use the .slm extension with MIME type text/slim and UTF-8 encoding.

Syntax Header Zone

The header zone starts at line 1 and ends at the first # heading or non-blank, non-@ line.

@key: value          ~ orchestrator-only, stripped before LLM
@+key: value         ~ LLM-visible, also available as $key variable
@include: ./base.slm ~ import another .slm file

Strip semantics

Type coercion

Header values are automatically typed — no quotes required for most types.

@retry: 3            ~ → int
@threshold: 0.7      ~ → float
@async: true          ~ → bool
@context: null        ~ → None/null
@stack: python, js    ~ → list["python", "js"]
@id: "42"             ~ → str (quoted prevents int coercion)
@desc: First line
  second line           ~ → "First line second line" (continuation)

@include

Import another .slm file. Resolved before any other processing. Included @+ headers merge into the current LLM context; included @ headers are defaults the current file can override.

@include: ./base/agent.slm
@include: ./tools/mcp_tools.slm

• Max include depth: 5 levels
• Circular includes: parse error
• @+include is invalid — includes are always orchestrator-only

Multi-document files

Use --- on its own line to separate independent documents in one file. Each is parsed with its own header zone.

@slim: 2.0
@+agent: Planner
# Role
You plan tasks.
---
@slim: 2.0
@+agent: Executor
# Role
You execute tasks.

Syntax Body Zone

Everything after the header zone. This is the main content the LLM reads. Variables are interpolated before delivery.

Tables

Pipe-delimited rows. No |---| separator row — one of SLIM's token savings over Markdown.

| Format | Tokens | Readable |
| JSON   | 340    | Medium   |
| SLIM   | 175    | High     |

Syntax Sections

Named regions that can appear anywhere in the content zone. Sections use a no-close-tag design — content belongs to a section until the next section header. :: is a single BPE token, saving ~5 tokens per block vs the old === syntax.

::SECTION_NAME
content here

::SECTION_NAME type
typed content (verbatim for code types)

Nested sections (:::)

::OUTER
outer content

:::INNER_1
first nested content

:::INNER_2
second nested content

Rules

• Section names: [A-Za-z][A-Za-z0-9_]* — any case (e.g. CODE_1, UserInput)
• ::NAME requires a blank line before it (or file start) — prevents false triggers on CSS ::before, C++ ::, etc.
• :::NAME (nested) — no blank-line requirement; only valid inside a :: section
• Max nesting depth: 1 level (::::NAME is a parse error)
• Type tag determines content mode — code/data types = verbatim (no $var interpolation); no type or prose types = processed
• Escape :: at line start inside a section: prefix with \ → \:: becomes literal

Type tags

Example with nested sections

::EXAMPLES

:::EXAMPLE_1
user: Is this SQL safe?
assistant: No — SQL injection on line 2.

:::EXAMPLE_2
user: How do I fix it?
assistant: Use parameterized queries.

Syntax Directives

Lines beginning with > followed by a reserved ALL_CAPS keyword. Used to express agent workflow steps.

> CALL tool_name(param: value, param2: $var)
> ASSERT $result.status == complete
> YIELD $result.report
> EMIT event_name(payload: $data)
> LOG "Step completed"
> ABORT "Reason for stopping"
> WAIT 5s
> RETRY 3

Syntax Variables

$key references are resolved by the parser before the body text is sent to the LLM. Values come from @key or @+key headers.

@slim: 2.0
@+agent: SecurityBot
@+task: PR-942

You are $agent reviewing $task.
~ → "You are SecurityBot reviewing PR-942."

Syntax Schema Definitions

First-class syntax for AI function call schemas. Define tools the agent can call using the :tool_name prefix.

:tool_name
  desc: Human-readable description of what this tool does
  param1!: str           ~ required parameter
  param2?: int = 10      ~ optional with default
  param3?: [a|b|c] = a  ~ enum with default
  -> result: json        ~ return type

Property suffixes

Complete example

@slim: 2.0

:search_web
  desc: Search the internet for recent information
  query!: str
  max_results?: int = 10
  safe_search?: bool = true
  -> results: json

:run_code
  desc: Execute code in a sandboxed environment
  language!: [python|javascript|bash]
  code!: str
  timeout?: int = 30
  -> output: str
  -> exit_code: int

Custom type definitions

::TYPE_DEF
  Finding:
    line!: int
    severity!: [low|medium|high|critical]
    message!: str
    fix?: str

:analyze_code
  desc: Run static analysis on a code snippet
  code!: str
  language?: [python|js|java|go|rust] = python
  -> score: float, findings: list<Finding>

Reference Type System

Primitive types

First-class types (schema params)

Collection types

Syntax Comments

Lines starting with ~ (tilde) are stripped by all SLIM parsers. They never reach the LLM. Use them for author notes, TODOs, disabled content, or debugging hints.

~ Author: Jane Doe
~ TODO: add edge case for empty input
~ @+agent: DisabledAgent  ← never parsed, entire line stripped

Comments are valid anywhere in the file — header zone, body zone, inside blocks.

Security Security Model

Zone ordering enforcement

The header zone must precede the body zone. Any @key found after the first # heading or non-blank non-@ line is treated as literal body text, not a header. This prevents header injection — user content placed before headers cannot override @model, @include, or other orchestrator fields.

Section injection prevention

Parsers validate that embedded user content does not contain unescaped :: lines (preceded by a blank line). Use sanitize_user_content() to escape all control characters before embedding user text.

sanitize_user_content()

Always call this before embedding user-provided text in a SLIM document. It escapes all SLIM sigils:

from slim_parser import sanitize_user_content

user_input = "@model: evil-model\n> ABORT everything"
safe = sanitize_user_content(user_input)
# → "\@model: evil-model\n\> ABORT everything"

doc_text = f"""
@slim: 2.0
@+task: review

::USER_CONTENT
{safe}
"""

Characters escaped: @, $, >, ~ everywhere; :: at line start only → \@, \$, \>, \~, \::

@include path traversal

• Paths resolved relative to the including file's directory
• Absolute paths: allowed but linters should flag them
• Network URLs: disabled by default; parser-implementation-dependent
• Circular includes: parse error

API Python Parser

Parsing a file

from slim_parser import SLIMParser, ParseMode

parser = SLIMParser()

# From file
doc = parser.parse_file("agent.slm")

# From string
doc = parser.parse(slm_text)

# Strict mode (raises on errors)
doc = parser.parse(slm_text, mode=ParseMode.STRICT)

# Lenient mode (collects warnings, returns partial)
doc = parser.parse(slm_text, mode=ParseMode.LENIENT)

SLIMDocument properties

Utility functions

from slim_parser import sanitize_user_content, SLIMParser

# Sanitize user content before embedding
safe = sanitize_user_content(user_text)

# Format a .slm file (canonical form)
parser = SLIMParser()
canonical = parser.format(slm_text)

# Validate without parsing full doc
errors = parser.validate(slm_text)   # list[str], empty = valid

API JavaScript Library

The browser/Node.js library is available in website/js/slim.js and exposed as window.SLIM.

// Parse a SLIM document
const doc = SLIM.parse(slmText);
// → { headers, llmHeaders, sections, blocks, schemas,
//     directives, bodyText, strippedText, tokenEstimate }

// Convert Markdown → SLIM
const slm = SLIM.mdToSlm(markdownText);

// Convert JSON → SLIM
const slm = SLIM.jsonToSlm(jsonText);

// Syntax-highlight SLIM text (returns HTML string)
const html = SLIM.highlight(slmText);

// Estimate token count
const tokens = SLIM.estimateTokens(text);
// → Math.round(text.length / 4)

// Sanitize user content before embedding
const safe = SLIM.sanitizeUserContent(userText);

Plugins VS Code Extension

Build from source

cd vscode-slim
npm install
npm run package          # produces slim-language-1.0.0.vsix
code --install-extension slim-language-1.0.0.vsix

Features

Plugins IntelliJ IDEA Plugin

Build from source

cd intellij-slim
./gradlew buildPlugin      # → build/distributions/intellij-slim-1.0.0.zip
./gradlew runIde           # opens sandbox IDE for testing

Requirements

• IntelliJ IDEA 2023.2+ (Community or Ultimate)
• Java 17+
• Gradle 8.5+

Features

Plugins Notepad++ UDL

SLIM syntax highlighting for Notepad++ via a User Defined Language (UDL) XML file.

Install

1. Open Notepad++
2. Go to Language → User Defined Language → Define your language…
3. Click Import and select notepadpp-slim/slim.udl.xml
4. Restart Notepad++
5. Open any .slm file — highlighting applies automatically

Features

• Syntax highlighting for all SLIM constructs using dark theme colors
• ::BLOCK section fold regions
• Line commenting with ~
• Keyword highlighting: CALL ASSERT YIELD EMIT LOG ABORT WAIT RETRY

Reference BNF Grammar

document     ::= header_zone content_zone
header_zone  ::= (header_line | blank_line)*
header_line  ::= at_key ": " value newline
               | "@include" ": " path newline
at_key       ::= ("@" | "@+") [a-z][a-z0-9_-]*

content_zone ::= (section | schema | directive
               | table_row | bullet | ordered_step
               | paragraph | comment | blank_line)*
section      ::= section_open section_content
section_open ::= "::" NAME (" " type)? newline
               | ":::" NAME (" " type)? newline
section_content ::= (escaped_line | content_line)*
escaped_line ::= "\::" text newline
schema       ::= ":" identifier newline property+
property     ::= "  " identifier ("!" | "?")? ": " type
                 (" = " value)? newline
               | "  " "->" " " return_spec newline
directive    ::= ">" " " KEYWORD (" " args)? newline
table_row    ::= "|" (cell "|")+ newline
bullet       ::= "-" " " text newline
ordered_step ::= [0-9]+ "." " " text newline
comment      ::= "~" text? newline
variable_ref ::= "$" identifier ("." identifier | "[" integer "]")*

NAME         ::= [A-Za-z][A-Za-z0-9_]*
KEYWORD      ::= "CALL" | "ASSERT" | "YIELD" | "EMIT"
               | "LOG" | "ABORT" | "WAIT" | "RETRY"

Reference Reserved Header Keys

Custom keys are permitted. All reserved keys may be used with @+ prefix to expose to LLM, except @model and @include.

Guide Migration from Markdown

Structural equivalences

Step-by-step migration

1. Rename the file from .md to .slm
2. Add @slim: 1.0 as the very first line
3. Convert YAML frontmatter (--- block) to @key: or @+key: headers and remove the --- delimiters
4. Replace ``` lang ``` fenced blocks with ::BLOCK_NAME lang (no close tag; content is verbatim)
5. Replace <!-- comments --> with ~ comment lines
6. Remove | --- | separator rows from all tables
7. Run slim validate yourfile.slm to verify

SLIM-only features (no Markdown equivalent)

• @key header stripping — tokens never reach LLM
• $variable interpolation resolved at parse time
• > DIRECTIVE command syntax for workflow steps
• :tool schema definitions with typed parameters
• ::NAME type sections — typed, injection-safe, no close tag
• ~ comments — always stripped, zero LLM overhead
• list<T>, dict<K,V>, [enum|values] type system
• Multi-document files with --- separators
• @include imports