ai-md
Convert human-written CLAUDE.md into AI-native structured-label format. Battle-tested across 4 models. Same rules, fewer tokens, higher compliance.
42
30%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Risky
Do not use without reviewing
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/ai-md/SKILL.mdQuality
Discovery
32%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 identifies a specific artifact (CLAUDE.md) and a conversion target (structured-label format), which gives it some distinctiveness. However, it lacks an explicit 'Use when...' clause, includes marketing language ('battle-tested', 'higher compliance') that doesn't aid skill selection, and misses natural trigger terms users would actually say when needing this functionality.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user wants to reformat, optimize, or compress their CLAUDE.md file, or mentions reducing token usage in system instructions.'
Replace marketing fluff ('battle-tested across 4 models', 'higher compliance') with concrete actions like 'Parses human-written rules, converts prose to labeled directives, and reduces token count while preserving instruction semantics.'
Include natural trigger term variations such as 'reformat instructions', 'optimize CLAUDE.md', 'compress system prompt', 'reduce tokens' to improve matching.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | It names the domain (CLAUDE.md conversion) and one action (convert to structured-label format), but doesn't list multiple concrete actions. The phrases 'battle-tested across 4 models' and 'fewer tokens, higher compliance' are marketing fluff rather than specific capabilities. | 2 / 3 |
Completeness | It partially answers 'what' (convert CLAUDE.md to structured-label format) but has no explicit 'when' clause or trigger guidance. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and the 'what' itself is also somewhat vague, so this scores a 1. | 1 / 3 |
Trigger Term Quality | Includes 'CLAUDE.md' and 'structured-label format' which are relevant terms, but misses natural variations users might say like 'reformat instructions', 'optimize system prompt', 'compress CLAUDE.md', or 'token reduction'. The term 'AI-native' is jargon that users are unlikely to use. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of 'CLAUDE.md' and 'structured-label format' provides some specificity, but it could overlap with other skills related to formatting, prompt optimization, or markdown conversion. The niche is somewhat clear but not sharply delineated. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill contains genuinely valuable methodology for converting prose instructions to structured AI-native format, with strong concrete examples of before/after transformations. However, it massively violates its own core principle ('What Not Why') by spending hundreds of tokens explaining attention mechanisms, semantic anchoring theory, and justifying why the approach works — all content meant to convince humans, not instruct an AI. The result is an ironic anti-pattern: a skill about token efficiency that is itself extremely token-inefficient.
Suggestions
Cut the entire 'Why It Works' section (Mechanisms 1-3) and the 'Real-World Results' section — these explain WHY to humans but add no actionable guidance for Claude. Move to a separate THEORY.md if desired.
Extract the label vocabulary table, anti-patterns table, and special techniques into separate reference files (e.g., LABELS.md, ANTI-PATTERNS.md, TECHNIQUES.md) and link from the main skill with one-line descriptions.
Reduce the conversion process to a concise checklist with one example per phase instead of multiple extended examples — the current Phase 2 alone has 3 separate code blocks showing the same concept.
Add an explicit validation checkpoint after the DISTILL phase: what does Claude do if the user reports the converted format performs worse? Currently the feedback loop is 'revert' but there's no iterative fix-and-retry guidance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Extensively explains HOW LLMs process attention, WHY labels work, and the theory behind the methodology — all things Claude doesn't need explained. The 'Why It Works' section alone is pure explanatory prose that violates the skill's own 'What Not Why' principle. Much of this is educational content for humans, not actionable instructions for an AI. | 1 / 3 |
Actionability | The conversion phases (1-6) provide a structured process with concrete examples of input→output transformations, and the template is copy-paste ready. However, much of the 'actionable' content is mixed with lengthy explanations, the bash script uses placeholder variables without real implementation, and the multi-model testing protocol describes a process Claude can't fully execute (running tests on other models). | 2 / 3 |
Workflow Clarity | The six-phase conversion process (UNDERSTAND→DECOMPOSE→LABEL→STRUCTURE→RESOLVE→TEST) is clearly sequenced, and the two-stage workflow (PREVIEW→DISTILL) includes a backup step. However, validation checkpoints are weak — Phase 6 testing requires 2+ external models which Claude cannot orchestrate, and there's no explicit feedback loop for what to do if the conversion itself produces invalid output or the user rejects the preview. | 2 / 3 |
Progressive Disclosure | This is a monolithic wall of text with no references to external files. All content — theory, techniques, templates, anti-patterns, results — is inlined in a single massive document. The 'Special Techniques' section, the full label vocabulary table, the anti-patterns table, and the real-world results could all be separate reference files, dramatically reducing the main skill's token footprint. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (524 lines); consider splitting into references/ and linking | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Repository
- sickn33/antigravity-awesome-skills
- Commit
1a9f5ac
- 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.