grill-with-docs

A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.

Quality

53%

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

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

Quality

Content

57%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 extremely concise but underspecified: it delegates to two other skills without explaining how they combine or what the session produces. Conciseness is excellent, but actionability and workflow clarity suffer from the near-total lack of concrete guidance.

Suggestions

Spell out the orchestration: how /grilling and /domain-modeling interact, what inputs to seed the session with, and what outputs (ADR + glossary entries) to produce.

Add a short concrete workflow with a validation checkpoint, e.g. confirm the plan is sufficiently sharpened before writing the ADR and glossary entries.

Include a minimal example of the expected artifacts (an ADR stub and a glossary entry format) so the delegation is actionable rather than just directional.

Dimension	Reasoning	Score
Conciseness	The single line "Run a `/grilling` session, using the `/domain-modeling` skill." is maximally lean with no padding or over-explanation; every token is functional, so it earns the top conciseness score.	5 / 5
Actionability	It names two skills to invoke but gives only a high-level hint; the concrete steps for how to run the grilling session and how /domain-modeling is meant to be used are missing, so it falls at the minimal-guidance anchor.	2 / 5
Workflow Clarity	As a simple delegating skill the single action is mostly identifiable, but the relationship between /grilling and /domain-modeling is not explained and there are no checkpoints, so it sits at the middle anchor rather than the simple-skill 5.	3 / 5
Progressive Disclosure	There are no bundle files and no file references to navigate, and the body has no section structure; for a tiny skill this is acceptable but not well-organized enough to score above the midpoint.	3 / 5
	Total	13 / 20 Passed

Description

50%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 states what the skill does in third person with a couple of concrete actions, but omits any explicit "when to use it" trigger guidance and relies on terms that overlap with the skills it wraps. It sits at the midpoint across all dimensions.

Suggestions

Add an explicit trigger clause, e.g. "Use when the user wants to pressure-test, stress-test, or sharpen a plan or design before committing to it."

Broaden trigger coverage with natural synonyms users actually say ("refine my plan", "interview me about this design", "stress-test this approach", "draft an ADR").

Tighten the what/when pairing so the distinctiveness from /grilling and /domain-modeling is explicit, e.g. note that it combines grilling with doc generation rather than just running either skill.

Dimension	Reasoning	Score
Specificity	Phrases like "relentless interview to sharpen a plan or design" and "creates docs (ADR's and glossary) as we go" name the domain plus a couple of concrete actions, but coverage is not comprehensive enough for a 4.	3 / 5
Completeness	The "what" is clear, but there is no "Use when..." clause or equivalent trigger guidance, so per the judging guidelines completeness is capped at 3.	3 / 5
Trigger Term Quality	Terms such as "interview", "plan", "design", "ADR's", and "glossary" are relevant, but common natural variations a user would actually say (e.g. "refine", "pressure-test", "stress-test my design") are missing.	3 / 5
Distinctiveness Conflict Risk	The description carves a recognizable niche (interview + docs), but it overlaps conceptually with the /grilling and /domain-modeling skills it delegates to, so it is not yet clearly distinct.	3 / 5
	Total	12 / 20 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: coder/agent-tty
Path: .agents/skills/grill-with-docs/SKILL.md
Commit: ebff2c2

Reviewed: 4 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.