From 2a0bb4508567c68128423eebec15646b7bd84bd1 Mon Sep 17 00:00:00 2001
From: Amolith <amolith@secluded.site>
Date: Sun, 11 Jan 2026 11:11:39 -0700
Subject: [PATCH] docs(readme): add skill token stats section

Add detailed token statistics for each skill including name,
description, body, and references. Provides overall metadata usage
summary to help understand context window consumption.

Assisted-by: GLM 4.7 via Crush <crush@charm.land>
---
 README.md | 154 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 154 insertions(+)

diff --git a/README.md b/README.md
index 08263eca9ca1bddc11930d53a52c9dd5927388d5..54c59d6930c0b62a3c143aeb24d0b711dca9acc9 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,8 @@ agent capabilities through a standardised format.
 
 ## Available Skills
 
+Refer to [§ Skill stats](#skill-stats) for a detailed breakdown of each skill's token count, plus overall metadata usage.
+
 - [authoring-skills](skills/authoring-skills/SKILL.md): Creates
   well-structured Agent Skills following best practices. Use when
   writing new skills, reviewing existing skills, or when the user
@@ -140,3 +142,155 @@ complete example workflow.
 
 [amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
 [pr.pico.sh]: https://pr.pico.sh
+
+## Token stats
+
+Real token stats as reported by [Synthetic.new]'s [/messages/count_tokens] endpoint with [./skill-stats.go](./skill-stats.go).
+
+[Synthetic.new]: https://synthetic.new
+[/messages/count_tokens]: https://dev.synthetic.new/docs/anthropic/messages/count-tokens
+
+```
+=== authoring-skills ===
+
+Token breakdown:
+  Name:           20 tokens
+  Description:    86 tokens
+  Body:         2000 tokens (102 lines)
+  References:
+    checklist.md                               806 tokens
+    patterns.md                               2415 tokens
+    process.md                                 833 tokens
+    specification.md                          3890 tokens
+  ───────────────────────────────────────────────
+  Total:       10050 tokens
+
+=== creating-tasks-through-lunatask ===
+
+Token breakdown:
+  Name:           30 tokens
+  Description:   108 tokens
+  Body:         1927 tokens (88 lines)
+  References:
+    cli.md                                     589 tokens
+    handoff.md                                2769 tokens
+    installing-lune.md                         176 tokens
+  ───────────────────────────────────────────────
+  Total:        5599 tokens
+
+=== formatting-commits ===
+
+Token breakdown:
+  Name:           22 tokens
+  Description:    98 tokens
+  Body:          796 tokens (38 lines)
+  References:
+    installing-formatted-commit.md             296 tokens
+  ───────────────────────────────────────────────
+  Total:        1212 tokens
+
+=== frontend-accessibility ===
+
+Token breakdown:
+  Name:           20 tokens
+  Description:   140 tokens
+  Body:         2891 tokens (148 lines)
+  References:
+    antipatterns.md                           3638 tokens
+    patterns.md                               6233 tokens
+  ───────────────────────────────────────────────
+  Total:       12922 tokens
+
+=== handling-customer-data ===
+
+Token breakdown:
+  Name:           22 tokens
+  Description:   123 tokens
+  Body:         1983 tokens (107 lines)
+  ───────────────────────────────────────────────
+  Total:        2128 tokens
+
+=== invoking-subagents ===
+
+Token breakdown:
+  Name:           20 tokens
+  Description:   113 tokens
+  Body:          796 tokens (13 lines)
+  References:
+    installing-synu.md                         140 tokens
+  ───────────────────────────────────────────────
+  Total:        1069 tokens
+
+=== querying-documentation ===
+
+Token breakdown:
+  Name:           22 tokens
+  Description:   132 tokens
+  Body:          796 tokens (22 lines)
+  References:
+    dependencies.md                            108 tokens
+  ───────────────────────────────────────────────
+  Total:        1058 tokens
+
+=== resolving-secrets ===
+
+Token breakdown:
+  Name:           20 tokens
+  Description:   120 tokens
+  Body:          259 tokens (10 lines)
+  References:
+    installing-opx.md                          125 tokens
+  ───────────────────────────────────────────────
+  Total:         524 tokens
+
+=== resuming-work-through-lunatask ===
+
+Token breakdown:
+  Name:           30 tokens
+  Description:   113 tokens
+  Body:         1241 tokens (42 lines)
+  References:
+    cli.md                                     528 tokens
+    installing-lune.md                         176 tokens
+  ───────────────────────────────────────────────
+  Total:        2088 tokens
+
+=== scripting-with-go ===
+
+Token breakdown:
+  Name:           20 tokens
+  Description:   120 tokens
+  Body:         1968 tokens (138 lines)
+  ───────────────────────────────────────────────
+  Total:        2108 tokens
+
+=== writing-roc-lang ===
+
+Token breakdown:
+  Name:           22 tokens
+  Description:   142 tokens
+  Body:         1846 tokens (117 lines)
+  References:
+    builtins-llms.md                         67881 tokens
+    llms.md                                  11324 tokens
+    scripting.md                              1722 tokens
+  ───────────────────────────────────────────────
+  Total:       82937 tokens
+
+============================================================
+SUMMARY
+============================================================
+
+Skills: 11
+Metadata: 1543 tokens
+Combined bodies: 16503 tokens
+Overall: 121695 tokens
+Validation errors: 0
+
+Largest skills (by total tokens):
+  1. writing-roc-lang                         82937 tokens
+  2. frontend-accessibility                   12922 tokens
+  3. authoring-skills                         10050 tokens
+  4. creating-tasks-through-lunatask           5599 tokens
+  5. handling-customer-data                    2128 tokens
+```