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

1.37x

Quality

78%

Does it follow best practices?

Impact

84%

1.37x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Fix and improve this skill with Tessl

tessl review fix ./.github/skills/markdown-token-optimizer/SKILL.md

Quality

Content

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 efficiently communicates a clear workflow for markdown token optimization. Its main weakness is the lack of concrete examples—a sample input/output showing what the suggestion table or summary looks like would significantly improve actionability. The progressive disclosure is well-designed in principle, though the referenced files weren't available to verify.

Suggestions

Include a small before/after example of an optimization to make the guidance more concrete and copy-paste ready.

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 list with minimal words. No concepts are over-explained.	3 / 3
Actionability	The workflow steps are clear but lack concrete examples. There's no sample output table, no example of what a suggestion looks like, and the token estimation formula (~4 chars = 1 token) is a rough heuristic without executable code or a concrete worked example.	2 / 3
Workflow Clarity	The 4-step workflow (Count → Scan → Suggest → Summary) is clearly sequenced and unambiguous. The constraint 'suggest only (no auto-modification)' acts as a safety boundary. For this non-destructive analysis task, explicit validation checkpoints aren't necessary.	3 / 3
Progressive Disclosure	The SKILL.md is a concise overview with well-signaled one-level-deep references to ANTI-PATTERNS.md and OPTIMIZATION-PATTERNS.md. References are listed both inline in the workflow and in a dedicated References section. However, no bundle files were provided to verify the referenced files exist.	3 / 3
	Total	11 / 12 Passed

Description

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, making it easy for Claude to identify when to use it. However, it lacks specificity about what concrete actions the skill performs (e.g., what optimizations it applies) and would benefit from an explicit 'Use when...' clause rather than relying solely on a TRIGGERS list.

Suggestions

Add specific concrete actions the skill performs, e.g., 'Removes redundant formatting, compresses verbose sections, identifies token-heavy patterns, and suggests concise alternatives in markdown files.'

Convert the TRIGGERS list into an explicit 'Use when...' clause, e.g., 'Use when the user wants to optimize markdown for token efficiency, reduce file size, or mentions token bloat or verbose markdown.'

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 formatting, compress tables, simplify headers'. The description is somewhat vague about what specific optimizations are performed.	2 / 3
Completeness	The 'what' is present but thin ('analyzes markdown files for token efficiency'). While the TRIGGERS list implicitly serves as a 'when' clause, there is no explicit 'Use when...' statement that clearly answers when Claude should select this skill. 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'. These cover many natural variations of how users would phrase this need.	3 / 3
Distinctiveness Conflict Risk	This occupies a very clear niche — token optimization for markdown files. The specific trigger terms around tokens, conciseness, and file size for markdown create a distinct profile unlikely to conflict with general markdown editing or general file optimization skills.	3 / 3
	Total	10 / 12 Passed

Validation

100%

Warnings & errors only

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: d4563f6

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

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.