---
name: majiayu000/use-toon
source: https://app.decimal.ai/s/majiayu000-use-toon@1/SKILL.md
source_sha256: bfae0f1d0bc9
---

<objective>
TOON with schema.org vocabulary provides a standard format for prompting and instructing agents. Use it to structure task delegation, specify expected outputs, and ensure consistent responses from subagents and builtin agents.

Key benefits:
- **Clear task structure**: schema.org Action types define what the agent should do
- **Expected output format**: Specify result type so agents return consistent data
- **Token efficiency**: 30-60% fewer tokens than JSON = more context for agent reasoning
- **Semantic interoperability**: Standard vocabulary eliminates ambiguity
</objective>

<quick_start>
<syntax>
**Object**: `key: value`

**Nested**: Indentation (2 spaces)

**Simple array**: `items[3]: a,b,c`

**Tabular array** (uniform objects):

```toon
users[2,]{id,name}:
  1,Alice
  2,Bob
```

</syntax>

<when_to_use>
| Use TOON | Use JSON |
|----------|----------|
| Agent task prompts | External API calls |
| Subagent instructions | Parsing with JSON.parse() |
| Expected response format | Human debugging |
| Agent-to-agent data | Deeply nested structures |
</when_to_use>
</quick_start>

<agent_prompting>
<task_delegation>
Structure agent tasks as schema.org Actions:

```toon
@type: SearchAction
@id: task-001
description: Find all error handling patterns in the codebase

object:
  @type: SoftwareSourceCode
  codeRepository: ./src

expectedResult:
  @type: ItemList
  description: Files with error handling patterns
```

The agent knows:
- **What to do**: SearchAction = find/search
- **What to search**: object defines the target
- **What to return**: expectedResult specifies format
</task_delegation>

<instruction_format>
When instructing agents, include:

```
[Task description in natural language]

Input:
[TOON block with @type, @id, and structured data]

Return your result in TOON format using:
- @type: [expected type, e.g., ItemList, Report, SearchAction]
- @id: [task-id]-result
- Use tabular notation for lists
```
</instruction_format>

<common_task_types>
| Task | schema.org Type | Use |
|------|-----------------|-----|
| Find/search | `SearchAction` | Code search, file discovery |
| Create/generate | `CreateAction` | Generate code, create files |
| Modify/update | `UpdateAction` | Edit files, refactor code |
| Validate/review | `AssessAction` | Code review, validation |
| Delete/remove | `DeleteAction` | Remove files, clean up |
| Analyze | `AnalyzeAction` | Code analysis, metrics |
</common_task_types>
</agent_prompting>

<core_syntax>
<scalars>

```toon
name: Alice
age: 30
active: true
score: null
```

Types auto-detected: strings, numbers, booleans, null.
</scalars>

<nesting>
```toon
user:
  name: Alice
  address:
    city: Boston
    zip: 02101
```
Use 2-space indentation for nesting.
</nesting>

<simple_arrays>

```toon
tags[3]: red,green,blue
ids[4]: 1,2,3,4
```

Format: `key[count]: item1,item2,...`
</simple_arrays>

<tabular_arrays>
For arrays of uniform objects (most efficient):

```toon
users[3,]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Carol,user
```

Format: `key[rowCount,]{col1,col2,...}:`

Each row provides values in column order, comma-separated.
</tabular_arrays>

</core_syntax>

<schema_vocabulary>
Use schema.org types and properties as shared vocabulary between agents.

<required_metadata>
Every TOON object MUST include:
- `@type`: schema.org type (e.g., `Person`, `SearchAction`, `ItemList`)
- `@id`: Unique identifier for the object

```toon
@type: Person
@id: user-123
name: Alice
email: alice@example.com
```
</required_metadata>

<common_types>
| Type | Use Case | Key Properties |
|------|----------|----------------|
| `Action` | Task execution | agent, object, result, actionStatus |
| `SearchAction` | Search/find operations | query, result |
| `CreateAction` | Creation operations | result, targetCollection |
| `UpdateAction` | Modifications | targetCollection, result |
| `AssessAction` | Validation/review | result, actionStatus |
| `ItemList` | Collections | itemListElement, numberOfItems |
| `Thing` | Generic entity | name, description, identifier |
| `CreativeWork` | Documents/code | author, dateCreated, text |
| `SoftwareSourceCode` | Code snippets | programmingLanguage, codeRepository |
</common_types>

<action_status>
For Action types, use `actionStatus` property:

| Status | Meaning |
|--------|---------|
| `PotentialActionStatus` | Not yet started |
| `ActiveActionStatus` | In progress |
| `CompletedActionStatus` | Successfully finished |
| `FailedActionStatus` | Failed with error |

```toon
@type: SearchAction
@id: search-001
actionStatus: CompletedActionStatus
query: auth handlers
resultCount: 3
```
</action_status>

<nested_types>
Use `@type` for nested objects too:

```toon
@type: CreateAction
@id: create-file-001
actionStatus: CompletedActionStatus

result:
  @type: SoftwareSourceCode
  name: auth.ts
  programmingLanguage: TypeScript

agent:
  @type: SoftwareApplication
  name: CodeAgent
```
</nested_types>

<property_conventions>
Prefer schema.org property names:

