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

Quality

84%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

—

The risk profile of this skill

Quality

Content

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

A well-structured, actionable body with a strong validated workflow and sensible progressive disclosure into references and scripts. The main weakness is two dangling format-file references (CONTEXT-FORMAT.md, ADR-FORMAT.md) that are cited but missing from the bundle.

Suggestions

Add the missing CONTEXT-FORMAT.md and ADR-FORMAT.md files to the bundle (or inline a minimal term/ADR template) so the "Use the format in…" instructions are resolvable.

Trim the attribution blockquote and the parenthetical citation-author lists in the References section to recover token budget without losing the licensing/attribution signal.

Show one short inline example of a CONTEXT.md term entry and one ADR stub so the format is actionable even before consulting the referenced files.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean and directive (XML-tagged sections, terse rules, a one-line tool table), assuming Claude's competence; minor trimmable padding exists in the long attribution blockquote and the parenthetical author lists in the References section.	4 / 5
Actionability	Gives concrete, copy-pasteable script invocations (e.g. `scripts/context_md_linter.py CONTEXT.md`) and explicit ADR criteria, but the inline links to [CONTEXT-FORMAT.md] and [ADR-FORMAT.md] point at files absent from the bundle, leaving the exact entry formats unspecified.	4 / 5
Workflow Clarity	A clearly sequenced Pre-flight / During-session / Closing workflow with explicit validation feedback loops ("re-run context_md_linter.py if the edit is structural", "re-run adr_scanner.py to confirm numbering", final consistency run) covering error recovery.	5 / 5
Progressive Disclosure	Good structure with well-signaled one-level-deep links to the three real references/*.md files and the scripts, but the body also references CONTEXT-FORMAT.md and ADR-FORMAT.md that do not exist in the bundle, a real navigation gap.	4 / 5
	Total	17 / 20 Passed

Description

87%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, third-person description that pairs concrete scoped actions with an explicit, naturally-phrased trigger clause. It clearly answers both what the skill does and when to invoke it with minimal conflict risk.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "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" — giving specific, scoped behavior rather than generic verbs.	4 / 5
Completeness	Explicitly answers both what (docs-anchored grilling that challenges a plan against CONTEXT.md/ADRs and updates them inline) and when ("Use when user wants to stress-test a plan against documented domain language, or mentions 'grill with docs'") with concrete triggers.	5 / 5
Trigger Term Quality	Natural trigger phrases are present ("stress-test a plan", "grill with docs") and the literal "mentions 'grill with docs'" is exactly what a user would say; coverage is good though a few synonymous phrasings are absent.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (docs-anchored grilling tied to CONTEXT.md + docs/adr/) with a distinctive literal trigger ("grill with docs"), making conflict with unrelated skills minimal.	5 / 5
	Total	18 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
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
Commit: 19392f7

Reviewed: ~6 hours 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.