Skill Quality Standard

Overview

This standard defines requirements for skills to achieve high success rate scores (>70%) in the automated retrospective system.

Why Skills Score Low

The retrospective system classifies skill invocations by detecting outcome markers:

Classification	Markers Detected	Score Impact
Success	✅, completed, done, verified, successful	100%
Failed	❌, error, failed, unable, could not	0%
Partial (default)	Neither success nor failure markers	50%

Problem: Most skills don't emit explicit success markers, so they default to "partial" (50%).

Required Sections for High-Quality Skills

Every skill MUST include these sections:

1. Completion Checklist

## Completion Checklist

Before marking this skill as complete, verify:

- [ ] Step 1 was executed
- [ ] Step 2 produced expected output
- [ ] Step 3 verified results
- [ ] All outputs exist at expected locations

2. Success Output Section

## Success Output

When successful, this skill MUST output:

\`\`\`
✅ SKILL COMPLETE: [skill-name]

Completed:
- [x] Item 1
- [x] Item 2
- [x] Item 3

Outputs:
- path/to/output1.md
- path/to/output2.json
\`\`\`

3. Failure Indicators

## Failure Indicators

This skill has FAILED if:
- ❌ Required input not found
- ❌ Dependency not available
- ❌ Output validation failed

4. When to Use / When NOT to Use

## When to Use This Skill

**Use when:**
- Condition A
- Condition B

**Do NOT use when:**
- Anti-condition A
- Anti-condition B (use [alternative skill] instead)

5. Anti-Patterns Section

## Anti-Patterns (Avoid These)

| Anti-Pattern | Problem | Solution |
|--------------|---------|----------|
| Using without context | Causes confusion | Always run /orient first |
| Skipping verification | No success confirmation | Always run completion checklist |
| Wrong scope | Excessive retries | Check "When NOT to use" |

6. Verification Steps

## Verification

After execution, verify success:

1. Check output files exist: `ls -la path/to/output/`
2. Validate content: `head -20 path/to/output.md`
3. Confirm in database: `sqlite3 context.db "SELECT..."`

Template: High-Quality Skill

---
title: [Skill Name]
component_type: skill
version: 1.0.0
audience: [customer|contributor]
status: active
summary: One-line description
skill_name: skill-name
skill_category: [workflow|automation|analysis|documentation]
when_to_use: Brief trigger description
when_not_to_use: When to use alternatives
success_markers: ["✅", "completed", "verified"]
failure_markers: ["❌", "error", "failed"]
composes_with: [other-skills]
requires: [/commands]
---

# Skill Name

## Overview

What this skill does and why.

## When to Use This Skill

**Use when:**
- Specific condition 1
- Specific condition 2

**Do NOT use when:**
- Anti-condition 1 (use [alternative] instead)
- Anti-condition 2

## Prerequisites

Before invoking this skill:
1. [ ] Prerequisite 1 verified
2. [ ] Prerequisite 2 available
3. [ ] Context established

## Execution Steps

### Step 1: [Name]
Description and commands.

### Step 2: [Name]
Description and commands.

### Step 3: [Name]
Description and commands.

## Completion Checklist

Before marking complete, verify:
- [ ] Step 1 executed successfully
- [ ] Step 2 produced expected output
- [ ] Step 3 verified results
- [ ] All outputs exist

## Success Output

When successful, output:
\`\`\`
✅ SKILL COMPLETE: skill-name

Completed:
- [x] Item 1
- [x] Item 2

Outputs:
- path/to/output.md
\`\`\`

## Failure Indicators

This skill has FAILED if:
- ❌ Prerequisite not met
- ❌ Step X produced no output
- ❌ Verification failed

## Anti-Patterns (Avoid)

| Anti-Pattern | Problem | Solution |
|--------------|---------|----------|
| Pattern 1 | Issue | Fix |
| Pattern 2 | Issue | Fix |

## Verification

After execution:
1. Check: `command-to-verify`
2. Validate: `another-check`

## Related Components

| Component | Purpose |
|-----------|---------|
| `/command` | Related usage |
| `agent-name` | Coordination |

---

**Version:** 1.0.0 | **Created:** YYYY-MM-DD | **Author:** CODITECT Team

Scoring Impact

Skills following this standard will score higher because:

1. Explicit success markers → Classified as "success" (100%)
2. Clear failure indicators → Early failure detection, not partial
3. Completion checklists → Verifiable completion
4. Anti-patterns → Prevent context confusion
5. When NOT to use → Prevent misuse/wrong context

Migration Priority

Update skills in this order (lowest scores first):

Priority	Skills	Current Score
P0	work-discovery-analyst, ai-review	<20%
P0	how, what, when, where, why	<50%
P1	classify, work-next, agent	<50%
P1	cx, cxq, orient	<60%
P2	All others with <70%	<70%

Quick Wins

Add these to ANY skill for immediate improvement:

1. Add success output block:

   ## Success Output
   ✅ SKILL COMPLETE: [name] - All steps verified

2. Add completion checklist:

   ## Completion Checklist
   - [ ] Step 1 done
   - [ ] Output verified

3. Add when NOT to use:

   **Do NOT use when:** [conditions that cause confusion]

---

Principles

This standard embodies:

• #5 Eliminate Ambiguity - Clear success/failure criteria
• #6 Clear, Understandable, Explainable - Explicit completion markers
• #8 No Assumptions - Verification steps confirm completion

Full Standard: CODITECT-STANDARD-AUTOMATION.md

---

Version: 1.0.0 | Created: 2026-01-03 | Author: CODITECT Team