Skip to content

LeoYeAI/agent-master-skills / skills/ai-md

AI.MD — Convert any human-written CLAUDE.md into AI-native structured format. Your CLAUDE.md is read by AI every single turn, not by you — so write it in AI's language. Battle-tested: 5 rounds, 4 models (GPT-5.3, Gemini 2.5 Pro, Grok-4, Claude Opus 4.6). Structured-label format raised Codex compliance from 6/8 → 8/8 on identical content. Same rules, fewer tokens, higher precision. This skill contains the complete methodology: how to take natural language instructions and convert them into a format that LLMs actually follow better. Run with: "distill my CLAUDE.md" or "rewrite my MD for AI" or "蒸餾" or "AI.MD"

FileKindSize
README.mdmarkdown6.0 KB
SKILL.mdskill md18.9 KB
_meta.jsonconfig263 B
docs/_config.ymlconfig109 B
docs/index.mdmarkdown2.6 KB
examples/after.mdmarkdown3.8 KB
examples/before.mdmarkdown4.6 KB
# AI.MD

**Your CLAUDE.md is read by AI every single turn, not by you — so write it in AI's language.**

AI.MD converts human-written `CLAUDE.md` into AI-native structured-label format.
Not "compressed" — **restructured** so LLMs actually follow your rules better.

## The Problem

```
You type "hi" → AI reads your CLAUDE.md → responds
50 turns later → AI has re-read it 50 times
```

Claude Code re-reads `CLAUDE.md` on **every conversation turn**. Most CLAUDE.md files are written in human prose — paragraphs, parenthetical explanations, long sentences with multiple rules crammed together.

This wastes tokens AND reduces compliance. We proved it.

## Battle-Tested Results

Tested 2026-03 with real CLAUDE.md (washinmura.jp), 5 rounds, 4 models:

| Format | Codex (GPT-5.3) | Gemini 2.5 Pro | Claude Opus 4.6 |
|--------|-----------------|----------------|-----------------|
| Human prose (many rules) | 6/8 | 6.5/8 | 8/8 |
| AI-native structured | **8/8** | **7/8** | **8/8** |

**Same rules. Different format. Higher compliance across all models.**

The uncomfortable finding: Adding more rules in prose **decreased** compliance (8/8 → 6/8).
Converting to structured format **restored and exceeded** it (6/8 → 8/8).

### Size Reduction

Same real-world CLAUDE.md, before and after conversion:

| Metric | Before (prose) | After (AI-native) | Change |
|--------|---------------|-------------------|--------|
| File size | 13,474 bytes | 6,332 bytes | **-53%** |
| Line count | 224 lines | 142 lines | **-37%** |

Claude Code officially recommends keeping CLAUDE.md **under 200 lines** (re-read every turn).
The original was **over the limit** (224). After AI.MD conversion: **well within** (142).

Less tokens burned per turn × every turn × every session = compounding savings.

## What Makes It Work

Three mechanisms explain why structured-label format outperforms prose:

### 1. One Concept Per Line = Focused Attention

LLMs don't "read" — they **attend**. When rules share a line, attention splits.
When each rule has its own line, each gets full attention weight.

```
# BAD: 5 rules, 1 line — AI follows ~3
EVIDENCE: no-fabricate no-guess | banned:應該是 | Read/Grep→行號 | "好像"→self-test | guess=shame-wall

# GOOD: 5 rules, 5 lines — AI follows all 5
EVIDENCE:
  core: no-fabricate | no-guess | unsure=say-so
  banned: 應該是/可能是 → 先拿數據
  proof: all-claims-need(data/line#/source)
  hear-doubt: "好像"/"覺得" → self-test → 禁反問user
  violation: guess → shame-wall
```

### 2. Explicit Labels = Zero Inference

Labels declare meaning. Prose requires the model to infer it.

```
# BAD: AI must infer what (防搞混) means
GATE-1: 收到任務→先用一句話複述(防搞混)

# GOOD: Labels tell AI exactly what each part does
GATE-1 複述:
  trigger: new-task
  action: first-sentence="你要我做的是___"
  exception: signal=處理一下 → skip
```

### 3. Semantic Anchoring = Direct Matching

Labels act as matchable tags. When user says "add an API", the model matches it to `new-api:` directly — like a hash lookup instead of full-text search.

```
MOAT:
  new-api: must check health-check.py coverage (GATE-5)
```

This specific technique fixed a test case that failed 5 consecutive times across all models.

## Install

```bash
mkdir -p ~/.claude/skills/ai-md
curl -o ~/.claude/skills/ai-md/SKILL.md \
  https://raw.githubusercontent.com/sstklen/ai-md/main/SKILL.md
```

## Usage

In Claude Code, say any of:
- `AI.MD` or `distill my CLAUDE.md`
- `rewrite my MD for AI`
- `蒸餾`

The skill runs in two stages:
1. **Preview** — measures your current token burn, shows before/after examples
2. **Distill** — converts with backup, tests with multiple models, reports scores

## The Conversion Process

The full methodology is in [`SKILL.md`](SKILL.md), but here's the summary:

| Phase | What Happens |
|-------|-------------|
| **1. Understand** | Read like a compiler — identify triggers, actions, constraints, metadata, and deletable human explanations |
| **2. Decompose** | Break every `\|` separator, `()` parenthetical, and "and/but" conjunction into atomic rules |
| **3. Label** | Assign function labels: `trigger:` `action:` `exception:` `banned:` `policy:` etc. |
| **4. Structure** | Organize into hierarchy: `<gates>` → `<rules>` → `<rhythm>` → `<conn>` → `<ref>` |
| **5. Resolve** | Detect and resolve hidden conflicts between rules (priority, yields-to, not-triggered) |
| **6. Test** | Validate with 2+ LLM models, 8 test questions, same pass/fail criteria |

## Special Techniques

| Technique | What It Does |
|-----------|-------------|
| **Bilingual labels** | English labels (shorter, universal) + native language output strings |
| **State machine gates** | Each gate has trigger → action → exception → priority. Clear execution model. |
| **XML section tags** | `<gates>` `<rules>` `<rhythm>` create hard boundaries, prevent rule-bleed |
| **Cross-reference** | Single source of truth + `(GATE-5)` references instead of duplicates |
| **"What Not Why"** | Delete all explanations of WHY a rule exists. AI needs WHAT, not WHY. |
| **Not-triggered lists** | Explicit examples of when a rule should NOT fire. Prevents over-triggering. |
| **Conflict detection** | Check every pair of gates for hidden conflicts. Add priority/yields-to. |

## Template

```xml
# PROJECT-NAME | lang:xx | for-AI-parsing

<user>
identity, tone, signals, decision-style
</user>

<gates label="priority: gates>rules>rhythm">
GATE-1 name:
  trigger: ...
  action: ...
  exception: ...
</gates>

<rules>
RULE-NAME:
  core: ...
  banned: ...
  violation: ...
</rules>

<rhythm>
workflow patterns as key: value
</rhythm>

<conn>
connection strings (never compress facts)
</conn>
```

## Examples

See [`examples/before.md`](examples/before.md) and [`examples/after.md`](examples/after.md) for a real conversion.

## Key Insight

> **More rules in prose = worse compliance.**
> **Same rules in structure = better compliance.**
>
> Your beautifully written CLAUDE.md might be hurting your AI's performance.
> Structure > Prose. Always.

## License

MIT
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall