grill-with-docs

Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.

Quality

76%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/agents/reidbaker-agent/skills/grill-with-docs/SKILL.md

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

Quality

Content

75%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-written, concise instruction skill with genuinely concrete challenge dialogue, decision criteria, and file-handling rules. Its one significant defect is broken progressive disclosure: both linked format files are absent from the bundle, which undercuts the update-documentation half of the skill.

Suggestions

Create the referenced CONTEXT-FORMAT.md and ADR-FORMAT.md files (or inline the formats), since the skill currently points to files that do not exist.

Add a brief note on what to do when the user's answer conflicts with code or a prior ADR during the session (e.g., record the superseded decision).

Clarify how many questions or how deep the design-tree walk should go before concluding the session.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's competence: no explanation of what ADRs or glossaries are, no padding. The ASCII file-structure diagrams earn their tokens by making the lazy-creation rules concrete. Every section carries actionable instructions.	5 / 5
Actionability	Mostly concrete, executable guidance: verbatim challenge phrasings ("Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"), a crisp three-condition test for offering ADRs, and lazy file-creation rules. The gap is that the two format references (CONTEXT-FORMAT.md, ADR-FORMAT.md) point to files that do not exist in the bundle, so the "use the format in" instructions cannot actually be followed.	4 / 5
Workflow Clarity	The session flow is well sequenced: interview one question at a time, wait for feedback before continuing, provide a recommended answer per question, explore the codebase instead of asking when possible, then resolve terminology inline. The question-answer-wait loop is an explicit checkpoint pattern, though there is no guidance on how to verify a CONTEXT.md update landed correctly or what to do on conflicting answers.	4 / 5
Progressive Disclosure	The body links to [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md) and [ADR-FORMAT.md](./ADR-FORMAT.md), but neither file exists in the skill directory, and there are no references/, scripts/, or assets/ directories at all. The two most detail-heavy parts of the skill (the documentation formats) are deferred to files that are missing, leaving dangling references.	2 / 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 with explicit what and when clauses, concrete actions, and relevant domain-specific triggers. The main deductions are the second-person "your plan" phrasing (voice penalty on specificity) and trigger coverage that misses a few common synonyms.

Suggestions

Rewrite in third person: "Challenges a plan against the existing domain model..." instead of "challenges your plan".

Add common trigger variations such as "design review", "question my plan", or "challenge my design decisions".

Mention the interview format (one question at a time with recommended answers) as a concrete capability users would want to find.

Dimension	Reasoning	Score
Specificity	The description lists three concrete actions ("challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline"), which is solidly at the 3-4 anchor boundary, but the second-person phrasing "challenges your plan" triggers the rubric's voice penalty, capping it at 3.	3 / 5
Completeness	Both parts are explicit: the "what" is stated concretely (challenge plan, sharpen terminology, update CONTEXT.md/ADRs inline) and the "when" is a explicit trigger clause — "Use when user wants to stress-test a plan against their project's language and documented decisions."	5 / 5
Trigger Term Quality	Good natural trigger coverage: "stress-test a plan", "plan", "domain model", "terminology", "CONTEXT.md", "ADRs", "documented decisions" are phrases a user would plausibly say. Missing common variations like "design review", "question my plan", or "validate my design", so it does not reach comprehensive coverage.	4 / 5
Distinctiveness Conflict Risk	The DDD-flavored niche (domain model, glossary, ADRs, CONTEXT.md) is fairly distinctive with targeted triggers, but it could still overlap with general plan-review or brainstorming skills for a user who says "review my plan" without the documentation angle.	4 / 5
	Total	16 / 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: flutter/agent-plugins
Path: .agents/agents/reidbaker-agent/skills/grill-with-docs/SKILL.md
Commit: 8da8c54

Reviewed: 5 days 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.