Skip to content
Skills Library
Programming · Conversion & formats

yon-write

/yon-write

YON Writing & Compilation Mode. Use when creating, generating, converting, or writing YON content. Triggers on: "write YON", "convert to YON", "create a .yon file", "encode this as YON", "YON format", or any request where the expected output is YON records. Also triggers when unstructured content should be structured into YON even without explicit keyword — e.g., working in a YON project. Use yon-read instead when reading, interpreting, explaining, or summarizing existing YON.

Repository
open-skills ↗
Licence
Apache-2.0
Last repository change
05.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 05.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

YON Writing & Compilation Mode. Use when creating, generating, converting, or writing YON content. Triggers on: "write YON", "convert to YON", "create a .yon file", "encode this as YON", "YON format", or any request where the expected output is YON records. Also triggers when unstructured content should be structured into YON even without explicit keyword — e.g., working in a YON project. Use yon-read instead when reading, interpreting, explaining, or summarizing existing YON.

Triggers from the description

write YONconvert to YONcreate a .yon fileencode this as YONYON format
Original author description

YON Writing & Compilation Mode. Use when creating, generating, converting, or writing YON content. Triggers on: "write YON", "convert to YON", "create a .yon file", "encode this as YON", "YON format", or any request where the expected output is YON records. Also triggers when unstructured content should be structured into YON even without explicit keyword — e.g., working in a YON project. Use yon-read instead when reading, interpreting, explaining, or summarizing existing YON.

How it works

  1. The Encoding Principle
  2. When NOT to Generate YON
  3. Decision Gate — Before You Write
  4. Output Rules
  5. Required Fields Per Tag
  6. Conversion Patterns
  7. Worked Example: Prose → YON
  8. Handling Ambiguous Input
  9. Validation Checklist
  10. Record Order (Recommended)
Original SKILL.md headings · 179 lines, 1,147 words
SKILL.md preview
---
name: yon-write
description: >
  YON Writing & Compilation Mode. Use when creating, generating, converting, or writing YON content. Triggers on: "write YON", "convert to YON", "create a .yon file", "encode this as YON", "YON format", or any request where the expected output is YON records. Also triggers when unstructured content should be structured into YON even without explicit keyword — e.g., working in a YON project. Use yon-read instead when reading, interpreting, explaining, or summarizing existing YON.
visibility: public
triggers:
  - "write YON"
  - "convert to YON"
  - "create a .yon file"
  - "encode this as YON"
  - "YON format"
next-skills:
  - skill: yon-read
    phrase: "/yon-read"
    why: "Read back the authored YON to confirm it parses and means what was intended — the family round-trip."
  - skill: double-check
    phrase: "/double-check"
    why: "Targeted re-verification that the newly written YON is syntactically and semantically correct before relying on it."
  - skill: github-sync
    phrase: "/github-sync"
    why: "Commit and push the new .yon file once it is written and validated."
---

# /yon-write

YON Writing & Compilation Mode — create, generate, or convert content into YON (YounndAI Object Notation), a line-oriented, stream-first Cognitive Architecture for AI systems.

## The Encoding Principle

**Foundational contract: YON preserves what the emitter wants to send. An encoder preserves what was said. A translator decides what was meant. YON is an encoder.**

- `"probably purple"` stays `"probably purple"` — do not resolve to `confidence: 0.6`
- `"like everyone else does"` stays verbatim — do not interpret vague social references
- Hedging, uncertainty, and conversational nuance are preserved exactly
- Links, paths, URLs are preserved byte-for-byte. Never alias, shorten, or rewrite.
- The human's intent is sovereign. The encoding layer is faithful to the source. Interpretation is downstream.

## When NOT to Generate YON

YON is a Cognitive Architecture for AI pipelines, not a universal data format. Do not use it for:

- **API responses** — YON adds +54–185% size vs JSON minified for pure data payloads
- **Config files** — TOML or YAML are better for human-edited configuration
- **Short messages under ~340 tokens** — plain text is cheaper at small context sizes
- **Database records** — use JSON, Protobuf, or native formats
- **Simple key-value data** — YON's structural baseline adds no benefit for flat data

YON belongs in: system prompts, agent instructions, multi-hop pipelines, rules/policies, workflows, cognitive traces, provenance tracking, and anywhere intent + data + audit travel together.

## Decision Gate — Before You Write

