markdown-token-optimizer
Analyzes markdown files for token efficiency. TRIGGERS: optimize markdown, reduce tokens, token count, token bloat, too many tokens, make concise, shrink file, file too large, optimize for AI, token efficiency, verbose markdown, reduce file size
83
78%
Does it follow best practices?
Impact
84%
1.37xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.github/skills/markdown-token-optimizer/SKILL.mdQuality
Discovery
72%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description has strong trigger term coverage and occupies a clear, distinctive niche around markdown token optimization. However, it lacks specificity about what concrete actions the skill performs beyond 'analyzes' and is missing an explicit 'Use when...' clause, which limits its completeness score.
Suggestions
Add specific concrete actions beyond 'analyzes', e.g., 'Identifies redundant formatting, suggests structural simplifications, removes unnecessary whitespace, and estimates token savings in markdown files.'
Add an explicit 'Use when...' clause, e.g., 'Use when the user wants to reduce token count in markdown files, optimize markdown for AI context windows, or diagnose token bloat.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (markdown files, token efficiency) and one action (analyzes), but doesn't list multiple specific concrete actions like 'remove redundant headings, compress tables, simplify formatting'. The description is light on what specific optimizations or analyses are performed. | 2 / 3 |
Completeness | The 'what' is present but thin ('analyzes markdown files for token efficiency'). The trigger terms implicitly serve as 'when' guidance, but there is no explicit 'Use when...' clause. Per the rubric, a missing explicit 'Use when...' clause caps completeness at 2. | 2 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms users would actually say: 'optimize markdown', 'reduce tokens', 'token count', 'too many tokens', 'make concise', 'shrink file', 'file too large', 'verbose markdown', 'reduce file size'. These cover many natural phrasings a user might employ. | 3 / 3 |
Distinctiveness Conflict Risk | The combination of 'markdown' + 'token efficiency/optimization' is a very specific niche. The trigger terms are well-targeted and unlikely to conflict with general markdown editing skills or general file optimization skills due to the token-specific focus. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured, concise skill that effectively uses progressive disclosure to keep the main file lean while pointing to detailed references. The workflow is clear and appropriately scoped. The main weakness is the lack of concrete output examples showing what the suggestions table and summary should look like, which would make the skill more actionable.
Suggestions
Add a brief example of the expected suggestions table format (e.g., a 2-row markdown table with location, issue, fix, savings columns)
Add a concrete example of the summary output format showing current/potential/savings numbers
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Very lean and efficient. Every section earns its place, no unnecessary explanations of what tokens are or how markdown works. The ~4 chars = 1 token heuristic is a useful non-obvious detail. | 3 / 3 |
Actionability | The workflow steps are clear but lack concrete examples of output format (e.g., what the suggestions table looks like, what the summary format looks like). No executable code or copy-paste ready examples are provided. | 2 / 3 |
Workflow Clarity | The 4-step workflow (Count → Scan → Suggest → Summary) is clearly sequenced and unambiguous. Since this is an analysis-only skill with a 'suggest only, no auto-modification' rule, destructive operation validation is not needed. | 3 / 3 |
Progressive Disclosure | Clean overview with well-signaled one-level-deep references to ANTI-PATTERNS.md and OPTIMIZATION-PATTERNS.md. Content is appropriately split between the main skill and reference files. | 3 / 3 |
Total | 11 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- microsoft/github-copilot-for-azure
- Commit
a46a937
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.