Agent skill

use-toon

Use TOON (Token-Oriented Object Notation) with schema.org vocabulary for prompting and instructing subagents and builtin agents. Use when delegating tasks to agents, structuring agent prompts, or specifying expected response formats. DO NOT use for external API calls or when JSON parsing is required.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/use-toon

SKILL.md

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

<quick_start> 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

<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>

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

Types auto-detected: strings, numbers, booleans, null.

<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}

<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>

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

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

Didn't find tool you were looking for?

Be as detailed as possible for better results