Feedback on your senior-prompt-engineer skill

[RichardHightower]

I looked at your senior-prompt-engineer skill and noticed the grading rubric heavily penalizes the documentation structure—the core ideas are solid, but they're buried under formatting choices that make them harder to follow for developers actually trying to use the skill.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 36/100, which is an F grade. This is based on Anthropic's best practices for skill design. Your strongest area is Spec Compliance (12/15)—the YAML structure and naming conventions are solid. The real drag is Utility (4/20) and Writing Style (2/10)—you've got aspirational concepts but they lack concrete, actionable workflows that developers can actually execute.

What's Working Well

• Valid metadata structure - Your YAML frontmatter is clean and follows conventions perfectly
• Decent trigger coverage - You've identified relevant use cases like "optimizing LLM performance" and "designing agentic systems"
• Reference architecture - Having three reference files shows you're thinking layered, even if the content needs work
• Grep-friendly structure - The skill is organized in a way that's easy to search and navigate

The Big One: Duplicate Reference Content

Here's what's killing your score: all three reference files (prompt_engineering_patterns.md, agentic_system_design.md, llm_evaluation_frameworks.md) are 80%+ identical boilerplate. They share the same "Core Principles," "Advanced Patterns," and "Best Practices" sections—which defeats the whole purpose of having multiple references.

Why it matters: Progressive Disclosure Architecture is supposed to layer specific, relevant details. Right now you're wasting tokens repeating the same content three times instead of giving developers actionable patterns they can actually use.

Concrete fix: Differentiate each reference:

• prompt_engineering_patterns.md → Specific prompt techniques with example inputs/outputs
• llm_evaluation_frameworks.md → Concrete metrics, scoring methods, comparison tables
• agentic_system_design.md → Agent architectures (ReAct, planning loops, tool use patterns) with pseudocode

This alone could add +8 points.

Other Things Worth Fixing

1. Remove marketing language - "world-class" appears 5+ times. Strip all qualifiers like "senior-level," "enterprise-scale," "advanced." Let the content speak for itself. (+3 points)

2. Add a Table of Contents - Your SKILL.md is 227 lines with no TOC. Add one after the metadata so developers can jump to sections they need. (+2 points)

3. Concrete workflows instead of vague bullets - Right now you have bullets like "Monitor everything critical" and "Automate deployments." Replace with numbered steps: "1. Baseline current prompt with eval set → 2. Apply pattern X → 3. Run optimizer script → 4. Compare metrics → 5. Iterate if <10% improvement." (+6 points)

4. Context for every command - Commands are listed alone. Add what inputs they expect, what outputs you should see, and when to use them. (+4 points)

Quick Wins

• Kill the marketing language first (easiest, quick win)
• Give each reference file actual, different content (biggest impact)
• Add workflows with numbered steps so developers know what to do
• Include input/output examples for every command or script

These changes could realistically push you from 36 to 55-60 range.

---

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.

[alirezarezvani]

Thank you for the detailed feedback! I've implemented all the suggested improvements in PR #91.

Summary of Changes

SKILL.md:

• Added YAML frontmatter with trigger phrases for skill discovery
• Removed all marketing language ("world-class" appeared 5+ times)
• Added Table of Contents
• Converted vague bullets to 3 concrete workflows with step-by-step instructions
• Added input/output examples for all tool commands

Reference Files (all 3 were 100% identical - now unique):

• prompt_engineering_patterns.md: 10 patterns (Zero-Shot, Few-Shot, CoT, Role Prompting, Structured Output, Self-Consistency, ReAct, Tree of Thoughts, RAG, Meta-Prompting) with input/output examples
• llm_evaluation_frameworks.md: 7 sections covering BLEU, ROUGE, BERTScore, RAG metrics, human evaluation, A/B testing, and benchmarks
• agentic_system_design.md: 6 sections covering ReAct, Plan-and-Execute, Tool Use, Multi-Agent, Memory/State, and Design Patterns with architecture diagrams

Python Scripts (all 3 were identical placeholders - now functional):

• prompt_optimizer.py: Token counting, clarity scoring, few-shot extraction, optimization suggestions
• rag_evaluator.py: Context relevance, answer faithfulness, retrieval metrics (Precision@K, MRR, NDCG)
• agent_orchestrator.py: YAML/JSON parsing, validation, ASCII/Mermaid visualization, cost estimation

Stats:

• Before: ~785 lines of duplicate boilerplate
• After: 3,750 lines of unique, actionable content
• 3,571 lines added, 587 deleted

All scripts pass syntax validation and use only Python standard library (no external dependencies).

[alirezarezvani]

Issue Resolved ✅

All recommendations have been implemented and merged into main.

Changes Summary

Component	Before	After
SKILL.md	Marketing language, no TOC, vague bullets	Clean, structured with TOC and workflows
Reference files (3)	80%+ identical boilerplate	Unique, actionable content
Python scripts (3)	Identical placeholders	Working implementations

Recommendations Addressed

• ✅ Removed marketing language ("world-class" etc.)
• ✅ Added Table of Contents
• ✅ Differentiated all 3 reference files with unique content
• ✅ Added concrete workflows with numbered steps
• ✅ Added input/output context for all commands

Stats: 3,571 lines added, 587 deleted

Thank you for the detailed feedback - it significantly improved the skill quality!