brainstorming

Socratic questioning protocol + user communication. MANDATORY for complex requests, new features, or unclear requirements. Includes progress reporting and error handling.

Quality

58%

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/brainstorming/SKILL.md

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 well-structured with actionable templates and a clear gated workflow, but it is padded with generic communication guidance Claude already knows and references a dynamic-questioning.md file that is missing from the bundle, leaving a broken navigation path.

Suggestions

Trim or remove the Progress Reporting, Error Handling, Completion Message, Communication Principles, and Anti-Patterns sections, which restate behavior Claude already knows.

Provide the missing references/dynamic-questioning.md file referenced on lines 52 and 91, or inline the essential question-generation principles so the skill is self-contained.

Add an explicit feedback loop for the case where the user's answers are still ambiguous (re-ask P0 questions) to strengthen workflow_clarity toward a 5.

Dimension	Reasoning	Score
Conciseness	The core Socratic/question-generation sections are tight and table-based, but several appended sections (progress reporting, error handling, completion messages, communication principles) restate general communication behavior Claude already knows.	3 / 5
Actionability	Provides concrete, copy-paste-ready templates (the mandatory question format, the 5-step STOP/CHECK/ASK/WAIT/SAVE process) and a clear question-generation procedure; the main gap is punting question banks to dynamic-questioning.md, which is not present in the bundle.	4 / 5
Workflow Clarity	The Socratic Gate is a clear numbered checklist with an explicit WAIT checkpoint before proceeding, and question generation is sequenced with priorities; this is not a destructive/batch operation so the validation cap does not apply, but there is no real feedback loop beyond waiting for a reply.	4 / 5
Progressive Disclosure	The body is well-organized with clear headers and signals its one external reference ('see: dynamic-questioning.md'), but no references/ bundle exists so that reference is a dead link, breaking actual navigation to the detailed material.	3 / 5
	Total	14 / 20 Passed

Description

53%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 answers both what and when with explicit trigger guidance, but is weakened by generic capability language, the absence of the natural keyword "brainstorm", and broad triggers that create overlap risk with general coding skills.

Suggestions

Add concrete actions in third person (e.g., 'Clarifies vague requirements through targeted questions before implementation') instead of abstract concepts.

Include the natural trigger term 'brainstorm' and synonyms like 'explore options' or 'clarify requirements' that users actually say.

Narrow the trigger conditions so they don't overlap with general implementation skills (e.g., 'Use when the request is ambiguous and needs scoping before any code is written').

Dimension	Reasoning	Score
Specificity	Names the domain ("Socratic questioning protocol + user communication") and a couple of capabilities ("progress reporting and error handling"), but these are generic concepts rather than concrete actions like 'extract text' or 'fill forms'.	2 / 5
Completeness	Clearly states both what ("Socratic questioning protocol + user communication") and when ("MANDATORY for complex requests, new features, or unclear requirements"), with explicit trigger guidance; the 'what' could be more concrete to reach a 5.	4 / 5
Trigger Term Quality	Has relevant triggers ("complex requests, new features, or unclear requirements") but omits the most natural phrase a user would say — "brainstorm" — and lacks synonyms or variations.	3 / 5
Distinctiveness Conflict Risk	The Socratic questioning niche is distinct, but triggers like "complex requests" and "new features" are broad and would overlap with many implementation/coding skills.	3 / 5
	Total	12 / 20 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: vudovn/ag-kit
Path: .agents/skills/brainstorming/SKILL.md
Commit: 211561c

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