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 distinct niche, but falls short on specificity of capabilities (only 'analyzes' is stated as an action) and lacks an explicit 'Use when...' clause. Adding concrete actions (e.g., 'removes redundant formatting, suggests concise alternatives, estimates token savings') and a formal 'Use when' statement would significantly improve it.
Suggestions
Add specific concrete actions beyond 'analyzes', such as 'identifies redundant formatting, suggests concise alternatives, removes unnecessary whitespace, estimates token counts and savings'.
Add an explicit 'Use when...' clause, e.g., 'Use when the user wants to reduce token usage in markdown files or mentions token bloat, file size concerns, or AI context optimization.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (markdown files, token efficiency) and one action (analyzes), but doesn't list multiple specific concrete actions like 'removes redundant formatting, shortens headings, consolidates sections'. | 2 / 3 |
Completeness | The 'what' is present but thin ('analyzes markdown files for token efficiency'). The TRIGGERS list serves as implicit 'when' guidance but there is no explicit 'Use when...' clause that clearly states when Claude should select this skill. | 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 cover many variations. | 3 / 3 |
Distinctiveness Conflict Risk | The combination of markdown + token efficiency is a very clear niche. The trigger terms are specific enough to avoid conflicts with general markdown editing skills or general file optimization skills. | 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 '5. **Verify** - Re-count tokens after suggested changes to confirm savings target met' to create a feedback loop.
| 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
915f809
- 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.