### 1. Choose Profile

| Profile   | Use When                                             |
|-----------|------------------------------------------------------|
| `core`    | Basic structure (docs, notes)                        |
| `decl`    | Rules and schemas (policies, configs)                |
| `exec`    | Workflows (steps, checks, error handling)            |
| `audit`   | Provenance tracking                                  |
| `cognitive` | AI thought chains                                  |
| `agent`   | Multi-agent systems                                  |

### 2. Choose Format

| Format  | Use Case                                  |
|---------|-------------------------------------------|
| `canon` | Human docs, reference material            |
| `min`   | LLM pipelines, agents (recommended default) |
| `ultra` | Cost-critical transport                   |

### 3. Choose Kind

`doc`, `rule`, `workflow`, `skill`, `sidecar`, `spec`, `context`, `memory`, `note`, `prompt`

## Output Rules

**When writing to a `.yon` file:** Output YON records ONLY. No markdown, no fenced blocks, no commentary. Pure YON.

**When showing YON in conversation:** Use a fenced code block and briefly explain your choices (profile, kind, key decisions made during encoding).

**Always:**
- First non-comment line MUST be `@DOC`
- Separator: ALWAYS ` | ` (space, pipe, space)
- Bare values when matching `[A-Za-z0-9_./:@+#-]+`, otherwise double-quote
- Values containing `|` MUST be quoted: `regex="a|b|c"`
- Typed keys for non-strings: `n:int=3`, `active:bool=true`, `ts:ts=2026-01-01T00:00:00Z`
- `@MAP` pairs: BOTH sides quoted: `pairs=["key"->"value"]`
- `@BEGIN`/`@END` blocks: `mime=` required, `boundary=` 8+ chars, `id=` required when multiple blocks or referenced
- Self-describing docs: add `guide="https://yon.younndai.com/yon-guide.txt"` when the document targets LLMs without YON knowledge

## Required Fields Per Tag

| Tag          | Required Fields                                                               |
|--------------|-------------------------------------------------------------------------------|
| `@DOC`       | `ver`, `id`, `title`                                                         |
| `@SEC`       | `name`                                                                        |
| `@NOTE`      | `text`                                                                        |
| `@STAMP`     | `ts`, `src`                                                                   |
| `@RULE`      | `lvl` (MUST/MUST_NOT/SHOULD/SHOULD_NOT/MAY), `when`, `then`                 |
| `@MAP`       | `name`, `pairs`                                                               |
| `@CFG`       | `id`, `set`                                                                   |
| `@INTENT`    | `goal`                                                                        |
| `@CHECK`     | `rid`, `assert`, `fail` (ABORT/WARN/SKIP), `msg`                            |
| `@STEP`      | `rid`, `n:int`, `op`                                                         |
| `@CATCH`     | `target`, `on`, `do`                                                         |
| `@RETRY`     | `target`, `max`                                                               |
| `@PATCH`     | `ts`, `target`, `set`                                                        |
| `@VOID`      | `ts`, `target`                                                                |
| `@REDACTION` | `target`, `reason`                                                            |
| `@CONSENT`   | `party`, `scope`                                                              |

## Conversion Patterns

### Prose → Rules
- `"Always"` / `"Must"` → `lvl=MUST`
- `"Never"` / `"Must not"` → `lvl=MUST_NOT`
- `"Prefer"` / `"Should"` → `lvl=SHOULD`
- `"Optional"` / `"May"` → `lvl=MAY`

### Tables → Schema / Map / Cfg
- Enum/Choices → `@SCHEMA key=severity | opts=[low,med,high] | default=med`
- Condition→Outcome → `@MAP pairs=["input"->"output"]`
- Multi-setting → `@CFG id=X | set=[k=v]` then `@MAP pairs=["ctx"->"cfg:X"]`

### Code/JSON/Logs → Blocks
```
@BEGIN CODE | id=handler | mime="text/x-python" | boundary="bnd_py_001"
def hello():
    return "world"
@END CODE | boundary="bnd_py_001"
```

### List Constraints
- `in`/`out`: reference tokens ONLY (`block:`, `rid:`, `cfg:`, `ref:`, `file:`, `url:`, `agent:`, etc.)
- `args`/`set`: field items ONLY (`key=value`, `key:type=value`)
- `pairs`: map pairs ONLY (`"k"->"v"`)
- Depth limit = 1. No nested lists.

## Worked Example: Prose → YON

**Input (user's messy prose):**
> "ok so we need an api rate limiting thing. all calls must have auth tokens. standard users get 100/min, premium 500. if they hit the limit they should probably back off exponentially. never expose internal errors in responses."

**Output:**
```
@DOC ver=2.0 | id=api-rate-policy | title="API Rate Limiting Policy" | kind=rule | profile=decl | fmt=min
@INTENT goal="Define authentication and rate limiting standards for public API"

@SEC name="Authentication"
@RULE rid=rule:auth | lvl=MUST | when="calling any API endpoint" | then="include valid auth token"

@SEC name="Rate Limits"
@MAP name=TierLimits | pairs=["standard"->"100/min","premium"->"500/min"]
@RULE rid=rule:backoff | lvl=SHOULD | when="rate limit exceeded" | then="probably back off exponentially"

@SEC name="Error Handling"
@RULE rid=rule:errors | lvl=MUST_NOT | when="returning API response" | then="expose internal error details"

@STAMP ts:ts=2026-03-30T12:00:00Z | src=human
```

**What the encoding did:** Detected section boundaries from topic shifts. `"must"` → MUST, `"never"` → MUST_NOT, `"should probably"` → SHOULD. Preserved `"probably back off exponentially"` verbatim (hedging preserved). Dropped `"ok so"` and `"thing"` (zero semantic content).

**What the encoding did NOT do:** Did not resolve `"probably"` into a confidence level. Did not reorder the user's sequence. Did not add fields the user didn't mention.

## Handling Ambiguous Input

When the input doesn't map cleanly to YON:

- **Unclear when/then split:** Use a broad `when` (e.g., `when="in all contexts"`) and put the action in `then`. Don't fabricate conditions.
- **Mixed intent and data:** Put purpose in `@INTENT`, constraints in `@RULE`, factual descriptions in `@NOTE`. When unsure, `@NOTE` is the safe default.
- **Vague severity:** Default to `SHOULD` and flag with `note="severity inferred — confirm with author"`
- **Nested/complex structures:** Flatten. Use `@CFG` for grouped settings, `@BEGIN`/`@END` blocks for verbatim payloads. Depth limit is 1.

## Validation Checklist

After writing, verify:

- [ ] Exactly one `@DOC`, first non-comment record
- [ ] All `@BEGIN` have matching `@END` with same TAG and boundary
- [ ] All `@BEGIN` include `mime=`
- [ ] No duplicate keys within a single record
- [ ] `@MAP` uses `pairs=[...]` with both sides quoted
- [ ] Canonical separator ` | ` used consistently
- [ ] All required fields present for each tag
- [ ] `@RULE` with `lvl=MUST` or `MUST_NOT` are individual records (never merged/summarized)

## Record Order (Recommended)

`@DOC` → `@STAMP` → `@META` → `@DEF` → `@REF` → `@INTENT` → `@SCOPE` → `@SEC` sections → `@BEGIN`/`@END` blocks

## Detailed References

For edge cases, extended syntax, and complete examples:

- [references/write-card.txt](references/write-card.txt) — Complete compilation reference card with one-shot examples
- [references/domains-card.txt](references/domains-card.txt) — All profiles, formats, kinds, and official domain list
- [references/generation-guide.md](references/generation-guide.md) — Comprehensive examples: rules, workflows, cognitive traces, multi-agent, prose encoding

Full spec: https://yon.younndai.com
Files in this package (4)
  • SKILL.md 10 KB
  • references/domains-card.txt 3 KB
  • references/generation-guide.md 4 KB
  • references/write-card.txt 6 KB

Versions

The database has no other skills named yon-write.

Database snapshot: 13.11.2026 · package version 6a10d688ccf4 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100yon-read
    Read, interpret, or explain existing YON content. Trigger on any .yon file, YON snippet (lines with @TAG|...|... patterns), or when the user says "read this YON", "what does this YON mean", "explain this @DOC/@RULE/@STEP", "summarize this YON", "interpret this record". Do NOT…
  • 100handoff
    Generate a structured cold-agent handoff brief (YAML frontmatter + Obsidian markdown + YON blocks) that any fresh LLM session can pick up and execute. Trigger when the user runs /handoff or says "create a handoff", "dispatch to a fresh agent", "hand this to a cold session",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.