add-token-efficiency

name	add-token-efficiency
description	Use when creating commands, skills, or docs — defines generic compression patterns (minified JSON, abbreviations, glob patterns, single breaks). Load before any write where token density matters.

Token Efficiency

Overview

Every token counts. Resources must be compressed without losing clarity. This skill defines mandatory compression patterns for all ADD outputs (commands, skills, scripts, docs).

For doc-specific concerns (schemas, depth floors, output-length doctrine, validation gate), see {{skill:add-doc-schemas/SKILL.md}}. Output length is governed there — this skill covers compression patterns only.

When NOT to use

• Output-length decisions (word/char caps, depth floors) → use {{skill:add-doc-schemas/SKILL.md}}
• CLAUDE.md style and content rules → use {{skill:add-claude-md-style/SKILL.md}}
• ID format / branch naming → use {{skill:add-id-convention/SKILL.md}}

---

Mandatory Patterns

1. JSON Specs (Always Minified)

# BAD - 156 chars
```json
{
  "type": "command",
  "trigger": "slash",
  "structure": "phases"
}

GOOD - 48 chars

{"type":"cmd","trigger":"slash","structure":"phases"}

### 2. JSON = DATA. Markdown = INSTRUCTIONS.

JSON minified is exclusively for **data the agent looks up**: configs, specs, tech stack, path mappings, key-value pairs. Everything that orients behavior — rules, instructions, guidance, constraints, conventions — uses **markdown** (lists, tables, prose).

**Minified JSON — structured data:**
- Tech stack (`{"pkg":"npm","build":"turbo","lang":"typescript"}`)
- Path mappings (`{"domain":"libs/domain/src","api":"apps/backend/src"}`)
- Config values, detection rules, routing tables

**Markdown — rules, instructions, orientation:**
- Dependency rules, import constraints
- Behavioral guidance (do/dont, always/never)
- Architecture hierarchy and layer rules
- Naming conventions, placement rules
- Checklists, sequential steps

```markdown
# ❌ WRONG — rule inside JSON
{"hierarchy":"domain → backend → apps","rule":"inner never imports outer"}

# ✅ RIGHT — rule as markdown
domain → backend → apps. Inner never imports outer.

# ❌ WRONG — instruction inside JSON
{"note":"Read .codeadd/wiki/index.md, then the relevant domain page"}

# ✅ RIGHT — instruction as markdown
Read the wiki hub, then the relevant domain page.

# ❌ WRONG — placement guidance as JSON
{"Entities":"libs/domain/src/entities","Repos":"libs/app-database/src/repositories"}

# ✅ RIGHT — placement as table (behavioral orientation)
| What | Where |
|---|---|
| Entities | libs/domain/src/entities |
| Repos | libs/app-database/src/repositories |

# ✅ CORRECT — data as JSON
{"pkg":"npm","build":"turbo","lang":"typescript"}
{"backend":{"framework":"NestJS","version":"10"}}

Test: "Is this something the agent looks up, or something the agent must follow?" Look up → JSON. Follow → markdown.

3. Glob Patterns

# BAD
- .claude/commands/feature.md
- .claude/commands/plan.md
- .claude/commands/dev.md

# GOOD
.claude/commands/*.md

4. No Decorative Formatting

BAD: ──────── dividers wrapping ## Section Title. GOOD: bare ## Section Title.

5. Reference, Never Repeat

# BAD (repeating workflow in 3 places)
Phase 1: Detect → Gather → Execute
[same content in Phase 2 intro]
[same content in summary]

# GOOD
Workflow: detect→gather→execute (see Phase 1)

6. Abbreviations (Use Consistently)

{"abbrev_table":{"command":"cmd","skill":"sk","script":"sc","config":"cfg","dependency":"dep","required":"req","optional":"opt","description":"desc","implementation":"impl","reference":"ref"}}

7. Single Line Breaks Only

# BAD


## Section


Content here


# GOOD
## Section
Content here

8. Compress Examples

# BAD (42 words)
**Example Scenario:** When the user asks you to create
a new feature, you should first analyze the request,
then understand the requirements, and finally...

# GOOD (15 words)
User: "create feature X"
Agent: analyze→understand→design→implement

---

Anti-Patterns

Anti-pattern	Fix
Verbose explanations	Compress to dense bullets
Repeated concepts	Reference first occurrence
Decorative formatting	Remove ASCII art, excessive dashes
Full words	Use abbrev table
Inline examples (large blocks)	Move to separate file
Redundant headers	Merge related sections
Tables in resources	JSON for data, tables only in final output
JSON for instructions	Use markdown lists for do/dont/rules
Length caps	Never publish <N words / <N chars on agent-generated content; output length is governed by depth floors in add-doc-schemas

---

Validation Checklist

Before finalizing ANY resource:

[ ] JSON specs minified?
[ ] JSON for data, markdown lists for instructions?
[ ] Tables only in final output to user?
[ ] Paths use glob patterns?
[ ] No decorative formatting?
[ ] Abbreviations applied?
[ ] Single line breaks?
[ ] Examples compressed?
[ ] No repeated content?

---

Output length is NOT governed here. Numeric caps on agent-generated content (<N words, <N chars, ~N-N words) are prohibited per {{skill:add-doc-schemas/SKILL.md}}. Use depth floors and density.

---

Cross-references

• {{skill:add-doc-schemas/SKILL.md}} — authority on output length and doc structure (depth floors, density, validation gate, schemas by category). This skill covers compression patterns only; length is governed there.
• {{skill:add-claude-md-style/SKILL.md}} — CLAUDE.md generation rules
• {{doc:PRD0009}} — Documentation Context Engineering PRD
• {{doc:PRD0019}} — Documentation Standards Refactor (length-cap removal, schemas by category)