Skill Quality Gate

Relationship with skill-creator

• 6-step workflow: understand → plan → init → edit → package → iterate
• Template generation and packaging utilities
• Progressive disclosure principle

• Naming conventions and requirements
• Description quality standards with examples
• Quality checklist before deployment
• Anti-patterns to avoid
• Real-world pattern guidance

When to Use This Skill

• BEFORE writing any SKILL.md file (mandatory gate)
• After skill-creator generates template (validate before editing)
• Reviewing skills for quality before deployment
• Extracting patterns from repeated workflows into codified skills

• One-off instructions (just put in CLAUDE.md)
• Simple tool usage (Claude already knows)
• Tasks that don't repeat across sessions
• The process steps (use skill-creator for that)

Naming Requirements

• Lowercase letters, numbers, hyphens only
• Max 64 characters
• Match directory name exactly (critical)
• Use gerund or capability form:

  systematic-debugging

  ,

  workspace-fluency

• systematic-debugging

  - clear, action-oriented

• workspace-fluency

  - describes capability

• test-driven-development

  - known pattern name

• desired-outcomes

  - describes the concept

• pdf-helper

  - vague, "helper" is meaningless

• utils

  - generic, no information

• my-skill

  - doesn't describe purpose

• debug

  - verb, not gerund/capability

Description Requirements (CRITICAL)

[ACTION TYPE] + [SPECIFIC TRIGGER] + [METHOD/VALUE PREVIEW]

description: MANDATORY gate before writing any SKILL.md file. Invoke this skill FIRST when building new skills - provides structure template, naming conventions, description requirements, and quality checklist that MUST be validated before deployment.

• "MANDATORY gate" - not optional
• "before writing" - timing condition
• "FIRST" - positioning requirement
• "MUST be validated" - imperative

description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis testing, implementation) that ensures understanding before attempting solutions

• Specific trigger: "encountering any bug, test failure"
• Timing gate: "before proposing fixes"
• Method preview: "four-phase framework"
• Value: "ensures understanding before attempting solutions"

description: Coach on outcome quality with Tier 2 vs Tier 3 distinction. Triggers on 'check my outcomes', 'is this a good outcome', 'review my Todoist', 'why isn't this working' when discussing strategic work vs tactical projects.

• Explicit trigger phrases in quotes
• Context qualifier ("when discussing...")
• Domain-specific terms

description: Helps with debugging code problems

• No specific trigger
• Vague ("helps with")
• No insight into method or timing

description: Use when creating skills

• Too generic (I "know" patterns without invoking)
• No timing gate
• No method preview

Quality Checklist (MANDATORY)

Structure

• SKILL.md under 500 lines
• Name matches directory name exactly
• Name is kebab-case, gerund/capability form
• Description is third-person (verbs: "Orchestrates", "Calibrates", not "Use", "Invoke")
• Description includes trigger AND method AND timing
• Description ends with (user) tag for user-defined skills
• References one level deep from SKILL.md (if used)
• YAML frontmatter present with name and description

Content

• No time-sensitive information ("after Aug 2025...")
• Consistent terminology throughout
• Concrete examples, not abstract rules
• Configuration values justified (why these numbers?)
• Error handling documented
• Dependencies explicitly listed
• Anti-patterns section present

Workflow

• Clear phases/steps with success criteria
• When to Use AND When NOT to Use sections
• Integration points with other skills explicit
• Verification/validation included
• Quick reference for common operations

Discovery

• Description uses BEFORE/MANDATORY/FIRST patterns where appropriate
• Trigger phrases are natural language users actually say
• Context qualifiers included (when appropriate)
• Method preview gives Claude enough to decide if relevant
• If paired with a command (

  ~/.claude/commands/*.md

  ), command explicitly names the skill

Anti-Patterns to Avoid

In Discovery (Most Critical)

skill-name

In Structure

In Content

Integration with Other Skills

• skill-creator - Anthropic's process (template generation, packaging)
• verification-before-completion - Validate after skill-creator steps

## Integration with Other Skills

**Requires:**
- **root-cause-tracing** - When error is deep in call stack (Phase 1, Step 5)

**Complements:**
- **verification-before-completion** - Verify fix before claiming success

Real-World Skill Quality Patterns

High-Invocation Skills Share

1. BEFORE conditions in description (systematic-debugging, verification-before-completion)
2. Specific trigger phrases in quotes (crash-recovery, desired-outcomes)
3. Method preview that's actionable (test-driven-development, brainstorming)
4. Clear anti-patterns that catch mistakes (workspace-fluency)
5. Integration points that compose (skill referencing skill)

Low-Invocation Skills Suffer From

1. Generic "Use when..." descriptions (Claude knows patterns without loading)
2. Vague value propositions ("helps with", "guides", "assists")
3. Missing timing gates (no BEFORE/FIRST/MANDATORY)
4. Documenting what Claude already knows (not teaching new patterns)

Common Skill Types

Process Skills (like systematic-debugging)

• Iron law or core principle
• Phases with explicit success criteria
• Anti-patterns with rationalizations
• Red flags that trigger "STOP"
• BEFORE condition in description

Fluency Skills (like workspace-fluency)

• Tool selection guidance
• Workflows for common tasks
• Best practices for domain
• Error handling patterns
• Integration with data skills

Coaching Skills (like desired-outcomes)

• Quality criteria (good vs poor examples)
• Coaching questions to ask
• Pattern recognition for bad input
• Pattern intervention points
• Specific trigger phrases

Quality Gate Skills (like this one)

• MANDATORY language in description
• Checklist-driven validation
• Requirements with examples
• Anti-patterns to catch
• Complement process skills

Quick Reference

Minimum Viable Skill

---
name: kebab-case-name
description: [TIMING] + [TRIGGER] + [METHOD/VALUE]. Specific phrases: 'phrase1', 'phrase2'.
---

# Skill Title

[Core principle]

## When to Use
[Specific triggers with examples]

## When NOT to Use
[Clear boundaries]

## Workflow/Process
[Steps with success criteria]

## Anti-Patterns
[What to avoid with fixes]

## Quick Reference
[Common operations]

Files to Include

Before Sharing

# Scan for PII, secrets, paths
~/.claude/skills/skill-check/scripts/scan.py /path/to/skill

# High-risk only (blocking issues)
~/.claude/skills/skill-check/scripts/scan.py --risk high /path/to/skill

# JSON output for processing
~/.claude/skills/skill-check/scripts/scan.py --format json /path/to/skill

1. Run scanner on target
2. Triage findings by risk level (high first)
3. Remediate or accept each finding
4. Rescan to verify clean
5. Share

references/sharing-scan.md

Success Criteria

• Every skill built passes the quality checklist
• Description triggers invocation reliably (not bypassed)
• Naming conventions are consistent across skills
• Anti-patterns are caught before deployment
• Integration with skill-creator is smooth

Remember