CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

md-context-writer

Write, audit and fix CLAUDE.md, AGENTS.md and .claude/rules from facts in your repository, with a linter that checks them against the code. Use when: Create a CLAUDE.md or AGENTS.md built on the real build, test and lint commands; Audit an existing instruction file for stale commands, moved paths and secrets; Split a long CLAUDE.md into path-scoped .claude/rules that load only when needed.

Quality

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/md-context-writer/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

38%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a well-written promotional README for the skill rather than an operational SKILL.md: sections are clear and the example transcript is illustrative, but the two scripts, writing guide, template, and example file it instructs the agent to use are not shipped in the bundle, leaving no executable path. Rewriting user instruction files also deserves an explicit diff/approval checkpoint beyond a FAQ mention.

Suggestions

Ship the actual bundle (repo_facts.py, lint_claude_md.py, the writing guide, template, and example file) in scripts/ and references/, and reference them with explicit paths and invocation syntax (e.g. `python scripts/repo_facts.py` with expected output), so the guidance is executable rather than descriptive.

Restructure 'The workflow' into numbered steps with a validation checkpoint at each phase (run repo_facts.py → verify commands → ask ≤5 questions → draft → run linter → fix and re-lint until 0 errors), and move the safety behavior (show a diff with reasons, never drop content silently) into that workflow instead of a FAQ.

Remove the promotional padding (the Nex AI callouts, paid-catalog footer, 'Tested on... 19 automated tests', and the FAQ that restates the description) to cut the body to the operational content, and trim the 40-line example transcript to the linter output plus a short before/after table.

DimensionReasoningScore

Conciseness

The operational core ("What it does", "Two scripts", "The workflow", "Known limitations") is tight and free of concept explanations Claude already knows, but roughly half the body is non-operational padding: "Free skill by Nex AI... This file is the public guide", "Built by Nex AI, nex-ai.be", a footer advertising a paid catalog, and a FAQ that restates the description. This fits 'mostly efficient but includes some unnecessary explanation or could be tightened'; it does not reach the 2 anchor's level of pervasive padding since the technical sections themselves are lean.

3 / 5

Actionability

Guidance stays at the hint level: "repo_facts.py reports what the repo actually contains", "Collect facts, verify the commands, ask only what files cannot answer (at most five questions)" — no invocation syntax, arguments, or usage steps for either script, and the scripts themselves are explicitly "not in this folder" ("Scripts, extension source, and templates from the original package are not in this folder"), so the one shown command (`python lint_claude_md.py`) cannot actually be executed. This matches the score-2 anchor (high-level hints missing the specific steps to execute) and is well below the 3 anchor, where partial but genuinely executable guidance exists.

2 / 5

Workflow Clarity

The workflow exists as a single prose sentence — "Collect facts, verify the commands, ask only what files cannot answer (at most five questions), write under 200 lines, put area-specific rules in path-scoped .claude/rules/, lint until clean" — so a sequence is discernible and a feedback loop ("lint until clean") is implied, but steps are unnumbered, checkpoints are implicit, and no per-step commands are given. It fits the score-3 anchor ('sequence present but checkpoints missing or implicit') rather than 4, which requires explicit per-step commands like `python scripts/unpack.py input.docx`.

3 / 5

Progressive Disclosure

No bundle exists (no references/, scripts/, or assets/ directories), yet the body points to materials that are absent: repo_facts.py, lint_claude_md.py, "a writing guide with before/after examples, a template, and a complete example file" — and even admits "Scripts, extension source, and templates from the original package are not in this folder". Navigation to the skill's actual detailed content is broken, matching the score-2 anchor (references buried/unusable, content that belongs in separate files is not actually provided); it avoids a 1 only because the body itself is well-sectioned and the missing files are one level deep, not nested.

2 / 5

Total

10

/

20

Passed

Description

92%Weight 40%Scale 1-5

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 is a strong example: third-person, concrete, names its target files, and includes an explicit multi-clause 'Use when:' trigger list. The only gap is modest synonym coverage (e.g. 'project instructions', 'rules') that would push trigger-term quality to the top anchor.

DimensionReasoningScore

Specificity

The description lists multiple concrete actions ("Write, audit and fix CLAUDE.md, AGENTS.md and .claude/rules", "a linter that checks them against the code") tied to specific artifacts and grounded in "facts in your repository", giving comprehensive coverage of the skill's capabilities. It clearly exceeds the score-4 anchor ("several specific actions; minor gaps") since the linter's purpose, the source of truth (repo facts), and all target file types are named.

5 / 5

Completeness

It explicitly answers both questions: the 'what' is "Write, audit and fix CLAUDE.md, AGENTS.md and .claude/rules from facts in your repository, with a linter", and the 'when' is an explicit "Use when:" clause with three concrete trigger scenarios (create, audit, split). This matches the score-5 anchor with concrete trigger phrases, and is clearly above the score-4 anchor where the 'when' is generic.

5 / 5

Trigger Term Quality

Strong natural keywords: "CLAUDE.md", "AGENTS.md", ".claude/rules", "stale commands", "moved paths and secrets", "path-scoped" — phrases users would plausibly say when needing this skill. A few natural variations are missing (e.g. "project instructions", "rules files", "context file", "init"), so it sits between the 4 and 5 anchors but noticeably above the midpoint.

4 / 5

Distinctiveness Conflict Risk

It occupies a clear niche — generating and linting agent instruction files — with distinct triggers ("stale commands, moved paths and secrets", "split a long CLAUDE.md") that no generic documentation or linting skill would claim. Overlap risk is minimal (at most with a generic /init-style skill, which its own body differentiates).

5 / 5

Total

19

/

20

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

NexaiGuy/nex-ai-skills

Path

skills/md-context-writer/SKILL.md

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.