grill-with-docs

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

Quality

27%

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

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

14%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill body is essentially empty—a single line that delegates entirely to other skills without providing any of its own content. For a skill described as conducting a relentless interview that produces ADRs and glossary documents, there should be substantial guidance on interview structure, question strategies, document templates, and validation steps. As written, it provides no actionable value.

Suggestions

Add a concrete workflow describing the phases of the grilling session (e.g., initial context gathering, deep questioning, challenge assumptions, document decisions) with explicit steps and validation checkpoints.

Include specific examples of the types of questions to ask, what constitutes a satisfactory answer, and when to push back versus accept an answer.

Define the expected output artifacts (ADR format/template, glossary entry format) with concrete examples so Claude knows exactly what to produce.

Explain the relationship to `/domain-modeling` and `/grilling`—what each contributes and how this skill orchestrates them—rather than just referencing them without context.

Dimension	Reasoning	Score
Conciseness	The content is extremely brief (one line), which is lean, but it's so terse that it provides no actual value—it's essentially a redirect with no substance of its own. It doesn't waste tokens on things Claude knows, but it also doesn't contribute any meaningful tokens.	2 / 3
Actionability	The content provides no concrete guidance whatsoever—no steps, no examples, no commands, no structure for how to conduct a 'grilling' session. It merely delegates to another skill without any actionable instructions.	1 / 3
Workflow Clarity	There is no workflow described at all. For a skill described as 'a relentless interview to sharpen a plan or design' that also 'creates docs (ADRs and glossary),' there should be clear steps, interview phases, validation checkpoints, and document creation steps. None are present.	1 / 3
Progressive Disclosure	The content references `/grilling` and `/domain-modeling` skills but provides no context, no overview, and no navigation structure. There are no bundle files to support it. It's a bare redirect with no progressive disclosure structure.	1 / 3
	Total	5 / 12 Passed

Description

40%Scale 1-3

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 conveys a general sense of the skill's purpose—an interactive interview process that produces ADRs and glossary entries—but lacks concrete specificity about what actions are performed and when the skill should be selected. The informal tone ('relentless') and missing 'Use when...' clause weaken its effectiveness as a skill selector among many options.

Suggestions

Add an explicit 'Use when...' clause with trigger scenarios, e.g., 'Use when the user wants to stress-test a design, review architecture decisions, or needs help creating ADRs.'

List specific concrete actions the skill performs, e.g., 'Asks probing questions about design trade-offs, identifies gaps in requirements, generates Architecture Decision Records (ADRs), and maintains a project glossary.'

Include natural trigger terms users might say, such as 'architecture decision record', 'design review', 'challenge my plan', 'document decisions', 'technical glossary'.

Dimension	Reasoning	Score
Specificity	The description uses vague language like 'sharpen a plan or design' and 'creates docs' without specifying concrete actions. 'ADR's and glossary' are mentioned but the core capabilities (what kind of interview, what kind of sharpening) remain abstract.	1 / 3
Completeness	The 'what' is partially addressed (interview process that creates ADRs and glossary), but there is no explicit 'Use when...' clause or equivalent trigger guidance. The 'when' is only vaguely implied by the nature of the activity.	2 / 3
Trigger Term Quality	Contains some relevant keywords like 'interview', 'plan', 'design', 'ADR', and 'glossary' that users might mention, but misses common variations and natural phrases users would say (e.g., 'architecture decision record', 'design review', 'requirements gathering', 'challenge my design').	2 / 3
Distinctiveness Conflict Risk	The combination of 'interview' + 'ADR' + 'glossary' provides some distinctiveness, but 'plan or design' is broad enough to overlap with general planning, architecture, or documentation skills. The 'relentless interview' framing is somewhat unique but not clearly scoped.	2 / 3
	Total	7 / 12 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

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

Reviewed: 1 day 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.