CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

grill-with-docs

Docs-anchored grilling session — challenges a plan against the project's existing language (CONTEXT.md) and recorded decisions (docs/adr/), and updates those files inline as terminology and decisions crystallise. Use when user wants to stress-test a plan against documented domain language, or mentions "grill with docs".

62

Quality

78%

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 ./engineering/grill-with-docs/skills/grill-with-docs/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

70%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 an efficient, well-sequenced instruction set with genuinely strong validation feedback loops around CONTEXT.md and ADR edits. Its main defect is that the two format specifications the skill repeatedly tells the reader to use are missing from the bundle, which simultaneously weakens actionability and leaves two dangling references in an otherwise clean progressive-disclosure structure.

Suggestions

Add the missing CONTEXT-FORMAT.md and ADR-FORMAT.md to the skill bundle (or fix the links to their actual locations) so the 'Use the format in...' instructions are followable.

Alternatively, inline a minimal format sketch (a 3-5 line template for each) in SKILL.md so the core write tasks remain actionable even if the full format files are unavailable.

Verify the companion paths (../../agents/cs-grill-with-docs.md and ../../commands/cs-grill-with-docs.md) resolve in the installed layout, since a third broken path would further degrade navigation.

DimensionReasoningScore

Conciseness

The body is a lean instruction set ('Create files lazily — only when you have something to write', the three-criteria ADR gate, 'one question per turn') with no explanation of concepts Claude already knows; only minor non-operational tokens remain (the attribution blockquote, the version footer, and two ASCII directory trees), fitting anchor 4's 'efficient; minor instances that could be trimmed' rather than anchor 5's every-token-earns-its-place.

4 / 5

Actionability

It provides exact executable commands ('Run scripts/context_md_linter.py CONTEXT.md', 'glossary_code_consistency.py --context CONTEXT.md --code src/'), but both central write instructions point at files that do not exist in the bundle ('Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md)' and '[ADR-FORMAT.md](./ADR-FORMAT.md)'), leaving key details unavailable — anchor 3's 'concrete guidance but incomplete; missing key details' rather than anchor 4's minor gaps.

3 / 5

Workflow Clarity

The three-phase workflow (pre-flight validators, in-session rules with immediate edits, closing verification) has explicit validation checkpoints and feedback loops: 're-run context_md_linter.py if the edit is structural', 're-run adr_scanner.py to confirm numbering', and 'Final glossary_code_consistency.py run to confirm no new orphan terms were introduced' — matching anchor 5's clear sequence with explicit validation and error-recovery loops.

5 / 5

Progressive Disclosure

The references/ files (3 real, one level deep, each with a one-line role description) and the scripts table are well signaled, but two load-bearing referenced paths — ./CONTEXT-FORMAT.md and ./ADR-FORMAT.md — dangle (absent from the bundle), breaking navigation exactly where the skill's output formats live; this sits between anchor 3 and anchor 4, and the broken central references pull it down to 3.

3 / 5

Total

15

/

20

Passed

Description

78%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.

A strong description that clearly and explicitly states both what the skill does and when to use it, with natural trigger phrases and a well-delineated niche. It is held back from the top tier only by compressed capability coverage — two core actions with no mention of the interview loop or the validator tooling.

Suggestions

Enumerate one more concrete capability in the 'what' clause (e.g., mention the one-question-at-a-time interview loop or the CONTEXT.md/ADR pre-flight validators) to lift specificity from 1-2 actions toward several specific actions.

Add common trigger synonyms such as 'challenge my plan', 'ADR', or 'glossary' alongside 'stress-test a plan' to broaden natural keyword coverage.

DimensionReasoningScore

Specificity

The description names the domain precisely ('challenges a plan against the project's existing language (CONTEXT.md) and recorded decisions (docs/adr/)') and lists two concrete actions — challenge a plan against docs, update files inline — but coverage is not comprehensive (the interview loop, pre-flight validators, and scenario stress-testing are absent), matching anchor 3's '1-2 concrete actions, but not comprehensive' rather than anchor 4's several distinct actions.

3 / 5

Completeness

It explicitly answers both what ('challenges a plan against the project's existing language (CONTEXT.md) and recorded decisions (docs/adr/), and updates those files inline as terminology and decisions crystallise') and when ('Use when user wants to stress-test a plan against documented domain language, or mentions "grill with docs"') with concrete trigger phrases, matching anchor 5 exactly.

5 / 5

Trigger Term Quality

'stress-test a plan against documented domain language' and the literal 'grill with docs' are phrases a user would naturally say, complemented by file-specific terms (CONTEXT.md, docs/adr/); common variations like 'challenge my plan', 'ADR', or 'glossary' are missing, so it fits anchor 4's 'good keyword coverage; a few natural terms missing' rather than anchor 5's comprehensive synonym coverage.

4 / 5

Distinctiveness Conflict Risk

The docs-anchored grilling niche tied to CONTEXT.md and docs/adr/ artifacts is mostly distinct with specific triggers, but a generic 'review my plan' request could overlap with plain plan-review or ADR-writing skills, fitting anchor 4's 'mostly distinct; minor overlap risk' rather than anchor 5's minimal conflict risk.

4 / 5

Total

16

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 2 missing

Warning

Total

15

/

16

Passed

Repository

alirezarezvani/claude-skills

Path

engineering/grill-with-docs/skills/grill-with-docs/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.