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".

60

Quality

76%

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 ./.gemini/skills/grill-with-docs/SKILL.md

The canonical home for this skill is grill-with-docs in alirezarezvani/claude-skills

SKILL.md
Quality
Evals
Security

Quality

Content

63%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 lean, well-structured instruction skill with an explicit one-question-at-a-time interview protocol and a validation-looped wrapper workflow. Its decisive defect is that the entire supporting bundle it points to — three scripts, three references, and two format files — is absent, breaking both actionability and navigation in practice.

Suggestions

Ship the referenced bundle files: scripts/context_md_linter.py, scripts/adr_scanner.py, scripts/glossary_code_consistency.py, the three references/*.md files, CONTEXT-FORMAT.md, and ADR-FORMAT.md — every link in the body currently dangles.

Inline a minimal CONTEXT.md entry template (a 3-4 line example of one glossary term) so "Use the format in CONTEXT-FORMAT.md" is followable even before that file is opened.

State the expected output of each validator (e.g., "PASS/WARN/FAIL per rule" exit codes or summary lines) so the re-run feedback loops are interpretable without reading the script source.

DimensionReasoningScore

Conciseness

The core guidance earns its tokens: "Ask the questions one at a time, waiting for feedback", the three-part ADR criteria, and quoted challenge examples ("Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?") are all actionable, not explanatory filler. Minor trimmable padding: the provenance blockquote's "3 in-depth references each citing 7+ authoritative sources" and the author name-dropping in the reference list. Not 5 because of that meta-commentary; not 3 because nothing explains concepts Claude already knows.

4 / 5

Actionability

Commands are concrete and copy-paste-shaped ("scripts/context_md_linter.py CONTEXT.md", "glossary_code_consistency.py --context CONTEXT.md --code src/") and the interview rules include example dialogue, but the load-bearing artifacts are missing from the bundle: CONTEXT-FORMAT.md, ADR-FORMAT.md, and all three scripts are referenced yet absent, so "Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md)" cannot actually be followed. Not 4 because the gaps are key details, not minor; not 2 because the written guidance itself is precise and specific.

3 / 5

Workflow Clarity

The wrapper workflow is clearly sequenced (Pre-flight → During the session → Closing) with explicit validation checkpoints and feedback loops ("re-run adr_scanner.py to confirm numbering", "Final glossary_code_consistency.py run to confirm no new orphan terms"). Not 5 because the validators those checkpoints depend on are absent from the bundle, so the loops cannot actually execute as shipped; not 3 because sequence and checkpoints are explicit, not merely implied.

4 / 5

Progressive Disclosure

References are well-signaled and one level deep — a tool table with one-line roles, per-reference summaries ("why a glossary belongs in source control"), and inline links at point of use — but verification of the bundle shows none of the referenced files exist (no references/, scripts/, CONTEXT-FORMAT.md, or ADR-FORMAT.md), so every navigation path dead-ends. Not 4 because all links dangling is more than a minor organization gap; not 2 because the in-body structure is well designed and nothing that belongs in separate files is inlined.

3 / 5

Total

14

/

20

Passed

Description

80%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 cleanly and explicitly answers both what and when, in third person, anchored to concrete artifacts (CONTEXT.md, docs/adr/) with a literal invocation phrase. The main weakness is narrow trigger vocabulary — a user saying "challenge my plan", "interrogate my design", "glossary", or "ADR" would not match it.

Suggestions

Add natural trigger synonyms such as "challenge/interrogate a plan", "glossary", "ADR", or "domain language" so users who don't already use the word "grill" still match.

Consider mentioning the pre-flight validation capability (linting CONTEXT.md, scanning ADRs) to round out the action coverage.

DimensionReasoningScore

Specificity

"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" list several concrete actions anchored to specific artifacts. Not 5 because coverage has gaps (no mention of pre-flight linting or glossary↔code consistency checks); not 3 because more than 1-2 actions are named with concrete file targets.

4 / 5

Completeness

Explicitly answers what ("challenges a plan against ... recorded decisions (docs/adr/), and updates those files inline") and when ("Use when user wants to stress-test a plan against documented domain language, or mentions 'grill with docs'") with concrete trigger phrases, in third person. Not 4 because both what and when are fully explicit rather than merely present.

5 / 5

Trigger Term Quality

"stress-test a plan" and "grill with docs" are natural phrases users would say, but common variations are missing — "challenge/interrogate my plan", "glossary", "ADR", "ubiquitous language" are absent. Not 4 because keyword coverage is narrow for the niche; not 2 because it does include genuinely natural phrasing plus the literal invocation phrase.

3 / 5

Distinctiveness Conflict Risk

Anchoring to "CONTEXT.md" and "docs/adr/" plus the unique trigger "grill with docs" carves a clear niche with minimal conflict risk against generic planning or review skills. Not 4 because no closely related skill would realistically capture these triggers.

5 / 5

Total

17

/

20

Passed

Validation

87%

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

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 5 missing

Warning

referenced_paths_exist

Referenced path issues: 12 missing

Warning

Total

14

/

16

Passed

Repository

alirezarezvani/claude-skills

Path

.gemini/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.