Feedback on your tool-design skill

[RichardHightower]

I've been digging into how tools evolve as systems grow more complex, and your skill nails the progression from "what should this do" to "how do we actually build it"—the fact that you scored 92 says you're handling the hard part most people skip over.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 92/100, solidly in A territory. This is based on Anthropic's best practices for skill design. Your writing style is the strongest pillar (9/10)—clear, objective, and technically sound. The weakest spot is spec compliance (12/15), mostly because your description could lean harder on trigger phrases for discoverability.

What's Working Well

• Writing Style is tight — Your 9/10 here reflects genuinely professional docs. The consolidation principle is explained without fluff, and you use imperative language cleanly. The Tool Selection Framework feels like something someone would actually follow.

• Architecture is thoughtfully layered — SKILL.md gives the overview, best_practices.md goes deep (177 lines), but you're not repeating yourself. That's how you score 26/30 on Progressive Disclosure Architecture. The reference file pattern lets someone get oriented quickly without drowning in details.

• Utility is solid (18/20) — Your Tool-Testing Agent Pattern and the well-designed vs. poorly-designed tool comparisons give developers real leverage. The feedback loops section actually walks through how to iterate, not just talk about it.

The Big One: Missing Table of Contents

Here's what's holding back an extra 1-2 points: SKILL.md runs 270 lines and best_practices.md hits 177 lines, but neither has a TOC. This hurts navigation signals in your PDA score.

For someone scrolling through, a simple TOC after your metadata makes a huge difference:

## Overview
[intro paragraph]

## Contents
- [Core Concepts](#core-concepts)
- [Tool Selection Framework](#tool-selection-framework)
- [Design Patterns](#design-patterns)
- [Practical Examples](#practical-examples)
- [Integration](#integration)
- [References](#references)

## Core Concepts
[existing content]

Do the same in best_practices.md. This nets you +1 point on PDA (navigation_signals → 5/5).

Other Things Worth Fixing

1. Tighten the description triggers — You've got some good ones ("creating new tools", "debugging tool-related failures"), but the description field only captures 1-2. Add more specific keywords like "tool consolidation", "agent tool design", "tool description patterns". This is a quick win for spec compliance (3→4).

2. Watch the second-person voice in best_practices.md — Lines around 81-107 slip into "you" language ("When designing tool collections, consider what information you need..."). Flip it to agent-centric ("When designing tool collections, identify what information agents need..."). Minor, but keeps it consistently instructional.

3. Consolidate Integration section — Your Integration section (lines 241-247) lists skills that already appear in References. Either remove it or fold those related skills into a "Related Skills" subsection in References to avoid redundancy.

4. Document your scripts — You've got description_generator.py and verify.py in the scripts/ directory, but they're not mentioned anywhere. Add a note in SKILL.md or best_practices.md so people know those utilities exist.

Quick Wins

• Add TOC to both files → +1 point (PDA)
• Expand description triggers → +1 point (Spec Compliance)
• Fix second-person voice → +1 point (Writing Style)
• Remove redundant Integration section → cleaner architecture
• Document utility scripts → better discoverability

These changes should bump you to 95-96/100 easily.

---

Checkout your skill here: [SkillzWave.ai](https://skillzwave.ai) | [SpillWave](https://spillwave.com) We have an agentic skill installer that install skills in 14+ coding agent platforms. Check out this guide on how to improve your agentic skills.