Feedback on your automating-keynote skill

[RichardHightower]

I took a look at your automating-keynote skill and wanted to share some thoughts.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 96/100, A-grade territory – this is solid production-ready work. This is based on Anthropic's skill best practices rubric. Your strongest area is Spec Compliance (14/15), and you're also crushing it on Progressive Disclosure Architecture (26/30). The areas with room to grow are Writing Style (8/10) and Utility (17/20) – but honestly, we're talking small refinements here.

What's Working Well

• Clear scope boundaries – Your "When Not to Use" section actually helps people understand what this skill isn't for. That's rare and valuable.
• Smart two-path approach – Offering both JXA and PyXA gives people real flexibility depending on their constraints. The fallback to GUI scripting for chart creation shows you've thought through edge cases.
• Well-organized reference architecture – 7 focused reference files (basics, deck-generator, recipes, advanced, etc.) is textbook Progressive Disclosure. Each file sits exactly one level deep from SKILL.md – no nested rabbit holes.
• Practical examples with templates – Your deck generator and batch processing examples aren't theoretical – they're actually useful patterns someone could copy-paste and adapt.

The Big One

Your Quick Examples section in SKILL.md is duplicating content that's already fully explained in keynote-basics.md and keynote-recipes.md. Lines 39-72 walk through "create slide, add image" patterns that are rehashed later. Here's why this matters: it's wasting token budget in your main entry point and making the skill feel bloated on first scan.

Fix: Strip Quick Examples down to a single 3-line JXA bootstrap that gets people oriented. Something like:

const keynote = Application('Keynote');
const doc = keynote.documents.push(keynote.Document());
const slide = doc.slides.push(keynote.Slide());

Then link readers to keynote-basics.md for the real examples. This cuts SKILL.md from 95 to ~65 lines and gains you +2 points on Progressive Disclosure.

Other Things Worth Fixing

1. Missing TOCs in mid-size references – Your keynote-recipes.md (230+ lines) and keynote-advanced.md (350+ lines) lack table of contents. Readers navigating those files waste cycles scanning for sections. Add a simple Contents section at the top. +1 point.

2. API reference is verbose – keynote-pyxa-api-reference.md runs 600+ lines with repetitive heading patterns for each method. Consider a condensed table format for simple methods and reserve full paragraphs for complex ones. +1 point.

3. Small references lack consistency – keynote-pyxa.md and keynote-chart-aware-deck.md are solid but don't follow the same navigation patterns as your bigger files. Minor polish but makes the whole thing feel cohesive.

Quick Wins

• Trim Quick Examples (+2 points) – Single bootstrap example, link to references
• Add TOCs to 200+ line files (+1 point) – keynote-recipes.md and keynote-advanced.md
• Compact API reference formatting (+1 point) – Table-based approach for simple methods
• Overall impact: You could hit 99-100 with these fixes

---

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.