| Instead of | Use | schema.org property |
|------------|-----|---------------------|
| `file` | `name` | Thing.name |
| `path` | `url` | Thing.url |
| `content` | `text` | CreativeWork.text |
| `created` | `dateCreated` | CreativeWork.dateCreated |
| `author` | `author` | CreativeWork.author |
| `count` | `numberOfItems` | ItemList.numberOfItems |
| `items` | `itemListElement` | ItemList.itemListElement |
| `error` | `error` | Action.error |
</property_conventions>
</schema_vocabulary>

<prompting_patterns>
<structured_input>
When asking an agent to process structured data, use schema.org types:

```
Process this item list:

@type: ItemList
@id: pending-review
numberOfItems: 3

itemListElement[3,]{@type,identifier,name,status}:
  Product,A1,Widget,pending
  Product,A2,Gadget,shipped
  Product,A3,Gizmo,pending

Return pending items as an ItemList in TOON format.
```
</structured_input>

<requesting_toon_output>
Include format instruction with schema.org guidance:

```
Return your answer in TOON format:
- Use appropriate schema.org @type (Action, ItemList, etc.)
- Include @id for the result object
- Use schema.org property names (name, description, result)
- Use tabular notation for uniform lists
- Wrap in ```toon code block
```
</requesting_toon_output>

<agent_task_pattern>
For agent task delegation, structure as Action:

```toon
@type: SearchAction
@id: task-001
description: Find all authentication handlers

object:
  @type: SoftwareSourceCode
  codeRepository: ./src

expectedResult:
  @type: ItemList
  description: Files with auth handlers
```
</agent_task_pattern>

<agent_response_pattern>
Agents return completed Actions:

```toon
@type: SearchAction
@id: task-001
actionStatus: CompletedActionStatus

result:
  @type: ItemList
  @id: task-001-result
  numberOfItems: 3

  itemListElement[3,]{@type,name,url,description}:
    SoftwareSourceCode,handleLogin,src/auth.ts:42,Login handler
    SoftwareSourceCode,handleLogout,src/auth.ts:78,Logout handler
    SoftwareSourceCode,authGuard,src/middleware.ts:15,Auth middleware
```
</agent_response_pattern>

<extraction_pattern>
Parse TOON from LLM response:

```python
def extract_toon(response: str) -> str:
    if "```toon" in response:
        return response.split("```toon")[1].split("```")[0].strip()
    elif "```" in response:
        return response.split("```")[1].split("```")[0].strip()
    return response.strip()
```
</extraction_pattern>
</prompting_patterns>

<api_reference>
Using the toon-format Python library (`pip install toon-format`):

```python
from toon_format import encode, decode, estimate_savings

# Python dict to TOON
toon_str = encode(data, options={})

# TOON to Python dict
data = decode(toon_str, options={})

# Check efficiency
stats = estimate_savings(data)
# Returns: {"json_tokens": N, "toon_tokens": M, "savings_percent": X}
```

<options>
| Option | Default | Use |
|--------|---------|-----|
| delimiter | "," | Row separator: ",", "\t", "|" |
| lengthMarker | "" | Prefix for lengths: "", "#" |
| strict | False | Validation strictness |
</options>
</api_reference>

<quoting_rules>
Quote strings when they would be ambiguous:

| Value    | Requires Quotes | Reason                      |
|----------|-----------------|-----------------------------|
| `""`     | Yes             | Empty string                |
| `"true"` | Yes             | Boolean keyword as string   |
| `"123"`  | Yes             | Numeric string (not number) |
| `"a,b"`  | Yes             | Contains delimiter          |

Unquoted values are parsed as their natural type.
</quoting_rules>

<success_criteria>
TOON with schema.org is correctly applied when:

- Every object has `@type` (schema.org type) and `@id`
- Property names follow schema.org conventions
- Actions use appropriate `actionStatus` values
- Tabular notation used for uniform `itemListElement` arrays
- Code blocks tagged with `toon` language
- Data round-trips correctly: `decode(encode(data)) == data`
</success_criteria>

<examples>
<example name="search_action">
```toon
@type: SearchAction
@id: search-auth-001
actionStatus: CompletedActionStatus
query: authentication handlers

result:
  @type: ItemList
  @id: search-auth-001-result
  numberOfItems: 3

  itemListElement[3,]{@type,name,url,description}:
    SoftwareSourceCode,handleLogin,src/auth.ts:42,Login handler
    SoftwareSourceCode,handleLogout,src/auth.ts:78,Logout handler
    SoftwareSourceCode,authGuard,src/middleware.ts:15,Auth middleware
```
</example>

<example name="create_action">
```toon
@type: CreateAction
@id: create-component-001
actionStatus: CompletedActionStatus
description: Create React component

result:
  @type: SoftwareSourceCode
  @id: button-component
  name: Button.tsx
  url: src/components/Button.tsx
  programmingLanguage: TypeScript
  dateCreated: 2025-01-15
```
</example>

<example name="assess_action">
```toon
@type: AssessAction
@id: validate-005
actionStatus: CompletedActionStatus
description: Validate outcome specification

result:
  @type: Report
  @id: validate-005-report
  name: Validation Report
  reportStatus: NeedsAttention

  itemListElement[2,]{@type,name,description}:
    Warning,missing-desc,Description field is empty
    Info,add-examples,Consider adding examples
```
</example>

<example name="item_list">
```toon
@type: ItemList
@id: pending-tasks
description: Tasks awaiting review
numberOfItems: 3

itemListElement[3,]{@type,identifier,name,status}:
  Action,task-001,Implement auth,PotentialActionStatus
  Action,task-002,Add tests,ActiveActionStatus
  Action,task-003,Update docs,PotentialActionStatus
```
</example>
</examples>