beads

Use beads (bd) for persistent task tracking in coding projects. A git-backed issue tracker designed for AI agents with dependency graphs, hierarchical tasks, and multi-agent coordination.

Quality

67%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./beads/SKILL.md

Quality

Content

77%

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

This is a solid, actionable skill with clear workflows and executable commands throughout. Its main weakness is moderate verbosity — the Quick Reference section duplicates earlier content, and some sections (MCP server, git hooks) could be offloaded to separate files. The session workflow with explicit validation and the clear 'DO/DO NOT' rules are particular strengths.

Suggestions

Remove or significantly trim the 'Quick Reference' section at the end, as it duplicates commands already covered in 'Essential Commands' and 'Session Workflow'.

Consider moving secondary topics (MCP Server, Git Hooks, Dependency Types, Merge Conflicts) to separate reference files and linking to them from the main skill to improve progressive disclosure and reduce token usage.

Dimension	Reasoning	Score
Conciseness	The skill is mostly efficient but includes some unnecessary content. The 'Quick Reference' section at the end largely duplicates commands already covered. The MCP Server section and some explanatory text ('This enables bd doctor to detect orphaned issues') add minor bloat. However, it generally avoids explaining concepts Claude already knows.	2 / 3
Actionability	The skill provides fully executable commands throughout, with concrete examples including specific flags, IDs, and realistic task titles. The command table, workflow steps, and code blocks are all copy-paste ready with no pseudocode.	3 / 3
Workflow Clarity	The session workflow is clearly sequenced with explicit steps for starting, during, and ending sessions. The 'Land the Plane' section includes a numbered checklist with a verification step (git status check) and a CRITICAL callout about pushing. The merge conflict section includes a clear recovery workflow.	3 / 3
Progressive Disclosure	The content is well-structured with clear headers and logical sections, but it's a fairly long monolithic file with no references to external files for advanced topics. Dependency types, merge conflicts, git hooks, and MCP server details could be split into separate reference files to keep the main skill leaner.	2 / 3
	Total	10 / 12 Passed

Description

57%

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 identifies a clear niche tool (beads/bd) for task tracking with distinctive features, but falls short on specifying concrete actions users can perform and lacks an explicit 'Use when...' clause. Adding trigger guidance and more actionable verbs would significantly improve skill selection accuracy.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to track tasks, manage issues, create todos, or work with beads/bd in a coding project.'

List concrete actions such as 'create tasks, track dependencies, assign priorities, close issues, view task hierarchies' to improve specificity.

Include common natural language trigger terms like 'todo', 'tickets', 'bugs', 'backlog', 'project tasks' that users might say when needing this skill.

Dimension	Reasoning	Score
Specificity	Names the domain (task tracking, issue tracking) and mentions some features (dependency graphs, hierarchical tasks, multi-agent coordination), but doesn't list concrete actions like 'create issues', 'assign tasks', 'resolve dependencies', or 'close tickets'.	2 / 3
Completeness	The 'what' is partially covered (persistent task tracking, git-backed issue tracker with specific features), but there is no explicit 'Use when...' clause telling Claude when to select this skill. The 'when' is only implied by the opening phrase.	2 / 3
Trigger Term Quality	Includes some useful keywords like 'task tracking', 'issue tracker', 'beads', 'bd', and 'dependency graphs', but misses common user terms like 'todo', 'tickets', 'bugs', 'backlog', 'task list', or 'project management'.	2 / 3
Distinctiveness Conflict Risk	The description is quite distinctive with specific tool name 'beads (bd)', the git-backed nature, AI agent focus, and dependency graph features, making it unlikely to conflict with other skills.	3 / 3
	Total	9 / 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: block/agent-skills
Commit: 60bfdad

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