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
79
72%
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 distinctive niche, making it easy for Claude to identify when to use it. However, it lacks specificity about what concrete actions the skill performs beyond 'analyzes', and the 'when' guidance is implicit through a trigger list rather than an explicit 'Use when...' clause.
Suggestions
Add specific concrete actions beyond 'analyzes', e.g., 'Identifies redundant formatting, simplifies verbose sections, removes unnecessary whitespace, and suggests structural changes to reduce token count in markdown files.'
Add an explicit 'Use when...' clause to complement the trigger list, e.g., 'Use when a user wants to reduce the token footprint of markdown files for AI consumption or when files are too large for context windows.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (markdown files, token efficiency) and one action (analyzes), but doesn't list multiple concrete actions like 'remove redundant headings, simplify tables, compress verbose sections'. The description is light on what specific optimizations or outputs are produced. | 2 / 3 |
Completeness | The 'what' is present but thin ('analyzes markdown files for token efficiency'). The 'when' is provided via the TRIGGERS list, but there is no explicit 'Use when...' clause that contextualizes when Claude should select this skill. The triggers serve as implicit guidance but don't form a clear 'when' statement. | 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 are highly natural and varied. | 3 / 3 |
Distinctiveness Conflict Risk | This skill occupies a clear niche — markdown token optimization — that is unlikely to conflict with other skills. The combination of 'markdown' + 'token efficiency' is highly distinctive, and the trigger terms reinforce this specific domain. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
72%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. Its main weaknesses are the lack of concrete output examples (what does the suggestions table look like?) and missing validation/feedback steps in the workflow. Adding a brief example of expected output and a verification step would significantly improve actionability and workflow clarity.
Suggestions
Add a brief concrete example showing what the suggestions table output should look like (e.g., a 2-3 row markdown table with location, issue, fix, and savings columns).
Add a verification step to the workflow, such as re-counting tokens after suggested optimizations to confirm actual savings match estimates.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Very lean and efficient. Every section is tightly written with no unnecessary explanation. The workflow is compressed into a clear 4-step numbered list. No concepts are over-explained. | 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 should be). The ~4 chars = 1 token heuristic is concrete, but there's no example of an actual analysis being performed. | 2 / 3 |
Workflow Clarity | The 4-step workflow is clearly sequenced and easy to follow, but there are no validation checkpoints or feedback loops. For instance, there's no step to verify suggestions maintain clarity, or to re-count after optimization to confirm savings. | 2 / 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, with references listed both inline and in a dedicated section. | 3 / 3 |
Total | 10 / 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
771a666
- 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.