mirror of
https://github.com/alirezarezvani/claude-skills.git
synced 2026-10-03 02:21:55 +00:00
d3c822a517
Follow-up to v2.6.0. Uses the audit_skills.py tool (shipped in #646) to identify real bugs vs validator false-positives across 298 repo skills, then fixes both. Three coordinated changes: 1. Validator trigger pattern expansion (write-a-skill internal tools) - Old: only "Use when", "Use for", "Invoke when", "Trigger when" recognized - New: + "Use before/during/after/while", "Invoke before/after", "Apply when", "Run when/before" - Why: 11 legacy skills had semantically-valid triggers (e.g., gdpr-audit-prep says "Use before annual GDPR review") that the v2.6.0 validator wrongly flagged as missing. Natural English variants now accepted. - Impact: 30 skills reclassified from FAIL → WARN/PASS automatically. - Karpathy complexity: 100/100 (PASS) on both modified validators. 2. Ten placeholder descriptions fixed in engineering/skills/ The audit revealed 21 skills (~7% of repo) with broken descriptions that were literally just the skill name (e.g., description: "Migration Architect"). These were real bugs from a v2.0.0 batch import where the description field was never filled in. Top-10 fixed in this PR (POWERFUL-tier, high-visibility): - migration-architect: zero-downtime migration planning + rollback strategy - dependency-auditor: vulnerabilities + license + safe-upgrade audit - codebase-onboarding: codebase analysis + onboarding doc generation - ci-cd-pipeline-builder: pragmatic CI/CD from project stack signals - mcp-server-builder: MCP servers from OpenAPI contracts (Python + TS) - observability-designer: metrics + logs + traces + SLI/SLO design - api-design-reviewer: REST design review + breaking-change detection - performance-profiler: Node/Python/Go profiling + flamegraphs + load tests - changelog-generator: Conventional Commits → release notes automation - runbook-generator: operational runbooks from service name + templates Each new description: ≤1024 chars, third person, action verb in first sentence, "Use when ..." trigger in second sentence per Matt Pocock's rule. Remaining 11 placeholder descriptions tracked for v2.6.2. 3. Quality-gates reference updated (Option C: legacy advisory) quality_gates_for_skills.md now explicitly documents the binding-for-new vs advisory-for-legacy split. The 6-item checklist remains BLOCKING for post-v2.6.0 skills and ADVISORY for the 298 legacy SKILL.md files. Audit report drift is tracked separately; PASS count is the metric to grow, not a force-march-to-Friday deadline. Aggregate audit improvement (against the 298 real-skill cohort): - PASS: 4 (1%) → 7 (2%) - WARN: 111 (37%) → 134 (45%) - FAIL: 183 (61%) → 157 (53%) - "Missing trigger" failures: 119 (39%) → 79 (26%) 26 skills total lifted from FAIL → WARN/PASS in this PR. Highest-leverage fix per hour of any v2.6.x cleanup since the v2.6.0 release. https://claude.ai/code/session_01VFreMf7XLBqMgjsrG4wSYe |
||
|---|---|---|
| .. | ||
| .claude-plugin | ||
| agents | ||
| commands | ||
| skills/write-a-skill | ||
| README.md | ||
write-a-skill
Skill-author skill: create new agent skills with proper structure, progressive disclosure, and bundled resources.
Attribution
Derived from Matt Pocock's write-a-skill (MIT-licensed). Matt's skills repo — "Skills for Real Engineers. Straight from my .claude directory" — is the original source. Matt's SKILL.md voice + 3-phase workflow (Gather → Draft → Review) preserved verbatim per his MIT license.
What this adds on top of Matt's original
| Addition | Where | Why |
|---|---|---|
| 3 stdlib Python validation tools | skills/write-a-skill/scripts/ |
Operationalize Matt's review checklist (description validator, structure validator, review-checklist runner). Catches the common mistakes Matt names. |
| 3 in-depth references (5+ sources each) | skills/write-a-skill/references/ |
Progressive disclosure principles · Description design patterns · Quality gates for skills. Cites Anthropic skill docs + community precedent + research. |
| cs-skill-author persona agent | agents/cs-skill-author.md |
Surface skill-authoring as a forcing-question interrogation matching our cs-* persona pattern. |
/cs:write-a-skill slash command |
commands/cs-write-a-skill.md |
6-question forcing interrogation that runs Matt's review checklist programmatically. |
What Matt's original brings (preserved)
- The 3-phase workflow: Gather → Draft → Review
- The non-negotiable description rule: "The description is the only thing your agent sees when deciding which skill to load."
- The 100-line SKILL.md ceiling + progressive-disclosure pattern (REFERENCE.md / EXAMPLES.md / scripts)
- The good-example vs bad-example contrast for description writing
- The 6-item review checklist
- Matt's directness — no fluff, concrete patterns
Quick start
# Run Matt's review checklist on an existing skill
python skills/write-a-skill/scripts/skill_review_checklist_runner.py path/to/SKILL.md
# Validate description meets Matt's criteria (≤1024 chars, third person, "Use when" trigger)
python skills/write-a-skill/scripts/skill_description_validator.py path/to/SKILL.md
# Validate skill folder structure
python skills/write-a-skill/scripts/skill_structure_validator.py path/to/skill-folder/
All three tools run with embedded samples if no path provided.
License
MIT (matching Matt's upstream).