brainstorm

Dual-mode brainstorming pipeline. Auto mode: framework generation → parallel role analysis (spawn_agents_on_csv) → cross-role synthesis. Single role mode: individual role analysis. CSV-driven parallel coordination with NDJSON discovery board.

Quality

36%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Critical

Do not install without reviewing

Fix and improve this skill with Tessl

tessl review fix ./.codex/skills/brainstorm/SKILL.md

Quality

Content

55%

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

The skill is highly actionable with excellent workflow clarity — the pipeline phases are well-defined with clear sequencing, validation, and error handling. However, it severely suffers from being a monolithic document that inlines all implementation details (instruction templates, utility functions, CSV parsers) into a single file, making it both verbose and poorly structured for progressive disclosure. The content would benefit enormously from splitting into separate files for the role instruction template, utility functions, and phase-specific implementation details.

Suggestions

Extract the role instruction template (buildRoleInstruction), utility functions (parseCsv, updateMasterCsvRow), and synthesis agent instruction into separate bundle files (e.g., templates/role-instruction.md, lib/csv-utils.js) and reference them from SKILL.md

Reduce the main SKILL.md to an overview with the pipeline diagram, CSV schema, session structure, and brief phase descriptions — move all JavaScript implementation into referenced files

Remove the inline Available Roles table and CSV parser code from the main file — these are reference material that should live in supporting documents

Trim explanatory prose that Claude can infer (e.g., column descriptions for obvious fields like 'id', 'status', 'error') to reduce token consumption

Dimension	Reasoning	Score
Conciseness	The skill is extremely verbose at ~500+ lines with extensive inline code that could be in separate files. It includes implementation details (CSV parsers, utility functions, full instruction templates) that bloat the main skill file far beyond what's needed for an overview. Much of the JavaScript is boilerplate that Claude could generate from concise instructions.	1 / 3
Actionability	The skill provides fully executable JavaScript code for every phase, concrete CLI examples, specific function calls (spawn_agents_on_csv, spawn_agent), complete CSV schemas, and detailed instruction templates. Everything is copy-paste ready with real parameter values.	3 / 3
Workflow Clarity	The multi-phase pipeline is clearly sequenced with an excellent ASCII diagram, explicit phase transitions, validation checkpoints (user approval in Phase 2, status tracking in Phase 3), error recovery table, and compact protection directives for context compression. The feedback loop of role analysis → discovery board → synthesis is well-defined.	3 / 3
Progressive Disclosure	This is a monolithic wall of content with no bundle files to offload detail into. The role instruction template, utility functions, CSV parser, and phase implementation details should all be in separate referenced files. Everything is inlined into a single massive SKILL.md with no external references despite the content clearly warranting decomposition.	1 / 3
	Total	8 / 12 Passed

Description

17%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This description reads like an internal technical specification rather than a skill selection guide. It is heavy on implementation details (CSV-driven, NDJSON, spawn_agents_on_csv) that users would never use as search terms, while lacking a clear 'Use when...' clause and concrete, user-facing action descriptions. The core purpose—helping users brainstorm ideas through multi-role analysis—is obscured by jargon.

Suggestions

Add an explicit 'Use when...' clause with natural trigger terms like 'brainstorm', 'generate ideas', 'explore perspectives', 'ideation', 'creative thinking', 'multi-perspective analysis'.

Replace implementation jargon (spawn_agents_on_csv, NDJSON discovery board, CSV-driven parallel coordination) with user-facing descriptions of what the skill produces, e.g., 'Generates ideas from multiple expert perspectives and synthesizes them into actionable insights'.

Clarify the concrete outputs and use cases, e.g., 'Facilitates structured brainstorming by analyzing a topic from multiple expert roles and producing a synthesized summary of insights. Use when the user wants to explore an idea from different angles or needs diverse perspectives on a problem.'

Dimension	Reasoning	Score
Specificity	Names some actions like 'framework generation', 'parallel role analysis', 'cross-role synthesis', and 'individual role analysis', but these are described in jargon-heavy, abstract terms rather than concrete user-facing actions. It's unclear what tangible outputs are produced.	2 / 3
Completeness	While there is a partial 'what' (brainstorming pipeline with two modes), there is no 'when' clause or explicit trigger guidance. The description reads like an internal architecture spec rather than a skill selection guide.	1 / 3
Trigger Term Quality	The description uses highly technical internal jargon ('spawn_agents_on_csv', 'NDJSON discovery board', 'CSV-driven parallel coordination') that no user would naturally say. The word 'brainstorming' is the only natural trigger term, but it's buried among implementation details.	1 / 3
Distinctiveness Conflict Risk	The specific mention of 'dual-mode brainstorming pipeline' and technical terms like 'spawn_agents_on_csv' and 'NDJSON discovery board' make it somewhat distinctive, but the core concept of 'brainstorming' could overlap with other ideation or creative thinking skills.	2 / 3
	Total	6 / 12 Passed

Validation

72%

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 — 8 / 11 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (724 lines); consider splitting into references/ and linking	Warning
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	8 / 11 Passed

Repository: catlog22/Claude-Code-Workflow
Commit: 07491b0

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