cluster-documents

Automated content similarity and grouping analysis. Groups related documents by topic, purpose, or content similarity.

Quality

33%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/cluster-documents/SKILL.md

Quality

Discovery

32%

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 communicates the core capability of grouping documents by similarity but lacks explicit trigger guidance ('Use when...') and misses common user-facing synonyms. It is moderately specific but could easily overlap with other document analysis or classification skills.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to cluster, categorize, or find similar documents, or when detecting duplicate or related content.'

Include more natural trigger terms users would say, such as 'cluster', 'categorize', 'classify', 'deduplicate', 'organize', or 'find similar'.

List additional concrete actions beyond grouping, such as 'computes similarity scores, identifies duplicate content, generates topic clusters, and produces grouping summaries'.

Dimension	Reasoning	Score
Specificity	Names the domain (content similarity and grouping) and some actions (groups related documents by topic, purpose, or content similarity), but doesn't list multiple concrete specific actions beyond grouping.	2 / 3
Completeness	Describes what it does (groups related documents by similarity) but has no explicit 'Use when...' clause or trigger guidance, which per the rubric caps completeness at 2, and the 'when' is entirely missing, warranting a 1.	1 / 3
Trigger Term Quality	Includes some relevant keywords like 'content similarity', 'grouping', 'documents', 'topic', but misses common user-facing terms like 'cluster', 'categorize', 'classify', 'deduplicate', or 'organize'.	2 / 3
Distinctiveness Conflict Risk	Somewhat specific to content similarity and grouping, but 'documents' and 'topic' are broad enough to overlap with document analysis, search, or classification skills.	2 / 3
	Total	7 / 12 Passed

Implementation

35%

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

This skill reads as a high-level conceptual outline rather than actionable guidance. It describes what should happen at each step (normalize text, generate embeddings, apply clustering) without providing any executable code, specific library calls, concrete examples, or output schemas. Claude would need to independently figure out nearly all implementation details, making this skill minimally useful as written.

Suggestions

Add executable Python code examples for each workflow step using specific libraries (e.g., scikit-learn for TF-IDF/KMeans, or sentence-transformers for embeddings), so Claude can copy-paste and adapt rather than guess at implementation.

Provide a concrete example of the CLUSTERING_REPORT output as a JSON schema or sample, so the expected output format is unambiguous.

Add validation checkpoints—e.g., checking silhouette scores after clustering, verifying document count matches input, handling empty/unreadable files—to make the workflow robust.

Include a minimal end-to-end example with sample input (e.g., 3-4 short documents) and expected output to ground the abstract workflow in something concrete.

Dimension	Reasoning	Score
Conciseness	Mostly efficient but includes some unnecessary framing ('This skill helps organize large collections, identify redundancies, and discover relationships') and a Quick Reference section that restates what's already clear. Some filler could be trimmed.	2 / 3
Actionability	The skill is entirely abstract and descriptive—no executable code, no concrete commands, no specific library usage, no example inputs or outputs. Instructions like 'Generate embeddings or TF-IDF vectors' and 'Apply clustering algorithms (e.g., K-Means, DBSCAN)' are vague directions, not actionable guidance Claude can execute.	1 / 3
Workflow Clarity	Steps are listed in a logical sequence, but there are no validation checkpoints, no error handling, no feedback loops for when clustering results are poor, and no concrete criteria for evaluating cluster quality. The workflow reads more like a high-level outline than an operational procedure.	2 / 3
Progressive Disclosure	The content has reasonable section structure with clear headings, but everything is inline with no references to external files for detailed techniques, examples, or API references. The output schema is described loosely rather than with a concrete JSON schema or example.	2 / 3
	Total	7 / 12 Passed

Validation

90%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: dandye/ai-runbooks
Commit: 086cbf6

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.