Feedback on your google-style-guide skill #97
Description
I came across your google-style-guide skill and noticed how you've structured the guidance—the layered approach to different documentation contexts is solid, though I'm curious whether the enforcement mechanisms scale when developers have conflicting style preferences across teams.
Links:
The TL;DR
You're at 86/100, solid B territory. This is based on Anthropic's best practices for skill architecture. Your Writing Style is chef's kiss (10/10)—clear imperative voice throughout with zero marketing fluff. The weaker spots are Spec Compliance (11/15) and Utility (18/20), mostly around discoverability and validation workflows.
What's Working Well
- Perfect token economy — Your SKILL.md is 78 lines of pure signal; no bloat, every sentence earns its place. Reference files handle the depth without cluttering the entry point.
- Solid progressive disclosure — Three-tier structure (SKILL.md → references) is exactly right. The layering means someone can get started in 30 seconds or dig deep if they need it.
- Writing clarity throughout — Consistent use of active voice ("Use active voice", "Write clear procedures"). No second-person violations, no unnecessary hedging. That's the kind of consistency that makes skills actually useful.
- Strong before/after examples — Your formatting and grammar sections show clear input/output pairs that teach by contrast, not just by decree.
The Big One
Your reference files lack navigation for longer content. formatting.md is 234 lines without a table of contents—that's the size where someone reading it on their third search is going to lose the thread. Add a TOC to any reference file over 100 lines:
# Formatting Guidelines
## Table of Contents
- [Lists](#lists)
- [Comma-Separated Lists](#comma-separated-lists)
- [Numbers](#numbers)
- [Dates and Times](#dates-and-times)
- [Code and Technical Elements](#code-and-technical-elements)
- [Procedures](#procedures)
- [Tables](#tables)
## Lists
...This should net you +2 points on PDA and makes the skill feel more professional to use.
Other Things Worth Fixing
-
Expand trigger phrases — Your description has 1-2 triggers; add a few more specific ones like "inclusive language review" or "technical writing style". More discoverability, especially for niche documentation tasks.
-
Add explicit validation workflow — Right now the Quick Start says "apply principles." Give people a concrete checklist they can run through: Check voice/tense → Verify list formatting → Review inclusive language → Validate code blocks. That's +1 point on Utility.
-
XML tag cleanup — Minor metadata issue (frontmatter has some formatting quirks) that cost you a point. Worth a quick pass if you're touching the SKILL.md anyway.
Quick Wins
- Add TOC to formatting.md (234 lines) → +2 points
- Add 2-3 more specific trigger phrases → Better discoverability
- Create a review checklist section → +1 point, makes Utility pop
- Clean up frontmatter formatting → Polish
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.