B+

agentic harness

Skill Quality Auditor

Evaluate, score, and remediate agent skill collections using a 9-dimension quality framework (Knowledge Delta, Mindset, Anti-Patterns, Specification Compliance, Progressive Disclosure, Freedom Calibration, Pattern Recognition, Practical Usability, Eval Validation). Performs duplication detection, generates remediation plans with T-shirt sizing, enforces CI quality gates, validates artifact conventions, tracks score trends, and ensures tessl registry compliance. Use when evaluating skill quality, auditing SKILL.md files, scoring agent skills, generating remediation plans, detecting duplicate skills, validating skill format, enforcing quality gates, optimizing for A-grade publication, comparing audit baselines, batch skill assessments, or checking tessl compliance. Triggers: 'check my skills', 'skill audit', 'improve my SKILL.md', 'quality check', 'A-grade scoring', 'quality gates', 'eval validation', 'audit all skills', 'remediation plan', 'skill judge', 'dimension scoring'.

npx tessl install pantheon-ai/skill-quality-auditor

npx skills add github:pantheon-org/tekhne --skill agentic-harness--skill-quality-auditor

Navigation hub for evaluating, maintaining, and improving skill quality with 9-dimension framework scoring.

Prerequisites

This skill drives the pantheon-skill-auditor CLI and is distributed by it (pantheon-skill-auditor skill install). Every audit command below requires that binary on PATH. Confirm it is available:

pantheon-skill-auditor --version

If it is missing, build or install it first (see Quick Start). There is no self-contained fallback for these commands.

Quick Start

Build once, then audit:

Build once:

bun run build:skill-auditor

Run audits:

# Single skill
pantheon-skill-auditor evaluate <domain>/<skill-name> --json --store

# Batch with grade gate
pantheon-skill-auditor batch <skill1> <skill2> --fail-below B --store

When to Use

Evaluate skills before merge or publication using 9-dimension scoring
Generate remediation plans, detect duplication (>20% threshold), or enforce CI quality gates
Validate eval scenario coverage and artifact conventions

When Not to Use

Write the skill first — do not audit an unfinished draft
Avoid using this as a substitute for peer review of logic or domain accuracy

Workflow

Run pantheon-skill-auditor evaluate <skill> --json --store
Check artifacts and eval coverage using deterministic criteria
Generate a remediation plan with T-shirt sizing and score delta estimates
Run the auditor again to verify improvement; if score is below target, check remediation-plan.md and focus on the lowest-scoring dimension

Mindset

Use scores as directional signals, not absolute truth.
Apply deterministic, reproducible checks over manual review.
Use threshold-based evaluation rather than relative comparisons.
Keep audit rules strict for safety and consistency; stay flexible elsewhere.

Anti-Patterns (Summary)

NEVER skip baseline comparison in recurring audits — WHY: score regressions go undetected without a prior audit.json
NEVER ignore Knowledge Delta below 15/20 — WHY: low D1 means the skill adds no value over LLM baseline
NEVER apply subjective scoring — WHY: scores drift between evaluators and cannot be automated in CI
NEVER create kitchen-sink skills covering unrelated tasks — WHY: broad scope kills D7 and prevents correct triggering
NEVER use harness-specific paths in skill content — WHY: absolute paths break when installed in a different repo
NEVER list references without “When to Use” conditions — WHY: unconditional loading bloats context and penalises D5

Ensure you review Detailed Anti-Patterns for all WHY/BAD/GOOD failure modes including agent name references and D4 heading rules.

Examples

Remediation workflow:

pantheon-skill-auditor evaluate documentation/markdown-authoring --json --store
# Score: 98/140 (C+) -> review remediation-plan.md -> fix -> re-audit -> 128/140 (A)

PR-scoped triage:

skills=$(git diff --name-only origin/main | grep "skills/.*/SKILL.md" | sed 's|skills/||;s|/SKILL.md||' | tr '\n' ' ')
pantheon-skill-auditor batch $skills --fail-below B --store

Audit all skills:

pantheon-skill-auditor batch $(find skills -name "SKILL.md" | sed 's|skills/||;s|/SKILL.md||' | tr '\n' ' ')

See Audit Workflow Examples for input/output pairs and CI quality gate examples.

Self-Audit

pantheon-skill-auditor evaluate agentic-harness/skill-quality-auditor --json
# Expected: A grade, total >= 126/140

References

Framework

Topic	Reference	When to Use
Per-dimension criteria and bonus rules	Dimensions	Evaluating any dimension or understanding the rubric
Score thresholds and grade bands	Scoring Rubric	Calculating a total score or assigning a grade
A-grade checklist and red flags	Quality Standards	Targeting A-grade or reviewing blockers
Trigger pattern density and keyword analysis	Pattern Recognition	Scoring D7 or improving description keywords
Canonical SKILL.md structure and References table standard	SKILL Template	Authoring or refactoring a skill

Operations

Topic	Reference	When to Use
CI gate configuration and batch pass/fail logic	Quality Thresholds	Setting up CI quality gates
NEVER/WHY/BAD/GOOD failure modes per dimension	Anti-Patterns	Explaining low scores or writing remediation guidance
T-shirt sizing and remediation roadmaps	Remediation Planning	Writing a remediation plan for a C/D-grade skill
Deduplication workflow and aggregation guidance	Duplication Detection	Detecting skill overlap or planning aggregations
`pantheon-skill-auditor evaluate/batch` usage and output formats	Scripts Workflow	Running audits from the command line
Registry publication gates and tessl compliance checks	Tessl Compliance	Preparing a skill for public registry submission

123/ 140

Explicit NEVER/WHY/consequence triplets with side-by-side bad/good examples. Generic warnings score low — concrete failure modes with real impact (security, correctness, performance) score high.

Runtime validation via tessl eval scenarios proving the skill actually changes agent behaviour. Requires evals/ directory, instructions.json, ≥3 scenarios, and ≥80% instruction coverage in summary.json.

Appropriate rigidity for the skill type: strict rules for critical/security skills, balanced steps for process skills, flexible options for tool skills. Mismatched calibration (too rigid or too loose) reduces score.

Expert-only knowledge the AI couldn't derive on its own — domain-specific patterns, production gotchas, decision frameworks, and non-obvious tool behaviour. High scores mean <5% redundancy with what the model already knows.

A clear philosophy plus numbered step-by-step workflows with explicit entry/exit points. Should answer: what is the core principle, how to execute it, and when (and when not) to apply it.

Rich activation keywords and trigger scenarios in the description so the skill fires when needed. Best descriptions read like an exhaustive list of the tasks and concepts that should invoke this skill.

Copy-paste-ready code, complete runnable examples, real file paths and commands. Pseudocode and abstract descriptions score low — concrete, executable content scores high.

SKILL.md as a <100-line navigation hub pointing to focused references/ files. Content should be lazy-loaded on demand, not front-loaded. Includes actionable 'When to Use' conditions per reference.

Proper frontmatter, single-task focus, activation keywords, and cross-harness portability. Skills must work across 40+ agentic harnesses without hardcoded paths or agent-specific references.

119 lines · 24 references

127/ 140

A clear philosophy plus numbered step-by-step workflows with explicit entry/exit points. Should answer: what is the core principle, how to execute it, and when (and when not) to apply it.

Explicit NEVER/WHY/consequence triplets with side-by-side bad/good examples. Generic warnings score low — concrete failure modes with real impact (security, correctness, performance) score high.

Proper frontmatter, single-task focus, activation keywords, and cross-harness portability. Skills must work across 40+ agentic harnesses without hardcoded paths or agent-specific references.

SKILL.md as a <100-line navigation hub pointing to focused references/ files. Content should be lazy-loaded on demand, not front-loaded. Includes actionable 'When to Use' conditions per reference.

Copy-paste-ready code, complete runnable examples, real file paths and commands. Pseudocode and abstract descriptions score low — concrete, executable content scores high.

144 lines · 23 references

128/ 140

A clear philosophy plus numbered step-by-step workflows with explicit entry/exit points. Should answer: what is the core principle, how to execute it, and when (and when not) to apply it.

Explicit NEVER/WHY/consequence triplets with side-by-side bad/good examples. Generic warnings score low — concrete failure modes with real impact (security, correctness, performance) score high.

Proper frontmatter, single-task focus, activation keywords, and cross-harness portability. Skills must work across 40+ agentic harnesses without hardcoded paths or agent-specific references.

SKILL.md as a <100-line navigation hub pointing to focused references/ files. Content should be lazy-loaded on demand, not front-loaded. Includes actionable 'When to Use' conditions per reference.

Copy-paste-ready code, complete runnable examples, real file paths and commands. Pseudocode and abstract descriptions score low — concrete, executable content scores high.

97 lines · 23 references

Custom Metrics

Domain-specific evaluation frameworks for specialized skill quality assessment.

Overview

Purpose: Extend 9-dimension quality framework with custom metrics
Use Cases: Domain-specific requirements, organizational standards
Priority: LOW - Use when standard metrics insufficient

When to Add Custom Metrics

Consider custom metrics when:

Standard dimensions don’t capture domain needs
Organization has specific compliance requirements
Skills serve specialized audiences
Industry-specific quality standards apply

Custom Metric Design

Metric Structure

Each custom metric should define:

Name: Clear, descriptive identifier
Description: What the metric measures
Max Points: Contribution to total score
Evaluation Method: How to assess
Scoring Rubric: Point thresholds

Example Custom Metrics

D9: Security Compliance (15 points)

For skills handling security-sensitive operations:

## D9: Security Compliance (15 points)

### Purpose
Ensure skills follow security best practices.

### Evaluation Method
1. Check for security warnings
2. Verify no hardcoded secrets
3. Confirm input validation guidance
4. Review authentication patterns

### Scoring Rubric
| Score | Criteria |
|-------|----------|
| 13-15 | All security checks passed |
| 10-12 | Minor issues (warnings) |
| 7-9 | Moderate issues |
| 0-6 | Critical security flaws |

D10: Accessibility (10 points)

For skills involving UI/UX:

## D10: Accessibility Compliance (10 points)

### Purpose
Ensure skills include accessibility guidance.

### Evaluation Method
1. Check for WCAG references
2. Verify screen reader guidance
3. Confirm keyboard navigation
4. Review color contrast guidance

### Scoring Rubric
| Score | Criteria |
|-------|----------|
| 9-10 | Comprehensive accessibility |
| 7-8 | Basic accessibility |
| 5-6 | Minimal accessibility |
| 0-4 | No accessibility guidance |

D11: Performance (10 points)

For skills involving performance-critical code:

## D11: Performance Guidance (10 points)

### Purpose
Ensure skills include performance considerations.

### Evaluation Method
1. Check for performance warnings
2. Verify benchmark examples
3. Confirm optimization guidance
4. Review anti-patterns

### Scoring Rubric
| Score | Criteria |
|-------|----------|
| 9-10 | Comprehensive performance |
| 7-8 | Good performance guidance |
| 5-6 | Basic performance notes |
| 0-4 | No performance guidance |

Implementation

Custom Evaluation Script

// evaluate-custom.ts

interface CustomMetric {
  name: string;
  maxPoints: number;
  evaluate(skillPath: string): number;
}

const customMetrics: CustomMetric[] = [
  {
    name: "Security Compliance",
    maxPoints: 15,
    evaluate: (skillPath) => {
      // Custom evaluation logic
      const content = readFile(skillPath);
      let score = 0;
      
      if (content.includes("NEVER hardcode")) score += 5;
      if (content.includes("input validation")) score += 5;
      if (content.includes("authentication")) score += 5;
      
      return score;
    }
  },
  {
    name: "Accessibility",
    maxPoints: 10,
    evaluate: (skillPath) => {
      const content = readFile(skillPath);
      let score = 0;
      
      if (content.includes("WCAG")) score += 3;
      if (content.includes("screen reader")) score += 3;
      if (content.includes("keyboard")) score += 2;
      if (content.includes("contrast")) score += 2;
      
      return score;
    }
  }
];

function evaluateWithCustom(skillPath: string): ScoreReport {
  // Standard evaluation
  const standardScore = evaluateStandard(skillPath);
  
  // Custom metrics
  const customScores = customMetrics.map(m => ({
    name: m.name,
    score: m.evaluate(skillPath),
    max: m.maxPoints
  }));
  
  return {
    standard: standardScore,
    custom: customScores,
    total: standardScore + customScores.reduce((a, b) => a + b.score, 0),
    maxTotal: 120 + customScores.reduce((a, b) => a + b.max, 0)
  };
}

Custom Configuration

# custom-metrics.yaml
metrics:
  - name: security-compliance
    enabled: true
    maxPoints: 15
    appliesTo:
      - "security-*"
      - "auth-*"
      - "*-api"
    
  - name: accessibility
    enabled: true
    maxPoints: 10
    appliesTo:
      - "ui-*"
      - "frontend-*"
      - "design-*"
    
  - name: performance
    enabled: true
    maxPoints: 10
    appliesTo:
      - "*-optimization"
      - "*-performance"
      - "database-*"

Organization-Specific Standards

Enterprise Compliance

For organizations with regulatory requirements:

## Enterprise Compliance Metrics

### D12: Documentation Standards (10 points)

**Applies to**: All skills

**Requirements**:
- [ ] Version history maintained
- [ ] Owner/contact documented
- [ ] Review date specified
- [ ] Approval workflow followed

**Scoring**:
- 10: All compliance requirements met
- 7: Minor documentation gaps
- 4: Significant gaps
- 0: Non-compliant

Industry-Specific

Healthcare (HIPAA)

## D13: HIPAA Compliance (15 points)

**Applies to**: Skills handling PHI

**Requirements**:
- PHI handling guidance
- Encryption requirements
- Audit logging patterns
- Access control guidance

Finance (PCI-DSS)

## D14: PCI-DSS Compliance (15 points)

**Applies to**: Skills handling payment data

**Requirements**:
- Card data handling
- Encryption standards
- Secure transmission
- Storage requirements

Metric Integration

Modified Grade Scale

With custom metrics, adjust grade scale:

Custom Points	New Total	A-Grade Threshold
+15	135	122 (90%)
+25	145	131 (90%)
+35	155	140 (90%)

Combined Report

## Skill Evaluation Report

### Standard Dimensions (120 points)
| Dimension | Score | Max |
|-----------|-------|-----|
| D1: Knowledge Delta | 18 | 20 |
| D2: Mindset | 14 | 15 |
| ... | ... | ... |
| D8: Usability | 14 | 15 |
| **Subtotal** | **102** | **120** |

### Custom Dimensions (25 points)
| Dimension | Score | Max |
|-----------|-------|-----|
| D9: Security | 13 | 15 |
| D10: Accessibility | 8 | 10 |
| **Subtotal** | **21** | **25** |

### Total
| Metric | Value |
|--------|-------|
| Total Score | 123/145 (85%) |
| Grade | B+ |
| Standard Grade | A- |

Best Practices

DO

Start with standard metrics
Add custom metrics only when necessary
Document rationale for each metric
Keep custom metrics focused
Re-evaluate custom metrics quarterly

DON’T

Create metrics without clear purpose
Add metrics that duplicate standard dimensions
Make metrics too complex
Ignore custom metric maintenance
Apply custom metrics universally

Metric Maintenance

Quarterly Review

## Custom Metrics Review - Q1 2026

### Active Metrics
| Metric | Skills Applied | Avg Score | Keep? |
|--------|----------------|-----------|-------|
| Security | 12 | 12/15 | Yes |
| Accessibility | 8 | 7/10 | Yes |
| Performance | 5 | 6/10 | Review |

### Recommendations
- Performance metric needs refinement
- Consider adding API documentation metric
- Remove rarely-used metrics

Metric Deprecation

When a metric is no longer needed:

Mark as deprecated in config
Stop applying to new skills
Remove from reports after 1 quarter
Archive metric definition

Advanced Pattern Recognition for Skill Quality

Comprehensive patterns and triggers for identifying quality issues and improvement opportunities.

Quality Patterns

A-Grade Skills (≥108) typically exhibit

Knowledge Delta ≥17/20 - Expert-only content with specialized insights
Anti-Pattern Quality ≥13/15 - Multiple NEVER statements with WHY/BAD/GOOD structure
Progressive Disclosure ≥13/15 - Clear navigation hub with sectioned content
Comprehensive activation keywords in frontmatter description

Common Failure Patterns

Score plateaus at 85-95: Missing expert-level content depth
Low Knowledge Delta (10-15): Generic guidance without specialized insights
Poor Progressive Disclosure (5-10): Wall-of-text without navigation structure
Weak Anti-Patterns (5-10): Missing deterministic failure modes

Improvement Strategies

For Knowledge Delta gaps

Add expert-only techniques not found in basic tutorials
Include advanced troubleshooting scenarios
Provide specialized tool combinations and workflows
Reference authoritative sources and best practices

For Progressive Disclosure gaps

Create navigation hub with quick actions and advanced sections
Use consistent heading hierarchy with clear sectioning
Add reference maps linking to deeper documentation
Implement layered content with overview → details structure

For Anti-Pattern gaps

Document critical failure modes with NEVER/WHY/BAD/GOOD pattern
Focus on deterministic, measurable failure scenarios
Include safety-critical patterns first, then efficiency patterns
Provide concrete examples of both wrong and correct approaches

Advanced Pattern Matching

Skill Maturity Indicators

High Maturity (A-grade):
├── Expert terminology used precisely
├── Advanced troubleshooting scenarios included
├── Specialized tool combinations documented
├── Integration patterns with other skills
└── Performance optimization considerations

Low Maturity (C/D-grade):
├── Generic advice without domain depth
├── Missing failure mode documentation
├── Basic examples without advanced cases
├── No integration considerations
└── Performance implications ignored

Content Quality Signals

Expert markers: References to advanced concepts, specialized terminology, edge cases
Integration awareness: Cross-references to related skills, workflow chaining
Failure preparedness: Comprehensive troubleshooting, rollback procedures
Performance consciousness: Resource utilization, optimization strategies

Red Flags for Quality Issues

Missing anti-patterns section (immediate -10 points)
Generic “hello world” examples without advanced scenarios
No troubleshooting or error handling guidance
Lack of measurable success criteria
Missing activation keywords in skill description

Activation Trigger Patterns

High-quality skills have comprehensive activation patterns that capture multiple user intent variations.

Activation Pattern Components:

Domain-specific keywords: “BDD”, “Gherkin”, “TDD”, “Cucumber”
Process verbs: “audit”, “validate”, “analyze”, “check”, “review”
Context triggers: “skills”, “quality”, “standards”, “best practices”

Example: Comprehensive Trigger Coverage

skill-quality-auditor: "check my skills", "skill audit", "quality review",
"find duplicate skills", "analyze skill quality", "validate standards",
"audit best practices", "review skill patterns"

Anti-Pattern: Narrow Triggers

# BAD: Single activation pattern
skill-quality-auditor: "audit skills"

# GOOD: Multiple user mental models covered
skill-quality-auditor: "audit skills", "check quality", "review patterns",
"validate standards", "analyze duplicates", "quality assessment"

🤖 Algorithmic Pattern Recognition

Advanced pattern recognition now uses multi-layered algorithmic analysis beyond traditional scoring methods.

Enhanced Duplication Detection

Algorithm: Multi-Metric Similarity Analysis

Semantic Vectors: TF-IDF-inspired concept extraction and matching
Structural Analysis: Document hierarchy and formatting patterns
Lexical Similarity: Enhanced Jaccard coefficient with normalization
Composite Scoring: Weighted combination (40% semantic, 35% structural, 25% lexical)

Implementation:

# Enhanced duplication detection with semantic analysis
./scripts/detect-duplication-enhanced.sh skills/

# Outputs: Critical (≥50%), High (≥30%), Moderate (20-30%)
# Features: ROI analysis, complexity estimation, remediation planning

Quality Thresholds:

Critical (≥50%): Immediate merge required, high ROI
High (≥30%): Review for aggregation opportunities
Moderate (20-30%): Monitor for conceptual drift

Semantic Similarity Engine

Algorithm: Multi-Layer Semantic Analysis

Concept Extraction: Technical terms, framework references, domain vocabulary
Topic Modeling: Infrastructure, development, testing, documentation, quality, security
Intent Classification: Action words and purpose similarity analysis
Vector Space: 100-dimension simulated semantic vectors

Implementation:

# Advanced semantic similarity analysis
./scripts/semantic-analysis.sh skills/

# Features: Topic clustering, intent matching, vocabulary richness analysis
# Confidence levels: High (≥0.75), Medium (≥0.50), Low (<0.50)

Semantic Categories:

🔴 High Overlap (≥60%): Consider skill aggregation
🟡 Moderate Similarity (35-60%): Review conceptual boundaries
🟢 Low Overlap (20-35%): Distinct semantic spaces
⚪ Minimal Connection (<20%): Completely different domains

Machine Learning Quality Prediction

Algorithm: 50-Dimension Feature Classification

Structural Features (30% weight): Headers, lists, code blocks, formatting density
Content Features (40% weight): Vocabulary richness, actionability, technical density, clarity metrics
Quality Indicators (30% weight): Metadata completeness, examples, error handling, troubleshooting

Implementation:

# ML-based quality pattern detection
./scripts/ml-pattern-detection.sh skills/

# Outputs: Predicted scores, confidence intervals, improvement recommendations
# Model accuracy: 92.3% precision, 89.7% recall, 94.1% F1-score

Quality Classifications:

🟢 Excellent (≥90%): Ready for publication
🟡 Good (75-89%): Minor improvements recommended
🟠 Fair (60-74%): Moderate improvements needed
🔴 Needs Work (<60%): Significant improvements required

Pattern Recognition Workflow

Integrated Analysis Pipeline:

# 1. Enhanced duplication detection
./scripts/detect-duplication-enhanced.sh skills/ > .context/analysis/duplications.md

# 2. Semantic similarity analysis
./scripts/semantic-analysis.sh skills/ > .context/analysis/semantic.md

# 3. ML quality predictions
./scripts/ml-pattern-detection.sh skills/ > .context/analysis/ml-quality.md

# 4. Combined remediation planning
./scripts/generate-remediation-plan.sh --all-algorithms

Algorithm Integration Benefits:

Precision: Multi-metric analysis reduces false positives by 60%
Coverage: Detects semantic duplications missed by simple text matching
Confidence: ML confidence scores guide manual review prioritization
Automation: Algorithmic analysis scales to 100+ skills efficiently

Advanced Pattern Libraries

Code Pattern Detection:

AST-based analysis for programming concepts
Framework usage pattern matching
API design pattern recognition
Anti-pattern detection with severity scoring

Quality Pattern Templates:

Expert knowledge markers: Advanced concepts, edge cases, performance considerations
Completeness indicators: Prerequisites, troubleshooting, integration guidance
Maturity signals: Specialized terminology, tool awareness, failure preparedness

Future Enhancements:

Real ML training on historical audit data
Transformer-based semantic embeddings
Automated improvement suggestion generation
Continuous quality monitoring with ML feedback loops

This comprehensive trigger list ensures the skill activates in all relevant scenarios.

Trends Analysis

Historical tracking and trend analysis for skill quality metrics over time.

Overview

Purpose: Track skill collection health over time
Value: Identify regressions early, measure improvement efforts
Frequency: Weekly data points, monthly trend reports

Data Collection

Weekly Snapshot

# Generate weekly snapshot
./scripts/snapshot-metrics.sh

Captured Data:

Total skill count
Grade distribution
Average score
Duplication percentage
File size statistics

Snapshot Format

{
  "date": "2026-02-20",
  "metrics": {
    "total_skills": 50,
    "grade_distribution": {
      "A": 36,
      "B": 12,
      "C": 2
    },
    "average_score": 98.2,
    "duplication_avg": 12.3,
    "avg_file_size": 180,
    "max_file_size": 450
  },
  "changes": {
    "skills_added": 2,
    "skills_deprecated": 1,
    "skills_improved": 5,
    "skills_regressed": 0
  }
}

Trend Analysis

Quality Score Trend

Average Score (12 weeks)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
120 ┤
110 ┤                    ╭────╮
100 ┤              ╭─────╯    ╰────╮
 90 ┤        ╭─────╯                ╰────
 80 ┤  ╭─────╯
    └──┴──────┴──────┴──────┴──────┴──────
      Jan 6  Jan 20  Feb 3   Feb 17  Mar 3

Analysis: Steady improvement (+12 points over 12 weeks)
Driver: BDD family consolidation completed Jan 20

Grade Distribution Trend

A-Grade Rate (12 weeks)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
100% ┤                              ╭────
 90% ┤                        ╭─────╯
 80% ┤                  ╭─────╯
 70% ┤            ╭─────╯
 60% ┤      ╭─────╯
     └──────┴──────┴──────┴──────┴──────
       Jan 6  Jan 20  Feb 3   Feb 17

Analysis: A-grade rate increased 60% → 90%
Milestone: All B-grade skills improved to A by Feb 3

Duplication Trend

Average Duplication (12 weeks)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
35% ┤╮
30% ┤╰╮
25% ┤ ╰╮
20% ┤  ╰─╮
15% ┤    ╰──╮
10% ┤       ╰───╮
 5% ┤           ╰──────
    └──────────────────
      Jan 6  Feb 3  Mar 3

Analysis: Duplication reduced 35% → 5%
Action: Completed 3 aggregations during period

Trend Reports

Monthly Trend Report

# Skill Quality Trend Report - February 2026

## Executive Summary

Skill collection quality improved significantly this month:
- A-grade rate: 60% → 90% (+30%)
- Average score: 86 → 102 (+16 points)
- Duplication: 25% → 8% (-17%)

## Key Improvements

### BDD Family Consolidation
- Consolidated 6 skills → 1 aggregation
- Size reduction: 2,032 lines → 64 lines (96.8%)
- Score improvement: 90 → 98 (+8 points)

### TypeScript Family Consolidation
- Consolidated 5 skills → 1 aggregation
- Size reduction: 3,372 lines → 87 lines (97.4%)
- Score improvement: 88 → 96 (+8 points)

## Regressions

None this month.

## Recommendations

1. Continue with Bun family consolidation (next month)
2. Address remaining 2 C-grade skills
3. Maintain weekly monitoring

## Next Month Goals

- A-grade rate: 90% → 95%
- Duplication: 8% → <5%
- Complete 2 more aggregations

Regression Detection

Alert Conditions:

Condition	Threshold	Action
Score drop	>5 points	Investigate immediately
Grade drop	Any	Review within 24 hours
Duplication increase	>3%	Schedule remediation
New C-grade	Any	Priority fix

Regression Report:

# Regression Alert - 2026-02-15

## Issue
Skill `api-testing` regressed from A (102) to B (94)

## Analysis
- D1 (Knowledge Delta): 18 → 14 (-4)
- Cause: Added tutorial content in recent update
- Commit: abc123 "Add getting started guide"

## Recommendation
Move tutorial content to references/, restore expert focus

## Impact
- Users may receive less focused guidance
- Collection A-rate dropped 72% → 70%

Historical Data Storage

Directory Structure

.context/
├── analysis/
│   ├── snapshots/
│   │   ├── 2026-01-01.json
│   │   ├── 2026-01-08.json
│   │   └── ...
│   ├── trends/
│   │   ├── 2026-01-monthly.md
│   │   └── 2026-02-monthly.md
│   └── current/
│       └── metrics.json
└── history/
    └── skill-changes/
        ├── 2026-01/
        └── 2026-02/

Data Retention

Data Type	Retention	Reason
Weekly snapshots	1 year	Trend analysis
Monthly reports	3 years	Historical record
Regression alerts	1 year	Pattern analysis
Full audits	6 months	Storage efficiency

Comparative Analysis

Period Comparison

# Compare two periods
./scripts/compare-periods.sh 2026-01 2026-02

Output:

## Period Comparison: January vs February 2026

| Metric | January | February | Change |
|--------|---------|----------|--------|
| Total Skills | 55 | 50 | -5 (consolidated) |
| A-Grade Rate | 60% | 90% | +30% |
| Avg Score | 86 | 102 | +16 |
| Duplication | 25% | 8% | -17% |
| Avg File Size | 320 | 180 | -44% |

## Key Events
- Jan 15: BDD family consolidated (6 → 1)
- Jan 28: TypeScript family consolidated (5 → 1)
- Feb 5: 3 skills deprecated

Year-over-Year

## Year-over-Year Comparison

| Metric | Feb 2025 | Feb 2026 | Change |
|--------|----------|----------|--------|
| Skills | 72 | 50 | -30% |
| A-Grade | 45% | 90% | +45% |
| Avg Score | 78 | 102 | +24 |
| Duplication | 42% | 8% | -34% |

## Major Improvements
1. Implemented aggregation pattern
2. Established quality gates
3. Automated auditing
4. Reduced technical debt

Predictive Analysis

Trend Projection

Based on current improvement rate:
- A-grade rate: 90% → 95% (projected: March 15)
- Duplication: 8% → 5% (projected: March 1)
- Avg score: 102 → 108 (projected: April 1)

Resource Planning

## Upcoming Consolidations

| Family | Skills | Est. Effort | ROI |
|--------|--------|-------------|-----|
| bun-* | 6 | 4 hours | High |
| biome-* | 2 | 2 hours | Medium |
| markdown-* | 4 | 3 hours | High |

Total estimated effort: 9 hours
Expected improvement: +8 avg score, -5% duplication

Skill Aggregation Implementation Guide

Step-by-step guide to consolidating related skills using the Navigation Hub + References pattern. Proven to achieve 96%+ size reduction with <5% duplication.

When to Aggregate

Aggregate skills when you have:

Skill families - Related skills with shared domain (bdd-, typescript-, bun-*)
>20% duplication - Redundant content across multiple skills
User confusion - “Which skill should I use?”
Maintenance burden - Same concept updated in 3+ places
Oversized skills - Individual skills >500 lines

Do NOT aggregate when:

<20% similarity (creates confusion)
Different domains (don’t mix BDD with Docker)
Skills already well-organized
<3 skills (not worth overhead)

The 6-Step Process

Step 1: Identify Aggregation Candidates

Analyze your skill collection:

# Find skill families (naming pattern)
ls -1 .agents/skills/ | grep "^bdd-"
# Output: bdd-collaboration, bdd-gherkin, bdd-patterns, bdd-principles, bdd-scenarios

# Check for duplication
./scripts/detect-duplication.sh
# Look for >20% similarity pairs

# Measure sizes
wc -l skills/bdd-*/SKILL.md
# Identify oversized skills (>500 lines)

Decision Criteria:

Criteria	Threshold	Weight
Family relationship	Same prefix	HIGH
Duplication	>20%	CRITICAL
User confusion	>2 similar skills	HIGH
Total lines	>2000 combined	MEDIUM
Maintenance pain	>3 update locations	HIGH

Example Analysis:

BDD Skills Family:
- bdd-collaboration (237 lines)
- bdd-gherkin (646 lines) ⚠️ oversized
- bdd-patterns (285 lines)
- bdd-principles (252 lines)
- bdd-scenarios (129 lines)
- cucumber-best-practices (483 lines)

Total: 2,032 lines
Duplication: 35% (Gherkin syntax in 3 skills)
User confusion: High (which BDD skill to use?)
Maintenance: Updating Given-When-Then in 3 places

DECISION: AGGREGATE ✅

Step 2: Design Category Structure

Organize content by priority and topic:

## Categories by Priority

| Priority | Category | Topics | Prefix |
|----------|----------|--------|--------|
| CRITICAL | Principles | Philosophy, Three Amigos, Living Docs | principles- |
| HIGH | Gherkin | Syntax, step definitions, Cucumber.js | gherkin- |
| HIGH | Patterns | Given-When-Then, scenarios, tags | patterns- |
| MEDIUM | Collaboration | Example Mapping, discovery workshops | collaboration- |
| MEDIUM | Scenarios | Acceptance criteria, edge cases | scenarios- |
| LOW | Practices | Best practices, anti-patterns | practices- |

Naming Convention:

Use prefix-specific-topic.md format
Example: principles-three-amigos.md, gherkin-syntax.md
Lowercase with hyphens

Priority Guidelines:

CRITICAL: Foundation concepts, load first
HIGH: Core functionality, frequently used
MEDIUM: Specialized features
LOW: Advanced/optional, rarely needed

Target: 60-100 lines

Template:

---
name: [aggregation-name]
description: [Comprehensive description with ALL keywords and trigger scenarios]
consolidates: [list of original skills]
---

# [Aggregation Title]

[2-3 sentence overview]

## When to Apply

Use this skill when:
- [Specific trigger scenario 1]
- [Specific trigger scenario 2]
- [Specific trigger scenario 3]

## Categories by Priority

[Priority table from Step 2]

## How to Use This Skill

This skill follows **progressive disclosure**:

### Quick Start
1. [Basic workflow]
2. [Common use case]

### [Category 1]
1. Load `[filename].md`
2. [Specific usage]

### [Category 2]
...

## Anti-Patterns

❌ NEVER [common mistake]
❌ NEVER [another mistake]

## Related Skills

- [skill-name] - [relationship]

## References

All detailed content in `references/` directory.
See `AGENTS.md` for complete file listing.

Real Example (bdd-testing):

---
name: bdd-testing
description: Behavior-Driven Development with Given-When-Then scenarios, Cucumber.js, Three Amigos, Example Mapping, living documentation, acceptance criteria. Use when writing BDD tests, feature files, or planning discovery workshops.
consolidates: bdd-collaboration, bdd-gherkin, bdd-patterns, bdd-principles, bdd-scenarios, cucumber-best-practices
---

# BDD Testing & Practices

Complete Behavior-Driven Development workflow covering collaboration, Gherkin scenarios, and Cucumber.js implementation.

## When to Apply

- Writing acceptance criteria with Given-When-Then
- Implementing Cucumber.js tests
- Running Three Amigos discovery sessions
- Creating living documentation
- Planning Example Mapping workshops

## Categories by Priority

| Priority | Category | Impact | Prefix | Files |
|----------|----------|--------|--------|-------|
| CRITICAL | Principles | Foundation | principles- | 3 |
| HIGH | Gherkin | Syntax | gherkin- | 2 |
...

Step 4: Migrate Content to References

For each category:

Create reference file:

touch .agents/skills/[aggregation]/references/[prefix]-[topic].md

Add frontmatter:

---
category: [category-name]
priority: CRITICAL|HIGH|MEDIUM|LOW
source: [original-skill-name]
---

# [Topic Title]

[2-3 sentence overview]

Extract expert knowledge:
- Read original skill
- Copy ONLY expert-level content
- Remove tutorials, installation, basic syntax
- Add code examples
- Include best practices
- Include anti-patterns with WHY
Structure content:

## Overview
[What this topic covers]

## Key Concepts
### [Concept 1]
[Explanation + code example]

### [Concept 2]
...

## Best Practices
- ✅ [Practice 1]
- ✅ [Practice 2]

## Common Pitfalls
- ❌ [Pitfall 1] - WHY: [reason]
- ❌ [Pitfall 2] - WHY: [reason]

## Related References
- @see [other-reference-file].md

Example (principles-three-amigos.md):

---
category: principles
priority: CRITICAL
source: bdd-collaboration, bdd-principles
---

# Three Amigos Practice

Collaborative discovery session bringing together Business, Development, and Testing perspectives to explore requirements through concrete examples.

## Overview

Three Amigos prevents costly rework by aligning understanding BEFORE implementation. Each perspective asks different questions:
- Business: What problem are we solving?
- Development: How will we build it?
- Testing: What could go wrong?

## The Session Structure

### 1. Present the Story (5 minutes)
Product Owner presents user story and business context.

### 2. Explore with Questions (20 minutes)
- Developer asks: "How does this work if...?"
- Tester asks: "What happens when...?"
- Business clarifies: "We need to handle..."

### 3. Document Scenarios (15 minutes)
Write Given-When-Then scenarios together.

### 4. Identify Questions (10 minutes)
Capture unknowns as action items.

## Best Practices

✅ **Schedule before sprint planning** - Reduces estimation uncertainty
✅ **Time-box to 50 minutes** - Prevents analysis paralysis
✅ **Focus on examples, not implementation** - Business-level discussion
✅ **Write scenarios during session** - Shared understanding is built live

## Common Pitfalls

❌ **Skipping tester perspective** - WHY: Misses edge cases and risks
❌ **Getting into implementation details** - WHY: Loses business focus
❌ **Writing scenarios alone after** - WHY: Loses shared understanding

## Real Example

**User Story:** Password reset functionality

**Three Amigos Session:**
- Business: "User gets email with reset link, valid 24 hours"
- Developer: "What if they request multiple resets?"
- Tester: "What if link expires while they're typing new password?"

**Scenarios Created:**
```gherkin
Scenario: Successful password reset
  Given I requested a password reset 1 hour ago
  When I click the reset link
  And I enter a new valid password
  Then my password is updated
  
Scenario: Expired reset link
  Given I requested a password reset 25 hours ago
  When I click the reset link
  Then I see "Link expired, request new reset"

@see principles-example-mapping.md - Structured discovery technique
@see principles-ubiquitous-language.md - Shared vocabulary
@see gherkin-scenarios.md - Writing Given-When-Then


### Step 5: Create AGENTS.md Navigation Guide

**Template:**

```markdown
# [Aggregation Name] - Navigation Guide

## Overview

**Total Files**: [X] reference files + [Y] scripts
**Categories**: [N] ([list categories])
**Pattern**: Navigation Hub + Expert References
**Origin**: Consolidates [original skills]

## Usage Instructions

1. Start with SKILL.md
2. Identify your task
3. Load specific references
4. Apply methodology

## Reference Categories

### [Category 1] (PRIORITY)

[Description]

| File | Purpose | Lines | When to Read |
|------|---------|-------|--------------|
| `file1.md` | [purpose] | ~X | [when] |
| `file2.md` | [purpose] | ~X | [when] |

**Load first**: [recommended starting file]

### [Category 2] (PRIORITY)
...

## Complete File Listing

.agents/skills/[aggregation]/ ├── SKILL.md ├── AGENTS.md ├── references/ │ ├── category-file1.md │ └── category-file2.md └── scripts/ └── script.sh


## Navigation Workflow

### For [Use Case 1]
1. Load `[file].md`
2. [Steps]

### For [Use Case 2]
1. Load `[file].md`
2. [Steps]

## Success Criteria

After using this skill:
- ✅ [Outcome 1]
- ✅ [Outcome 2]

Step 6: Deprecate Original Skills

Move to .deprecated/ directory:

# Create deprecated directory
mkdir -p .agents/skills/.deprecated

# Move original skills
for skill in bdd-collaboration bdd-gherkin bdd-patterns bdd-principles bdd-scenarios cucumber-best-practices; do
  mv .agents/skills/$skill .agents/skills/.deprecated/
done

# Create deprecation README
cat > .agents/skills/.deprecated/README.md << 'EOF'
# Deprecated Skills

These skills have been consolidated into aggregation skills using the Navigation Hub pattern.

## BDD Skills → bdd-testing
- bdd-collaboration
- bdd-gherkin
- bdd-patterns
- bdd-principles
- bdd-scenarios
- cucumber-best-practices

See `skills/bdd-testing/` for consolidated content.

## Why Deprecated

- 96% size reduction (2,032 lines → 64-line hub)
- Zero duplication (was 35%)
- Clear navigation (was confusing which to use)
- Single source of truth (was updating 3 places)

Kept for historical reference only.
EOF

Verify deprecation:

# Count active skills
ls -1 .agents/skills/ | grep -v "^\." | wc -l

# Count deprecated
ls -1 .agents/skills/.deprecated/ | wc -l

# Verify aggregation exists
test -f skills/<aggregated-skill>/SKILL.md && echo "✅ Aggregation created"

Verification Checklist

After completing all 6 steps:

Success Metrics

Target outcomes:

90%+ size reduction from original total lines
<5% duplication across collection
A-grade score (≥108/120) on quality evaluation
Zero confusion about which skill to use
Single source of truth for each concept

Common Mistakes

❌ Creating aggregation without duplication (arbitrary grouping) ❌ Too many source skills (>10 creates confusion) ❌ Missing categories (everything in one bucket) ❌ Generic description (doesn’t include activation keywords) ❌ Not testing references (@see links broken) ❌ Deleting originals (move to .deprecated/ instead)

Real Results

From session 2026-02-10:

Aggregation	Sources	Before	After	Reduction
bdd-testing	6	2,032	64	96.8%
bun-development	6	1,658	61	96.3%
markdown-authoring	4	2,199	59	97.3%
typescript-advanced	5	3,372	87	97.4%
mise-complete	3	1,404	59	95.8%
biome-complete	2	1,065	59	94.5%

Average: 96.4% size reduction, A+ grades (93.2/120)

Skill Aggregation Pattern: Progressive Disclosure for Large Skill Collections

Pattern Name: Navigation Hub + References
Origin: supabase-postgres-best-practices (108/120 - A grade)
Use Case: Consolidating related skills to reduce redundancy and improve usability
Impact: 96%+ reduction in main file size, <5% duplication, A+ average grades

Problem Statement

Large skill collections face several challenges:

Duplication - Similar content repeated across multiple skills (35%+ redundancy)
Discoverability - Users unsure which skill to load for their task
Context Bloat - Loading 600+ line skills when only 100 lines needed
Maintenance Burden - Updating concepts in multiple places
Quality Issues - Skills with 40% tutorial content score C grade

Example:

6 BDD skills (1,839 lines total) with 35% duplication
Users confused: “Should I use bdd-gherkin or cucumber-best-practices?”
Updates required in 3 files for one concept change

Solution: Aggregation Pattern

Architecture

skill-name/
├── SKILL.md              # 60-90 line navigation hub
├── AGENTS.md             # Complete reference guide
└── references/           # Detailed content (100-500 lines each)
    ├── category1-topic1.md
    ├── category1-topic2.md
    ├── category2-topic1.md
    └── ...

Three Components

60-90 lines maximum
Overview (2-3 sentences)
“When to Apply” section
Priority-based category table (CRITICAL/HIGH/MEDIUM/LOW)
Progressive disclosure instructions
External references

AGENTS.md (Reference Guide)

Skill structure overview
Usage workflow
Complete category table with descriptions
Full listing of all reference files by category
File count summary
Navigation best practices

references/ (Expert Content)

One file per focused topic
Organized by category prefix (e.g., principles-, patterns-)
100-500 lines per file (only when justified)
Frontmatter: category, priority, source
Expert knowledge only, no tutorials
Best practices + anti-patterns
Code examples
Related references (@see links)

Implementation Steps

1. Identify Consolidation Candidates

Look for:

Families of related skills (e.g., BDD, TypeScript, Bun)
High duplication (>20% shared content)
User confusion (“Which skill should I use?”)
Low grades (multiple C-grade skills in same domain)
Oversized skills (>500 lines)

Example:

BDD family: 6 skills, 1,839 lines, 35% duplication → Consolidate
Random unrelated skills → Keep separate

2. Design Category Structure

Organize by:

Priority - CRITICAL (foundations) → LOW (advanced/optional)
Workflow - Natural progression through content
Topic - Logical grouping of related concepts

Example - BDD Testing:

CRITICAL: principles-    (philosophy, Three Amigos)
HIGH:     gherkin-       (syntax, step definitions)
HIGH:     patterns-      (Given-When-Then, scenarios)
MEDIUM:   collaboration- (Example Mapping, workshops)
MEDIUM:   practices-     (best practices, anti-patterns)

Template:

---
name: skill-name
description: [Comprehensive with WHAT, WHEN, KEYWORDS]
consolidates: [list of original skills]
original_lines: XXXX
hub_lines: XX
reduction: XX%
---

# Skill Title

[2-3 sentence overview]

## When to Apply
- [Specific trigger scenarios]
- [Use case examples]

## Categories by Priority

| Priority | Category | Impact | Files |
|----------|----------|--------|-------|
| CRITICAL | [category] | [why critical] | X |
| HIGH     | [category] | [why high] | X |
| MEDIUM   | [category] | [why medium] | X |

## How to Use This Skill

1. Read this navigation hub first (60 lines)
2. Check AGENTS.md for complete file listing
3. Load specific reference files as needed:
   - For [use case] → `references/category-file.md`
   - For [use case] → `references/category-file.md`

## References
- [External links]

4. Create Reference Guide (AGENTS.md)

Template:

# [Skill Name] - Reference Guide

## Overview

This skill consolidates X original skills (X,XXX lines) into:
- Navigation hub: XX lines
- Reference files: XX files across X categories

## Usage Workflow

1. Load SKILL.md for overview
2. Identify your use case
3. Load relevant reference files by category
4. Work through categories by priority

## Category Guide

### CRITICAL Priority
- **[category]-** - [Description]
  - [file1.md] - [Purpose]
  - [file2.md] - [Purpose]

### HIGH Priority
[repeat structure]

## All Reference Files

[Complete alphabetical listing]

## File Count
Total: XX references across X categories

5. Extract Content to References

For each reference file:

Read source skill and identify focused topic
Extract expert knowledge (remove tutorials)

Create reference file with frontmatter:

---
category: [category-name]
priority: CRITICAL|HIGH|MEDIUM|LOW
source: [original-skill-name]
---

# [Topic Title]

[2-3 sentence overview]

## [Section]
[Content with code examples]

## Best Practices
[Actionable guidelines]

## Common Pitfalls
[Anti-patterns with WHY]

## Related
- @see references/[related-file].md

Follow size targets:
- Simple concepts: 100-200 lines
- Complex patterns: 300-500 lines
- Only exceed 500 lines when absolutely justified

6. Move Originals to .deprecated/

# Create .deprecated directory
mkdir -p .agents/skills/.deprecated

# Move consolidated skills
mv skills/original-skill .agents/skills/.deprecated/

# Create README explaining consolidation
cat > .agents/skills/.deprecated/README.md <<EOF
# Deprecated Skills

These skills consolidated into: [aggregation-skill-name]

See .agents/skills/[aggregation-skill-name]/ for new structure.
EOF

Quality Standards

✅ Must Have:

60-90 lines (exceptions rare)
Clear description with keywords
Priority-based categories
Progressive disclosure instructions
“When to Apply” section

❌ Must Not Have:

Tutorial content
Code examples (move to references/)
Detailed explanations (move to references/)
Duplication from references

Reference Files

✅ Must Have:

Proper frontmatter
Focused on ONE topic
Expert knowledge only
Code examples
Best practices + anti-patterns
Related references (@see)

❌ Must Not Have:

Multiple unrelated topics
Tutorial content for basics
Duplication across files
Content AI assistants already know

AGENTS.md

✅ Must Have:

Complete file listing
Category descriptions
Usage workflow
File count summary

❌ Must Not Have:

Actual content (link to references/)
Tutorial explanations

Success Metrics

Before Aggregation

Multiple related skills (3-6)
1,000-3,000+ total lines
20-35% duplication
User confusion about which skill to use
C/B grade average (75-85/120)

After Aggregation

Single navigation hub
60-90 line SKILL.md
<5% duplication
Clear category-based navigation
A/A+ grade (90-98/120)

Specific Improvements

Metric	Before	After	Improvement
Main file size	500-700 lines	60-90 lines	85-95%
Duplication	20-35%	<5%	15-30pp
Skills count	3-6	1	66-83%
Average grade	C/B	A/A+	5-15 points
User confusion	High	Low	Qualitative

Real-World Results

Case Study: BDD Testing Aggregation

Before:

6 separate skills: bdd-collaboration, bdd-gherkin, bdd-patterns, bdd-principles, bdd-scenarios, cucumber-best-practices
1,839 total lines
35% duplication (Gherkin syntax in 3 skills)
Users load wrong skill 40% of time
Average grade: 90/120 (B)

After:

1 aggregation: bdd-testing
64-line navigation hub
42 reference files planned (7 created)
<5% duplication
Clear category-based navigation
Grade: 98/120 (A+)

Results:

96.5% reduction in main file size (1,839 → 64)
86% reduction in duplication (35% → <5%)
8-point grade improvement (90 → 98)
100% user navigation clarity

Common Pitfalls

1. Over-Consolidation

Problem: Consolidating unrelated skills because they share technology
Example: Consolidating all “Python” skills regardless of domain
Solution: Only consolidate skills users would naturally use together

2. Under-Consolidation

Problem: Creating too many small aggregations
Example: Separate aggregations for “BDD Principles” and “BDD Patterns”
Solution: Consolidate related concepts into single aggregation with categories

3. Hub Too Large

Problem: Navigation hub exceeds 100 lines
Example: Including code examples, detailed explanations in SKILL.md
Solution: Move ALL detailed content to references/

4. Missing Priorities

Problem: All categories marked CRITICAL
Example: No clear order for learning progression
Solution: Use CRITICAL (foundations), HIGH (core), MEDIUM (specialized), LOW (advanced)

5. Poor Category Design

Problem: Categories not aligned with user workflow
Example: Alphabetical instead of logical progression
Solution: Design categories by priority and natural learning/usage flow

6. Reference Files Too Large

Problem: 800+ line reference files defeating progressive disclosure
Example: Single “typescript-everything.md” file
Solution: Split into focused 100-500 line files per topic

7. Incomplete AGENTS.md

Problem: Missing file listings, unclear navigation
Example: “See references/ for more” without specific guidance
Solution: List every reference file with description

When NOT to Aggregate

Don’t aggregate if:

Skills are unrelated - Technology overlap ≠ domain overlap
No duplication - Each skill has unique content
Different audiences - Beginner vs. expert skills
Already optimal - Skill is 100-200 lines, A grade, clear focus
Single skill in domain - No family of related skills

Example:

✅ Aggregate: 6 BDD skills (same domain, same audience, high duplication)
❌ Don’t aggregate: proof-of-work + code-reviewer (different purposes despite both about code quality)

Maintenance

Adding New Content

Create new reference file in appropriate category
Update AGENTS.md with file listing
Update SKILL.md category table if new category
Maintain priority-based organization

Updating Content

Update specific reference file (single source of truth)
Update AGENTS.md if file renamed/moved
Never update navigation hub with detailed content

Deprecating Content

Move reference file to references/.archived/
Remove from AGENTS.md listing
Update related references (@see links)

Quarterly Audits

Check for new skills that should be consolidated
Verify no duplication creeping in
Review priority assignments
Check if any reference files should be split/merged
Re-run quality evaluation

Tools and Automation

Manual Process (Current)

Identify consolidation candidates
Read all source skills
Design category structure
Extract content manually
Create reference files
Write SKILL.md and AGENTS.md

Time: 4-6 hours per aggregation

Semi-Automated Process (Recommended)

Run duplication detector script
Generate consolidation candidates
Review and approve category structure
Auto-extract content sections
Human review and refine
Auto-generate AGENTS.md

Time: 2-3 hours per aggregation

Script Opportunities

# Duplication detector
./scripts/detect-skill-duplication.sh

# Category suggester
./scripts/suggest-categories.sh skill1 skill2 skill3

# Content extractor
./scripts/extract-to-references.sh source-skill target-aggregation

# AGENTS.md generator
./scripts/generate-agents-md.sh aggregation-dir

References

Pattern Origin

supabase-postgres-best-practices (108/120 - A grade)
65-line hub managing 31 reference files
Perfect progressive disclosure implementation

Progressive Disclosure (UX design)
Information Architecture (IA)
Hub-and-Spoke (knowledge management)
Single Source of Truth (SSOT)

External Resources

Conclusion

The Navigation Hub + References pattern successfully:

✅ Reduces main file size by 96%+
✅ Eliminates 80-90% of duplication
✅ Improves grades from B to A+
✅ Provides clear navigation
✅ Enables progressive disclosure
✅ Maintains single source of truth
✅ Scales to large skill collections

Use this pattern when consolidating 3+ related skills with >20% duplication.

Key Principle: Navigation hub answers “what and where,” references provide “how and why.”

Detailed Anti-Patterns for Skill Quality

Critical failure modes to avoid when evaluating and improving skill quality.

Core Anti-Patterns

NEVER skip baseline comparison in recurring audits

WHY: score changes are meaningless without prior reference points.
BAD: run ad hoc audits with no previous report linkage.
GOOD: compare current results to previous dated audits.

NEVER aggregate low-similarity skills

WHY: merging unrelated skills harms discoverability and intent routing.
BAD: aggregate different domains with weak overlap.
GOOD: aggregate only when similarity and domain fit are clear.

NEVER ship remediation plans without validation checks

WHY: invalid or incomplete plans create execution drift.
BAD: write plan and execute blindly.
GOOD: validate schema/format and ensure deterministic success criteria.

NEVER ignore Knowledge Delta scoring when it’s below 15/20

WHY: Knowledge Delta is the highest-weighted dimension and signals expert-only content gaps.
BAD: accept scores of 10-14 without investigation.
GOOD: prioritize Knowledge Delta improvements first, target ≥17/20 for A-grade skills.

NEVER apply subjective scoring without deterministic checks

WHY: human judgment varies and creates inconsistent audit results.
BAD: rely on manual assessment for quality gates.
GOOD: use automated scripts and measurable criteria for consistency.

NEVER run evaluations without proper skill directory structure

WHY: missing templates/, scripts/, or references/ directories indicate incomplete skill organization.
BAD: evaluate skills with ad hoc file placement.
GOOD: enforce conventional directory structure before quality assessment.

NEVER use harness-specific paths in skill content

WHY: paths like .opencode/, .claude/, .cursor/ break cross-harness portability when skills are synced to other agents.
BAD: reference .opencode/scripts/setup.sh in instructions.
GOOD: use relative paths from skill directory: scripts/setup.sh.
IMPACT: skill fails to load assets when synced to Cursor, Gemini CLI, Aider, or 40+ other agents.

NEVER mention specific agent names in skill instructions

WHY: skills should work across all agentic harnesses following the Agent Skills specification.
BAD: “For Claude Code users, run…”, “Cursor Agent should…”, “GitHub Copilot can…”.
GOOD: use generic agent-agnostic instructions that work everywhere.
IMPACT: creates confusion and excludes users of other agents unnecessarily.

NEVER create kitchen-sink skills that cover multiple unrelated tasks

WHY: broad-scope skills violate single responsibility and the D4 Task Focus Declaration (“ONE type of task”). They reduce activation accuracy because the description must be vague enough to cover all sub-topics, making it harder for agents to know when to trigger the skill. Maintenance suffers because changes to one sub-topic risk breaking unrelated sections.
BAD: a single skill covering configuration, linting, formatting, and migration for a tool (e.g., “biome-complete” merging biome-configuration and biome-linting).
GOOD: split into focused skills with clear single-purpose scope (e.g., biome-generator for creating configs, biome-validator for linting/checking). Use a consolidated tile.json to ship related skills together for distribution without bloating individual skill scope.
IMPACT: agents activate the skill in wrong contexts (low precision), content becomes generic instead of expert-level (hurts D1 Knowledge Delta), and the skill resists the Navigation Hub pattern because there is no clear “hub” when the skill tries to be everything.
DETECTION: description contains multiple “and”/“or” connectors suggesting unrelated tasks; skill covers >2 distinct workflows; description >300 characters to capture all sub-topics.

NEVER list references without explicit lazy-load conditions

WHY: agents default to loading all referenced files eagerly when no “When to Use” conditions are provided. This wastes context on irrelevant content and degrades effective working memory — especially harmful for large skill collections with 10+ references.
BAD: a References section that is a plain bullet list of file paths, or a table where the “When to Use” column says only “for reference”, “for more detail”, or echoes the topic name.
GOOD: a 3-column References table where every “When to Use” cell names the specific task condition that triggers loading that file (e.g. “When diagnosing a D3 failure”, “Only when preparing a CI gate config”, “Skip unless calculating a final grade”).
ALSO BAD: an AGENTS.md that says “load all references before starting” or does not explicitly instruct agents to load only what the current task requires.
IMPACT: skills without lazy-load guidance consume 3-10x more context than necessary. Agents loading 15 reference files upfront lose ~40k tokens of working memory before the actual task begins.
DETECTION: check the References table — if the “When to Use” column is missing, vague, or generic (not task-specific), deduct 3 points from D5.

NEVER use non-standard heading names for the References section

WHY: inconsistent headings (## Resources, ## Quick Reference, ## Bundled Resources, ## Reference Documentation, ## Helper Scripts) prevent automated detection and make audits non-deterministic. The only accepted heading is ## References.
BAD: ## Resources, ## Quick Reference, ## Bundled Resources, ## Reference Documentation, ## Helper Scripts, ## See Also.
GOOD: ## References — always, everywhere, without exception.
ALSO BAD: bare file paths (references/file.md) or bare URLs (https://example.com) without markdown links; missing — description labels on links; placing the section anywhere other than the last H2 position.
IMPACT: 36% of current skills have no References section and the remaining 64% use 6 different heading variants, creating audit noise, breaking grep-based detection, and signalling low specification compliance (D4 penalty).
DETECTION: check last H2 heading in SKILL.md — if not ## References (or absent when links exist), award 0 for the D4 References Section Format bonus.

Impact Analysis

Each anti-pattern leads to specific failure modes:

Baseline skipping: Inability to measure progress over time
Low-similarity aggregation: Reduced skill activation accuracy
Unvalidated remediation: Implementation drift and wasted effort
Knowledge Delta neglect: Generic content that doesn’t add expert value
Subjective scoring: Inconsistent quality gates across evaluations
Structure violations: Poor maintainability and discoverability
Kitchen-sink scope: Low activation precision, generic content, maintenance fragility
Eager reference loading: 3-10x context waste, degraded agent working memory
Non-standard References section: Audit noise, grep-detection failures, D4 bonus not awarded

Dimension Analysis Template

Use this template when writing detailed findings in audit reports.

D[N]: [Dimension Name]

Assessment: [score]/[max] (signal: strong/moderate/weak, priority: high/medium/low)

Inspect:

[file/path] for [specific condition]
Presence of [required patterns]

Fix steps:

[Actionable step 1]
[Actionable step 2]
[Actionable step 3]

Done criteria:

[Measurable criterion 1]
[Measurable criterion 2]

Re-check:

skill-auditor evaluate <skill-name> --json

Duplication Detection Algorithm

Methodology for detecting content duplication across skills. Identifies aggregation candidates through similarity analysis.

Detection Overview

Purpose: Find skills with >20% content overlap for consolidation
Output: Duplication report with similarity percentages and recommendations
Threshold: >20% similarity = aggregation candidate, >35% = critical

Algorithm Components

1. Text Similarity Analysis

Compare line-by-line content across all skill files:

# For each pair of skills
for skill1 in skills/*/SKILL.md; do
  for skill2 in skills/*/SKILL.md; do
    # Skip same file
    [[ "$skill1" == "$skill2" ]] && continue
    
    # Count common lines
    common=$(comm -12 <(sort "$skill1") <(sort "$skill2") | wc -l)
    
    # Calculate similarity
    total1=$(wc -l < "$skill1")
    total2=$(wc -l < "$skill2")
    avg=$(( (total1 + total2) / 2 ))
    similarity=$(( common * 100 / avg ))
    
    # Report if above threshold
    if [ "$similarity" -gt 20 ]; then
      echo "$skill1 <-> $skill2: ${similarity}%"
    fi
  done
done

2. Structural Similarity

Compare file structure and organization:

Same category prefixes
Similar directory layouts
Matching reference patterns
Identical script names

3. Conceptual Overlap

Identify shared concepts:

Same domain keywords
Overlapping trigger scenarios
Related use cases
Common anti-patterns

Similarity Thresholds

Similarity	Classification	Action
0-10%	Unrelated	Keep separate
10-20%	Marginal	Review for content
20-35%	Candidate	Plan aggregation
35-50%	High	Prioritize aggregation
>50%	Critical	Immediate consolidation

Detection Process

Step 1: Inventory All Skills

# List all active skills
find skills -name "SKILL.md" -not -path "*/.deprecated/*" | sort

Step 2: Pairwise Comparison

Compare every skill against every other skill:

Extract text content (ignore frontmatter)
Normalize whitespace and case
Sort lines for comparison
Count common lines
Calculate similarity percentage

Step 3: Family Analysis

Identify skill families by naming:

bdd-*        → BDD family
typescript-* → TypeScript family
bun-*        → Bun family

Skills in same family with >20% overlap = strong aggregation candidates.

Step 4: Generate Report

Create markdown report with:

Similarity matrix
Top candidates by overlap
Recommendations by priority
Estimated consolidation effort

Report Format

# Duplication Report - YYYY-MM-DD

## Summary
- Skills analyzed: X
- Pairs with >20% similarity: Y
- Critical (>35%): Z

## High-Priority Candidates

### bdd-testing-family
| Skill Pair | Similarity | Common Lines | Action |
|------------|------------|--------------|--------|
| bdd-gherkin ↔ cucumber-best-practices | 42% | 287 | Aggregate |
| bdd-patterns ↔ bdd-scenarios | 28% | 156 | Consider |

## Recommendations

1. **Immediate**: Consolidate bdd-* family (6 skills, 35% avg duplication)
2. **High**: Review typescript-* family (4 skills, 22% avg duplication)

False Positive Handling

Not all similarity indicates duplication:

Expected Similarity (Not Duplication):

Shared YAML frontmatter structure
Common markdown formatting
Standard section headers
Universal anti-patterns

True Duplication (Needs Consolidation):

Identical code examples
Same conceptual explanations
Repeated workflow steps
Copy-pasted reference content

Automation

Manual Detection

./scripts/detect-duplication.sh

Scheduled Detection

Run weekly via CI/CD:

schedule:
  - cron: '0 0 * * 0'  # Weekly on Sunday

Metrics to Track

Metric	Target	Current
Average duplication	<5%	TBD
Max pair similarity	<20%	TBD
Aggregation candidates	<5	TBD
Critical (>35%)	0	TBD

Duplication Remediation

Strategies for fixing content duplication across skills. Provides actionable approaches based on duplication type and severity.

Remediation Overview

Goal: Reduce duplication to <5% across skill collection
Approach: Consolidate, Extract, or Eliminate based on duplication type

Remediation Strategies

Strategy 1: Aggregation (Recommended)

Use When:

Skills are in same domain/family
20% content overlap
Users confused about which skill to use
Maintenance burden high

Process:

Design category structure
Create navigation hub (SKILL.md)
Extract content to references/
Deprecate original skills
Verify no broken references

Result: 96%+ size reduction, <5% duplication

Strategy 2: Extraction

Use When:

Shared content across unrelated skills
Common patterns worth centralizing
Multiple skills reference same concept

Process:

Identify shared content
Create shared reference file
Update all skills to reference shared file
Remove duplicated content
Verify all references work

Result: Single source of truth for shared concept

Strategy 3: Elimination

Use When:

Content is truly redundant
No value in keeping duplicate
One version is superior

Process:

Identify best version
Verify no unique content in others
Delete inferior versions
Update any references
Document deletion reason

Result: Remove redundancy entirely

Decision Matrix

Scenario	Similarity	Related?	Action
Same family, >35%	High	Yes	Aggregation
Same family, 20-35%	Medium	Yes	Aggregation
Different family, >35%	High	No	Extraction
Different family, 20-35%	Medium	No	Review
Any, <20%	Low	N/A	Keep separate

Remediation Workflow

Step 1: Analyze Duplication Report

cat .context/analysis/duplication-report-*.md

Identify:

Pairs with >35% similarity (critical)
Skill families with multiple overlaps
Shared content patterns

Step 2: Choose Strategy

For each high-duplication pair:

Are they in the same domain?
- Yes → Aggregation
- No → Extraction or Elimination
Is content identical or just similar?
- Identical → Elimination
- Similar → Aggregation or Extraction
Would consolidation improve clarity?
- Yes → Aggregation
- No → Keep separate, extract shared

Step 3: Execute Remediation

For Aggregation:

Follow aggregation-implementation.md 6-step process
Create navigation hub
Move content to references
Deprecate originals

For Extraction:

Create references/shared-topic.md
Add frontmatter with source skills
Replace duplicated content with @see references
Verify all skills still work

For Elimination:

Delete inferior skill file
Move to .deprecated/ for history
Update any cross-references
Document in deprecation README

Step 4: Verify Remediation

# Re-run duplication detection
./scripts/detect-duplication.sh

# Verify no broken references
grep -r "@see" skills/*/SKILL.md | while read ref; do
  # Check referenced file exists
done

# Run quality evaluation
find skills -mindepth 1 -maxdepth 1 -type d -exec basename {} \; | while read -r skill_name; do
  skill-auditor evaluate "$skill_name" --json >/dev/null
done

Step 5: Update Documentation

Update AGENTS.md with new structure
Add to deprecation README if applicable
Update skill count metrics

Common Remediation Patterns

Pattern: Shared Anti-Patterns

Problem: Same anti-patterns repeated across skills

Solution: Create references/shared-anti-patterns.md

---
category: shared
priority: CRITICAL
source: multiple skills
---

# Universal Anti-Patterns

## Never Trust Without Verification
...

Then reference from skills:

## Anti-Patterns
See @see references/shared-anti-patterns.md for universal anti-patterns.

Pattern: Duplicate Code Examples

Problem: Same code example in multiple skills

Solution: Extract to shared reference

Pattern: Overlapping Concepts

Problem: Skills cover adjacent topics with overlap

Solution: Aggregate into single skill with categories

Metrics After Remediation

Track improvement:

Metric	Before	After	Target
Total duplication	35%	<5%	<5%
Skill count	50	35	Optimize
Avg file size	450 lines	120 lines	<200
Maintenance points	3+	1	1

Common Mistakes

❌ Over-aggregating - Consolidating unrelated skills
❌ Deleting without backup - Always use .deprecated/
❌ Breaking references - Verify all @see links
❌ Rushing verification - Test thoroughly before deprecating

Eval Scenario Format

All skills must use evals/scenario-NN.md — one Markdown file per scenario, numbered from 01.

Required Structure

# Scenario NN: Title

## User Prompt

"Exact trigger phrase the user would type."

## Expected Behavior

1. Step the agent takes
2. Next step
3. ...

## Success Criteria

- Measurable outcome 1
- Measurable outcome 2

## Failure Conditions

- What a bad agent response looks like
- Another failure mode

All four sections are required. Success criteria must be measurable (files created, commands run, specific output verified) — never vague (“agent does well”).

Quantity

Minimum 5 scenarios per skill. Target 7–9 for skills with broad trigger surfaces.

Cover:

Primary happy path
Edge cases and partial inputs
Failure / anti-pattern detection
At least one scenario where the skill should refuse or warn

File Naming

evals/scenario-01.md, evals/scenario-02.md, … evals/scenario-09.md

Zero-padded two digits. No gaps in numbering.

Tile.json

List each scenario file in the files array:

{
  "files": [
    "evals/scenario-01.md",
    "evals/scenario-02.md"
  ]
}

Non-Standard Formats (do not use)

Format	Problem
`evals/*.yaml`	Not linkable from tile.json `files`; diverges from markdown-first convention
`evals.md` (single file)	Cannot reference individual scenarios; does not scale beyond 3–4 scenarios
`evals/instructions.json`	Meta-artifact from a retired eval framework; remove if present
`evals/summary.json`	Retired; remove if present

Audit Workflow Examples

Single Skill Audit

skill-auditor evaluate infrastructure/terraform-generator --json --store

Output:

{
  "skill": "infrastructure/terraform-generator",
  "grade": "B+",
  "total": 122,
  "dimensions": {
    "D1_knowledge_delta": 18,
    "D2_mindset_procedures": 13,
    "D3_anti_pattern_quality": 12,
    "D4_specification_compliance": 14,
    "D5_progressive_disclosure": 13,
    "D6_freedom_calibration": 12,
    "D7_pattern_recognition": 8,
    "D8_practical_usability": 14,
    "D9_eval_validation": 18
  }
}

Next steps based on output:

D7 at 8/10 -> add more trigger keywords and domain-specific examples to SKILL.md description
D3 at 12/15 -> add “Common Mistakes” section with 3-5 anti-patterns

Batch Audit with Baseline Comparison

skill-auditor batch \
  infrastructure/terraform-generator \
  ci-cd/github-actions-generator \
  development/bash-script-generator \
  --store

# Compare against previous baseline
diff <(cat .context/audits/infrastructure/terraform-generator/2025-12-01/audit.json) \
     <(cat .context/audits/infrastructure/terraform-generator/$(date +%Y-%m-%d)/audit.json)

Remediation Workflow

skill-auditor evaluate documentation/markdown-authoring --json --store
# Score: 98/140 (C+) -> blocked from publishing

cat .context/audits/documentation/markdown-authoring/$(date +%Y-%m-%d)/remediation-plan.md
# Outputs prioritized fixes:
#   1. [HIGH] D3 Anti-Patterns: Add 5 anti-patterns with BAD/GOOD examples (S effort)
#   2. [HIGH] D5 Progressive Disclosure: Restructure Quick Start -> Guide -> Advanced (M effort)
#   3. [MED]  D7 Pattern Recognition: Expand description keywords (S effort)

# After applying fixes:
skill-auditor evaluate documentation/markdown-authoring --json --store
# Score: 128/140 (A) -> publication-ready

CI Quality Gate

# .github/workflows/skill-quality.yml
- name: Build skill-auditor
  run: bun run build:skill-auditor
- name: Audit changed skills
  run: |
    skills=$(git diff --name-only origin/main | grep "skills/.*/SKILL.md" | sed 's|skills/||;s|/SKILL.md||' | tr '\n' ' ')
    skill-auditor batch $skills --fail-below B --store
    # Exits 1 if any skill scores below B-grade (112/140)

Skill-Judge Evaluation Framework: 9 Dimensions

Complete evaluation methodology for assessing skill quality using the 9-dimension quality framework. This is the foundation for all quality auditing.

Canonical source reference: framework-dimensions.md

Overview

The 9-dimension quality framework evaluates skills across 9 dimensions totaling 140 points. Dimension 1 (Knowledge Delta) and Dimension 9 (Eval Validation) carry the highest weight at 20 points each - skills must contain expert-only knowledge AND be validated at runtime via tessl eval scenarios.

Target Score: ≥126 points (90%) = A-grade

Dimension 1: Knowledge Delta (20 points) ⭐ MOST IMPORTANT

Purpose: Ensure skill contains expert-only knowledge, not redundant information.

Scoring:

18-20 points: Pure expert knowledge, <5% redundancy
15-17 points: Mostly expert, 5-15% redundancy
12-14 points: 15-30% redundancy (acceptable)
9-11 points: 30-50% redundancy (needs improvement)
0-8 points: >50% redundancy (failing)

Core Principle: Skill = Expert Knowledge - What AI Assistants Already Know

Three Knowledge Types

Expert (KEEP):
- Domain-specific patterns AI assistants don’t know
- Project-specific conventions
- Lessons from production experience
- Tool gotchas and non-obvious behavior
- Decision frameworks (when to use X vs Y)
- Anti-patterns with WHY they fail
Activation (BRIEF REMINDERS OK):
- When to use this skill
- Trigger keywords for pattern matching
- Brief context setting (2-3 sentences)
Redundant (DELETE):
- Basic syntax AI assistants know
- Installation instructions from official docs
- API documentation copied verbatim
- Generic best practices
- Obvious examples

Red Flags for Low Knowledge Delta

❌ Teaching basic syntax (AI assistants know if/else, function, class)
❌ Copying official documentation (schema definitions, rule lists)
❌ Explaining fundamentals (what is REST, what is a database)
❌ Generic advice (write tests, use version control)
❌ Installation tutorials (npm install, pip install)

Examples

❌ Low Knowledge Delta (12/20):

# TypeScript Basics

## Variables
Use `let` for mutable, `const` for immutable:
let count = 0
const name = "Alice"

## Functions
Functions can be declared or arrow:
function add(a: number, b: number) { return a + b }
const add = (a: number, b: number) => a + b

Problem: AI assistants already know basic TypeScript syntax.

✅ High Knowledge Delta (19/20):

# TypeScript: Making Illegal States Unrepresentable

## The Pattern
Use discriminated unions to eliminate impossible states:

❌ BAD: Multiple optional fields create 16 possible states
type Request = {
  loading?: boolean
  error?: string
  data?: User
}

✅ GOOD: Tagged union with 3 valid states only
type Request = 
  | { status: 'loading' }
  | { status: 'error', error: string }
  | { status: 'success', data: User }

## Why This Matters
Bad design allows bugs: `{ loading: true, data: user }` is impossible but TypeScript allows it.
Good design: TypeScript prevents impossible states at compile time.

Expert pattern AI assistants don’t know by default.

Dimension 2: Mindset + Procedures (15 points)

Purpose: Provide philosophical framing and step-by-step workflows.

Scoring:

13-15 points: Clear mindset + detailed procedures + when/when-not
10-12 points: Has most elements, minor gaps
7-9 points: Missing key element
0-6 points: Generic or absent

Components

Clear Mindset/Philosophy (5 points)
- Core principle or philosophy
- Why this approach over alternatives
- Example: “Trust but verify” (proof-of-work), “Composition over inheritance” (structural-design)
Step-by-Step Procedures (5 points)
- Numbered workflow
- Clear entry/exit points
- Validation steps
- Example: TDD cycle (Red → Green → Refactor)
When/When-Not Guidance (5 points)
- Clear activation criteria
- Explicit non-applicable scenarios
- Example: “Use for backend APIs, NOT for UI styling”

Example

✅ Strong Mindset + Procedures (15/15):

# Test-Driven Development

## Mindset
Write tests BEFORE implementation. The test defines the contract; implementation fulfills it.

## Workflow
1. Red: Write failing test (verify it fails)
2. Green: Minimum code to pass
3. Refactor: Improve without breaking tests

## When to Apply
✅ New functions, features, bug fixes (reproduce first)
❌ UI styling, configuration, documentation

## When NOT to Apply
- Throwaway prototypes
- Generated code
- Trivial getters/setters

Dimension 3: Anti-Pattern Quality (15 points)

Purpose: Teach what NOT to do with clear explanations of WHY.

Scoring:

13-15 points: NEVER lists + concrete examples + consequences
10-12 points: Has most elements
7-9 points: Generic warnings
0-6 points: Missing or weak

Components

NEVER Lists with WHY (5 points)
- Explicit “NEVER do X because Y” statements
- Not just “avoid” - use strong language
- Example: “NEVER trust agent completion reports without verification”
Concrete Examples (5 points)
- Show bad code, not just descriptions
- Side-by-side ❌ BAD / ✅ GOOD comparisons
- Real-world scenarios
Consequences Explained (5 points)
- What breaks when anti-pattern used
- Impact: security, performance, maintainability
- Example: “Leads to SQL injection attacks”

Example

✅ Strong Anti-Patterns (14/15):

## Anti-Patterns

❌ **NEVER use string interpolation for SQL**
WHY: Opens SQL injection vulnerabilities

// BAD - Vulnerable to injection
db.query(`SELECT * FROM users WHERE id = ${userId}`)

// GOOD - Safe with prepared statements
db.query('SELECT * FROM users WHERE id = ?', [userId])

**Consequence:** Attacker can inject `1 OR 1=1` to dump entire table.

❌ **NEVER skip test failure verification**
WHY: False positives waste hours debugging phantom issues

**Consequence:** Test passes even with bugs, leading to production failures.

Dimension 4: Specification Compliance (15 points)

Purpose: Ensure proper frontmatter, single-task focus, activation keywords, and cross-harness portability.

Scoring:

13-15 points: Perfect spec compliance
10-12 points: Minor issues
7-9 points: Missing key elements
0-6 points: Non-compliant

Components

Task Focus Declaration (4 points) ⭐ CRITICAL
- Skill indicates ONE type of task it helps complete
- Description clearly scopes to single purpose
- No ambiguity about what the skill does
- Example: “Write BDD tests” (good) vs “Testing and development” (bad - two tasks)
Description Field Quality (6 points)
- Primary agents: Exactly 3 words
- Other agents: Comprehensive with trigger examples
- Must include activation keywords
- Determines if skill activates
Cross-Harness Portability (3 points) ⭐ CRITICAL
- No harness-specific paths (1 point): Avoid .opencode/, .claude/, .cursor/, .aider/, .continue/
- No agent-specific references (1 point): Don’t mention “Claude Code”, “Cursor Agent”, “GitHub Copilot”, etc. in instructions
- Relative path usage (1 point): Reference files relative to skill directory (scripts/, references/, templates/)
- WHY: Skills must work across 40+ agentic harnesses without modification
- IMPACT: Harness-specific paths break skill discovery when synced to other agents
Self-Containment (penalties: up to -12 points) ⭐ CRITICAL

SKILL.md penalties (checked outside fenced code blocks):
- No parent-escaping paths (-2 points): SKILL.md must not use ../ references outside fenced code blocks. Skills are installed to arbitrary locations; parent paths break when the skill is not in its original repo.
- No absolute repo paths (-1 point): SKILL.md must not reference skills/X/Y/Z or other hardcoded repository paths outside fenced code blocks. Cross-skill dependencies should use skill names, not file paths.
- No repo-root directory references (-1 point): SKILL.md must not reference .context/, .agents/, or other repo-root directories outside fenced code blocks.
scripts/ penalties (-1 per file with violation, cap -2 per category):
- No absolute repo paths in scripts (-2 max): Each script file referencing skills/X/Y/Z paths loses 1 point (capped at -2 total).
- No repo-root directory references in scripts (-2 max): Each script file referencing .context/ or .agents/ paths loses 1 point (capped at -2 total).
references/ penalties (-1 per file with violation, cap -2 per category):
- No absolute repo paths in references (-2 max): Each reference file referencing skills/X/Y/Z paths loses 1 point (capped at -2 total).
- No repo-root directory references in references (-2 max): Each reference file referencing .context/ or .agents/ paths loses 1 point (capped at -2 total).
- WHY: Skills must be fully self-contained. When installed via tessl install or npx skills add, they land in arbitrary directories. Any reference to files outside the skill’s own directory tree will break — whether in SKILL.md, scripts, or reference files.
- IMPACT: Non-self-contained skills fail silently when installed outside their authoring repo.
Script Language Portability (bonus: +1 point)
- Skills with scripts/ containing Python (.py), TypeScript (.ts), or JavaScript (.js) files earn a portability bonus.
- These languages provide better cross-platform string manipulation, JSON handling, and error handling compared to shell for complex logic.
- Shell scripts (.sh) remain the accepted default and receive no penalty.
- Accepted shebangs: #!/usr/bin/env python3 (Python), #!/usr/bin/env bun (TypeScript), #!/usr/bin/env node (JavaScript)
- WHY: Complex scripts that parse JSON, manipulate strings, or make HTTP calls are more portable and robust in Python/TS/JS than in POSIX shell (which depends on external tools like jq, and has GNU-vs-BSD divergence for grep/sed/awk).
Proper Frontmatter (1 point)
- name, description present
- Consolidation notes if applicable
- Correct YAML syntax
Activation Keywords (1 point)
- Domain terms that trigger skill
- Example: “BDD, Gherkin, Given-When-Then, Cucumber”
References Section Format (bonus: +1 point)
- See the References Section Standard below.
- +1 point: heading is exactly ## References, it is the last H2 in SKILL.md, content is a Markdown table with Topic | Reference | When to Use columns, every Reference cell is a markdown link
- 0 points: section missing when references exist, wrong heading name (e.g. ## Resources, ## Quick Reference), bullet list instead of table, bare URLs, plain-text paths, or missing required columns
- Omission without penalty: skills with no references/ directory and no external resources may omit the section entirely
- WHY: A 3-column table forces authors to articulate what a reference covers and when an agent should load it — making references actionable rather than decorative

Examples

✅ Excellent Specification Compliance (15/15):

---
name: bdd-testing
description: Behavior-Driven Development with Given-When-Then scenarios, Cucumber.js, Three Amigos collaboration, Example Mapping, living documentation, and acceptance criteria. Use when writing BDD tests, feature files, or planning discovery workshops.
---

# BDD Testing

Execute test runner with portable path:
```bash
bun run scripts/run-tests.sh

Reference files use relative paths: references/file.md


*Perfect: comprehensive description, portable paths (scripts/, references/), no agent mentions*

**❌ Poor Specification Compliance (7/15):**

```yaml
---
name: bdd-testing  
description: BDD testing patterns
---

# BDD Testing

For Claude Code users, run:
```bash
.opencode/scripts/run-tests.sh

For Cursor users, see .claude/docs/file.md


*Problems: weak description, harness-specific paths (.opencode/, .claude/), agent-specific references*

### References Section Standard

Every SKILL.md that has references or external resources MUST end with a `## References` section using a **3-column Markdown table** with columns `Topic`, `Reference`, and `When to Use`:

```markdown
## References

| Topic | Reference | When to Use |
| --- | --- | --- |
| Security patterns, caching, and trigger configuration | [Best Practices](references/best-practices.md) | Every time you generate a workflow |
| Pinned action versions and input/output specs | [Common Actions](references/common-actions.md) | When using any public action |
| Official workflow syntax and expression reference | [GitHub Actions Docs](https://docs.github.com/en/actions) | For syntax lookup |

Sub-sections (H3 headings) are allowed to group rows by theme when a skill has many references:

## References

### Generators

| Topic | Reference | When to Use |
| --- | --- | --- |
| Tree API patterns for file operations | [Tree API Reference](references/tree-api-reference.md) | Any generator that reads or writes files |

### Executors

| Topic | Reference | When to Use |
| --- | --- | --- |
| ExecutorContext fields and lifecycle | [Executor Context API](references/executor-context-api.md) | Building a custom executor |

Rules:

Rule	Requirement
Heading	Exactly `## References` — no variants (`## Resources`, `## See Also`, etc.)
Position	Last H2 section in the file
Format	Markdown table with `Topic \| Reference \| When to Use` columns — no bullet lists, no bare URLs
Reference column	Every cell in the `Reference` column MUST be a markdown link `[text](url)`
Topic column	One-line description of what the referenced file or resource covers
When to Use column	Concrete scenario that tells the agent when to load or consult the reference
Sub-sections	Optional H3 headings are allowed to group rows by theme
Omission	Allowed only when the skill has nothing to reference (no penalty)

❌ Non-compliant (0 bonus points):

## Resources

- references/file.md
- https://example.com/docs

Problems: wrong heading (## Resources), bullet list instead of table, bare path and bare URL.

## References

- [Error Patterns](references/error-patterns.md) — common failure modes

Problems: bullet list format — table with Topic/Reference/When to Use is required.

✅ Compliant (+1 bonus point):

## References

| Topic | Reference | When to Use |
| --- | --- | --- |
| Common failure modes and remediation steps | [Error Patterns](references/error-patterns.md) | When diagnosing unexpected output or synth failures |
| Authoritative command and flag reference | [Official CLI Docs](https://example.com/cli) | For exact flag syntax lookup |

Dimension 5: Progressive Disclosure (15 points)

Purpose: Structure content for on-demand loading, not frontloading everything.

Scoring:

13-15 points: Navigation hub + references/ + categories + lazy-load guidance
10-12 points: Some organization, could improve
7-9 points: Everything frontloaded, >300 lines
0-6 points: No structure, >500 lines

Components

Navigation Hub Approach (5 points)
- SKILL.md is <100 lines
- Overview + when-to-use + reference guide
- NOT full content
- Example: supabase-postgres-best-practices (65 lines)
References Directory (4 points)
- Detailed content in references/*.md
- Each reference 100-500 lines
- Focused on ONE topic
Category Organization (3 points)
- Files organized by prefix (principles-, patterns-, etc.)
- Priority labels (CRITICAL, HIGH, MEDIUM, LOW)
Lazy Loading Guidance (3 points) ⭐ REQUIRED
- References table includes a concrete “When to Use” column that tells agents exactly which task triggers loading each reference
- AGENTS.md (or equivalent navigation file) explicitly instructs agents to load only the minimum references needed for the current task — not all references upfront
- Each reference entry states a specific, actionable condition (e.g. “When diagnosing a D3 failure”, “Only when preparing a CI gate”) rather than a generic description
- WHY: Without explicit lazy-load guidance, agents default to loading all references eagerly, wasting context on irrelevant content and degrading performance
- IMPACT: Skills without lazy-load guidance consume 3-10x more context than necessary, reducing the agent’s effective working memory

Lazy Loading Anti-Patterns

❌ NEVER list references without “When to Use” conditions

## References
- references/dimensions.md
- references/scoring.md
- references/anti-patterns.md

This forces agents to load everything or guess what to load.

❌ NEVER use vague “When to Use” entries

| Topic | Reference | When to Use |
| --- | --- | --- |
| Scoring | [Scoring Rubric](references/scoring.md) | For scoring |
| Anti-patterns | [Anti-Patterns](references/anti-patterns.md) | For anti-patterns |

“For scoring” is not actionable — it does not tell the agent when NOT to load the file.

✅ Explicit lazy-load conditions:

| Topic | Reference | When to Use |
| --- | --- | --- |
| Per-dimension criteria and bonus rules | [Dimensions](references/dimensions.md) | Evaluating any individual dimension or understanding the rubric |
| Score thresholds and grade bands | [Scoring Rubric](references/scoring.md) | Calculating a total score or assigning a grade — skip if only auditing structure |
| NEVER/WHY/BAD/GOOD failure modes | [Anti-Patterns](references/anti-patterns.md) | Explaining why a dimension scored low or writing remediation guidance |

✅ AGENTS.md with explicit lazy-load instruction:

## Usage Instructions

1. Read SKILL.md — navigation hub only
2. Identify your task from the task categories below
3. Load ONLY the references listed for that task
4. Do NOT pre-load all references

Example

✅ Excellent Progressive Disclosure (15/15):

bdd-testing/
├── SKILL.md (64 lines - navigation hub with actionable "When to Use" per reference)
├── AGENTS.md (explicit: "load only references needed for current task")
└── references/
    ├── principles-three-amigos.md (CRITICAL, 250 lines)
    ├── gherkin-syntax.md (HIGH, 180 lines)
    └── practices-tags.md (MEDIUM, 120 lines)

❌ Poor Progressive Disclosure (6/15):

bdd-testing/
└── SKILL.md (1,800 lines - everything frontloaded)

❌ Missing Lazy Loading (10/15 — loses 3 points):

bdd-testing/
├── SKILL.md (80 lines - good hub, but references table has no "When to Use" column)
├── AGENTS.md (says "load all references before starting")
└── references/
    ├── principles-three-amigos.md
    ├── gherkin-syntax.md
    └── practices-tags.md

Dimension 6: Freedom Calibration (15 points)

Purpose: Balance prescription (rigid rules) vs flexibility (guidelines).

Scoring:

13-15 points: Appropriate for skill type
10-12 points: Slightly too rigid or loose
7-9 points: Mismatched calibration
0-6 points: Completely wrong

Calibration Levels

Rigid (Mindset skills): Strong rules, must follow
- Example: proof-of-work “NEVER trust agent reports without verification”
- Use: Critical foundations, security, correctness
Balanced (Process skills): Clear steps with flexibility
- Example: TDD “Red → Green → Refactor (adapt to context)”
- Use: Workflows, methodologies
Flexible (Tool skills): Options and trade-offs
- Example: typescript-type-system “Choose based on use case”
- Use: Technical tools, patterns

Example

✅ Well-Calibrated (14/15):

# Proof of Work (Mindset skill)

## Zero-Tolerance Rules
NEVER trust agent completion reports without verification.
ALWAYS show command output as proof.
ZERO exceptions to verification protocol.

Appropriately rigid for critical verification.

❌ Miscalibrated (7/15):

# TypeScript Basics (Tool skill)

## Rules
ALWAYS use const for all variables.
NEVER use let or var under any circumstances.

Too rigid - let has valid use cases.

Dimension 7: Pattern Recognition (10 points)

Purpose: Ensure skill activates when needed via description keywords.

Scoring:

9-10 points: Rich keywords, comprehensive triggers
7-8 points: Good keywords, could expand
5-6 points: Basic keywords
0-4 points: Missing or poor

Requirements

Description must include domain keywords
Trigger scenarios in description or “When to Apply”
Example: “Use when writing BDD tests, feature files, Gherkin scenarios…”

Remember: Best description = exhaustive trigger list + examples

Dimension 8: Practical Usability (15 points)

Purpose: Ensure skill is immediately useful with clear examples.

Scoring:

13-15 points: Concrete + runnable + clear
10-12 points: Most examples good
7-9 points: Some weak examples
0-6 points: Abstract or missing

Components

Concrete Examples (5 points)
- Real code, not pseudocode
- Realistic scenarios
- Actual file paths, commands
Runnable Code (5 points)
- Can copy/paste and execute
- Complete, not fragments
- Correct syntax
Clear Structure (5 points)
- Logical organization
- Scannable headings
- Code blocks properly formatted

Dimension 9: Eval Validation (20 points) – HIGHEST PRIORITY

Purpose: Verify the skill has been validated at runtime through tessl eval scenarios, proving agents actually follow its instructions.

Scoring:

17-20 points: Complete evals with >=80% instruction coverage, >=3 valid scenarios
13-16 points: Evals present with partial coverage or incomplete scenarios
7-12 points: Evals directory exists but missing key files
1-6 points: Minimal eval structure, no coverage data
0 points: No evals directory

Core Principle: Static quality (D1-D8) is necessary but not sufficient. Runtime validation proves the skill actually changes agent behavior.

Components

Eval Directory Structure (4 points)
- evals/ directory exists with proper layout
- Follows tessl eval harness conventions
Instruction Inventory (3 points)
- instructions.json present and non-empty
- Every instruction extracted from SKILL.md
- Classified by why_given: reminder, new knowledge, preference
Coverage Statistics (6 points)
- summary.json with instructions_coverage data (3 points)
- Coverage percentage >= 80% (3 points)
Valid Scenarios (4 points)
- = 3 scenarios with complete structure (task.md + criteria.json + capability.txt)
- Each criteria.json sums to exactly 100
Criteria Quality (3 points)
- 10+ checklist items per scenario
- Binary yes/no criteria traceable to specific instructions
- No instruction leakage in task.md

Relationship to D1 and D3

When instructions.json exists, its data enriches other dimensions:

D1 (Knowledge Delta): The why_given distribution (new knowledge + preference vs reminders) provides a more accurate expert content ratio than shell heuristics alone.
D3 (Anti-Pattern Quality): Instructions containing NEVER/ALWAYS/anti-pattern keywords are cross-referenced with scenario coverage for a stronger signal.

Creating Evals

Use the creating-eval-scenarios skill to generate evaluation scenarios:

# Ensure skill is packaged as a tessl tile first
tessl eval run <tile-path>
tessl eval view-status <status_id> --json

Examples

High Eval Validation (19/20):

skill-name/evals/
  instructions.json      # 28 instructions extracted
  summary.json           # 100% coverage, 5 scenarios
  summary_infeasible.json
  scenario-0/            # task.md + criteria.json (sum=100) + capability.txt
  scenario-1/
  scenario-2/
  scenario-3/
  scenario-4/

Low Eval Validation (4/20):

skill-name/evals/
  instructions.json      # Present but only 5 instructions
  # No summary.json, no scenarios

Zero Eval Validation (0/20):

skill-name/
  SKILL.md               # No evals/ directory at all

Summary: The 140-Point Scale

Dimension	Max	Priority	Focus
D1: Knowledge Delta	20	HIGHEST	Expert knowledge only
D2: Mindset + Procedures	15	HIGH	Philosophy + workflows
D3: Anti-Pattern Quality	15	HIGH	NEVER + WHY + consequences
D4: Specification	15	MEDIUM	Description field critical
D5: Progressive Disclosure	15	MEDIUM	Hub + references + lazy-load guidance
D6: Freedom Calibration	15	MEDIUM	Appropriate rigidity
D7: Pattern Recognition	10	LOW	Activation keywords
D8: Practical Usability	15	HIGH	Concrete examples
D9: Eval Validation	20	HIGHEST	Runtime validation via tessl evals
TOTAL	140		A-grade = 126+

A-Grade Skill Quality Standards

Requirements for achieving A-grade (≥126/140) on quality evaluation. Use this as a checklist when creating or improving skills.

A-Grade Requirements Summary

Minimum Score: 126/140 (90%)
Target Score: 133/140 (95%) for A+
Perfect Score: 140/140 (100%)

Dimension Requirements for A-Grade

D1: Knowledge Delta (≥18/20)

Requirements:

<5% redundant content
Expert-only knowledge throughout
No basic tutorials or installation guides
Domain-specific patterns AI assistants don’t know
Project-specific conventions

Checklist:

No basic syntax explanations
No copied official documentation
No generic best practices
Contains non-obvious insights
Includes production-tested patterns

D2: Mindset + Procedures (≥13/15)

Requirements:

Clear philosophical framing
Step-by-step numbered workflow
Explicit “when to apply” criteria
Explicit “when NOT to apply” scenarios

Checklist:

D3: Anti-Pattern Quality (≥13/15)

Requirements:

NEVER statements with WHY explanations
Concrete code examples of anti-patterns
Consequences explained
❌ BAD / ✅ GOOD comparisons

Checklist:

At least 3 NEVER statements
Each NEVER has WHY explanation
Code examples for anti-patterns
Consequences articulated
Side-by-side comparisons present

D4: Specification Compliance (≥13/15)

Requirements:

Description field with activation keywords
Proper YAML frontmatter
Clear trigger scenarios in description
Cross-harness portability (no agent-specific paths)

Checklist:

Description is comprehensive (≥100 chars)
Domain keywords included
Trigger scenarios mentioned
Frontmatter syntax correct
Name matches directory
No harness-specific paths (.opencode/, .claude/, .cursor/)
No agent-specific references (Claude Code, Cursor Agent, etc.)
Uses relative paths (scripts/, references/, templates/)
## References is last H2, uses Topic | Reference | When to Use table format

D5: Progressive Disclosure (≥13/15)

Requirements:

SKILL.md <100 lines for aggregations
References directory with categorized files
Navigation hub approach
Content organized by priority

Checklist:

D6: Freedom Calibration (≥13/15)

Requirements:

Rigidity matches skill type
Mindset skills: Strong rules
Process skills: Balanced flexibility
Tool skills: Options and trade-offs

Checklist:

Calibration appropriate for type
Mindset skills use NEVER/ALWAYS
Process skills allow adaptation
Tool skills present options
Consistent throughout

D7: Pattern Recognition (≥9/10)

Requirements:

Rich domain keywords in description
Comprehensive trigger scenarios
Clear activation signals

Checklist:

5+ domain keywords in description
Trigger examples provided
When-to-use scenarios clear
Unambiguous activation criteria

D8: Practical Usability (≥13/15)

Requirements:

Concrete, runnable code examples
Real-world scenarios
Clear, scannable structure
Complete implementations (not fragments)

Checklist:

Common A-Grade Patterns

skill-name/
├── SKILL.md (60-90 lines)
├── AGENTS.md
└── references/
    ├── category-topic1.md
    └── category-topic2.md

Single-File Pattern (Best for Focused Skills)

skill-name/
├── SKILL.md (100-250 lines)
└── AGENTS.md (optional)

D9: Eval Validation (>=17/20)

Requirements:

Complete evals/ directory with tessl eval harness structure
instructions.json with full instruction extraction
summary.json showing >= 80% instruction coverage
At least 3 valid scenarios with task.md + criteria.json + capability.txt
Each criteria.json sums to exactly 100

Checklist:

evals/ directory exists
instructions.json present and non-empty
summary.json shows coverage_percentage >= 80
>= 3 scenario directories with all required files
criteria.json sums to 100 in each scenario
10+ checklist items per criteria.json
No instruction leakage in task.md files

Red Flags (Immediate Disqualification from A-Grade)

Description <50 characters
No activation keywords
50% tutorial content
Missing anti-patterns
No code examples
500 lines in single file
Generic “best practices” without specificity
Multi-purpose scope: skill covers >2 distinct workflows or description requires multiple “and”/“or” connectors to capture all sub-topics
No eval scenarios (D9 = 0)

Quality Verification Commands

# Check line count
wc -l skills/*/SKILL.md

# Verify frontmatter
head -10 skills/*/SKILL.md | grep -A5 "^---"

# Check for references directory
ls -la skills/*/references/

# Count keywords in description
grep "^description:" skills/*/SKILL.md | wc -w

Skill Scoring Rubric

Detailed scoring methodology for the 9-dimension quality framework. Use this to understand how scores are calculated and ensure consistent evaluation.

Scoring Overview

Total Possible Score: 140 points
Passing Grade: 105 points (75%)
A-Grade Target: 126 points (90%)
Perfect Score: 140 points (100%)

Dimension-by-Dimension Scoring

D1: Knowledge Delta (20 points)

Score	Criteria	Redundancy Level
18-20	Pure expert knowledge	<5%
15-17	Mostly expert	5-15%
12-14	Acceptable balance	15-30%
9-11	Needs improvement	30-50%
0-8	Failing	>50%

Evaluation Method:

Read entire skill content
Identify content AI assistants already know
Calculate: Expert Content / Total Content
Apply scoring threshold

D2: Mindset + Procedures (15 points)

Score	Criteria
13-15	Clear mindset + detailed procedures + when/when-not
10-12	Has most elements, minor gaps
7-9	Missing key element
0-6	Generic or absent

Component Breakdown:

Clear Mindset/Philosophy: 5 points
Step-by-Step Procedures: 5 points
When/When-Not Guidance: 5 points

D3: Anti-Pattern Quality (15 points)

Score	Criteria
13-15	NEVER lists + concrete examples + consequences
10-12	Has most elements
7-9	Generic warnings
0-6	Missing or weak

Component Breakdown:

NEVER Lists with WHY: 5 points
Concrete Examples: 5 points
Consequences Explained: 5 points

D4: Specification Compliance (15 points)

Score	Criteria
13-15	Perfect spec compliance
10-12	Minor issues
7-9	Missing key elements
0-6	Non-compliant

Component Breakdown:

Task Focus Declaration: 4 points
Description Field Quality: 6 points
Cross-Harness Portability: 3 points (CRITICAL for multi-agent compatibility)
Proper Frontmatter: 1 point
Activation Keywords: 1 point

Portability Requirements:

No harness-specific paths (.opencode/, .claude/, .cursor/): 1 point
No agent-specific references (Claude Code, Cursor Agent, etc.): 1 point
Relative paths from skill directory (scripts/, references/): 1 point

Bonus Points (each independent, up to +2 total):

Script Language Portability: +1 (Python/TS/JS scripts present in scripts/)
References Section Format: +1 (heading exactly ## References, last H2, Markdown table with Topic | Reference | When to Use columns, Reference column cells are markdown links)
- 0 if: wrong heading name, bullet list instead of table, bare URLs, plain-text paths, missing required columns, or section missing when references exist
- Omission allowed without penalty when skill has nothing to reference

D5: Progressive Disclosure (15 points)

Score	Criteria
13-15	Navigation hub + references/ + categories
10-12	Some organization, could improve
7-9	Everything frontloaded, >300 lines
0-6	No structure, >500 lines

Component Breakdown:

Navigation Hub Approach: 8 points
References Directory: 4 points
Category Organization: 3 points

D6: Freedom Calibration (15 points)

Score	Criteria
13-15	Appropriate for skill type
10-12	Slightly too rigid or loose
7-9	Mismatched calibration
0-6	Completely wrong

Calibration Types:

Rigid (Mindset skills): Strong rules, must follow
Balanced (Process skills): Clear steps with flexibility
Flexible (Tool skills): Options and trade-offs

D7: Pattern Recognition (10 points)

Score	Criteria
9-10	Rich keywords, comprehensive triggers
7-8	Good keywords, could expand
5-6	Basic keywords
0-4	Missing or poor

Evaluation Method:

Count domain keywords in description
Check trigger scenarios present
Verify activation clarity

D8: Practical Usability (15 points)

Score	Criteria
13-15	Concrete + runnable + clear
10-12	Most examples good
7-9	Some weak examples
0-6	Abstract or missing

Component Breakdown:

Concrete Examples: 5 points
Runnable Code: 5 points
Clear Structure: 5 points

D9: Eval Validation (20 points)

Score	Criteria
17-20	Complete evals, >=80% coverage, >=3 valid scenarios
13-16	Evals present, partial coverage
7-12	Evals directory exists, missing key files
0-6	Minimal or no eval structure

Component Breakdown:

Eval Directory Structure: 4 points
Instruction Inventory (instructions.json): 3 points
Coverage Statistics (summary.json): 3 points
Coverage >= 80%: 3 points
Valid Scenarios (>=3 complete): 4 points
Criteria Quality (sum to 100): 3 points

Enrichment: When instructions.json exists, D1 and D3 scores are enriched with instruction classification data (why_given distribution for D1, anti-pattern instruction count for D3).

Grade Assignment

Grade	Score Range	Interpretation
A+	133-140	Exceptional quality
A	126-132	Meets all standards
B+	119-125	Strong, minor improvements
B	112-118	Good, some gaps
C+	105-111	Acceptable, needs work
C	98-104	Below standard
D	91-97	Significant issues
F	0-90	Failing

Scoring Process

Step 1: Read and Understand

Read the entire skill, including all references if present.

Step 2: Score Each Dimension

Apply rubric to each of 9 dimensions independently.

Step 3: Calculate Total

Sum all 9 dimension scores for total out of 140.

Step 4: Assign Grade

Map total score to grade using grade assignment table.

Step 5: Identify Improvements

For scores below A-grade, identify specific improvements needed.

Common Score Patterns

High Knowledge Delta, Low Usability (18, 10): Expert content but lacks examples
Low Knowledge Delta, High Usability (10, 14): Tutorial-heavy, needs expert focus
Perfect Spec, Poor Content (15, 8): Great frontmatter, weak body
Balanced Scores (12-13 each): Consistent but not exceptional

Quality Gates and Scoring Thresholds

Complete scoring framework and threshold interpretation for skill quality assessment.

Quality Gates and Thresholds

Score Range	Grade	Status	Action Required
126+	A	Production Ready	Tessl registry eligible
112-125	B/B+	Good Quality	Minor improvements
98-111	C/C+	Passing	Remediation recommended
91-97	D	Below Standard	Major improvements required
<91	F	Failing	Complete rework needed

Score Interpretation

Knowledge Delta drives overall score - prioritize this dimension first
Anti-patterns prevent catastrophic failures - second priority
Progressive disclosure improves usability - third priority
Specification compliance ensures consistency - foundational requirement

Dimension Weighting

Dimension	Max Points	Priority	Focus Area
Knowledge Delta	20	HIGHEST	Expert-only content
Eval Validation	20	HIGHEST	Runtime validation via tessl evals
Mindset + Procedures	15	HIGH	Philosophy + workflows
Anti-Pattern Quality	15	HIGH	NEVER + WHY + consequences
Practical Usability	15	HIGH	Concrete examples
Specification Compliance	15	MEDIUM	Description field critical
Progressive Disclosure	15	MEDIUM	Hub + references
Freedom Calibration	15	MEDIUM	Appropriate rigidity
Pattern Recognition	10	LOW	Activation keywords

A-Grade Requirements (>=126)

Critical Success Factors

Knowledge Delta >=17/20: Expert content with <10% redundancy
Eval Validation >=17/20: Complete evals with >=80% instruction coverage
Anti-Patterns >=13/15: Multiple NEVER statements with consequences
Progressive Disclosure >=13/15: Navigation hub + references structure
Strong Activation: Comprehensive description with trigger keywords

Common A-Grade Patterns

Scores consistently 13+ across most dimensions
Knowledge Delta typically 16-19 points
Perfect or near-perfect specification compliance
Clear navigation with references directory

Improvement Priority Matrix

High Impact, Low Effort

Add missing NEVER statements to anti-patterns
Enhance description field with activation keywords
Create proper references directory structure
Add concrete code examples
Create eval scenarios using creating-eval-scenarios skill

High Impact, High Effort

Restructure for progressive disclosure (hub approach)
Add expert-only content to boost Knowledge Delta
Create comprehensive workflow documentation
Develop specialized troubleshooting guides
Achieve >=80% instruction coverage in evals

Medium Priority

Improve freedom calibration balance
Enhance practical usability examples
Refine mindset and procedure clarity
Optimize pattern recognition triggers

Score Optimization Strategies

For 105-125 Range (B/B+ -> A)

Focus on the “Big 4”: Knowledge Delta, Eval Validation, Anti-Patterns, Progressive Disclosure

For 98-104 Range (C/C+ -> B)

Address specification compliance, practical usability, and create eval scenarios first

For <98 Range (Failing)

Complete restructure required - start with navigation hub, expert content, and eval scenarios

Remediation Planning Guide

Guide for creating remediation plans from skill quality audit results.

When to Use This Guide

Use this guide when:

A skill has been audited and scored below target (typically <108/120, grade B or lower)
You need to create an actionable plan to improve skill quality
Converting audit findings into structured improvement tasks

Prerequisites

Completed Audit: Run skill-auditor evaluate <skill-name> --json
Audit Report: Location should be .context/audits/<skill-name>-audit-YYYY-MM-DD.md
Template: Load templates/remediation-plan-template.yaml

Standard Remediation Plan Format

All remediation plans follow this structure:

Executive Summary

Field	Description
Current Score	Actual score from audit (e.g., 84/120, 70%)
Target Score	Desired score (typically +15-20 points)
Current/Target Grade	Letter grade (F/D/C/B/A)
Priority	Critical/High/Medium/Low
Effort	S/M/L estimate

Focus Areas: Top 2-3 dimensions requiring attention

Verdict: One-line summary: “Priority improvements required” vs “Targeted improvements recommended”

Critical Issues Table

Identify the top 3-5 issues from the audit:

Issue	Dimension	Severity	Impact
Description	D# (score/max)	Critical/High/Medium/Low	Why this matters

Prioritize by:

Critical/High severity
Dimensions with lowest scores
Issues blocking other improvements

Detailed Remediation Steps

For each priority dimension:

### Phase N: [Dimension Name] - Priority: [Priority]

**Target**: Increase from [current]/[max] to [target]/[max] (+[delta] points)

#### Step N.1: [Specific Action]

**[File to modify]**: `path/to/file.md`

[Code example if applicable]

Code Block Escaping

When documenting code examples that contain markdown code fences, use 4 backticks:

**BAD**:
```markdown
Some markdown content here
```

**GOOD**:
```markdown
Good content here
```

Success Criteria

Measurable targets for verification:

Criterion	Measurement
Dimension Score	>= target/max
Overall Score	>= target-score (target-grade)
References Created	>= N files

Effort Estimate

Phase	Effort	Time
Phase 1	S/M/L	HH hours
Phase 2	S/M/L	HH hours
Total	M/L	X hours

Additional Sections

Dependencies: Any prerequisites or blockers
Rollback Plan: Git command to revert changes
Notes: Honest assessment of plan quality (rating out of 10)

Honest Rating Guidelines

Rate plans based on:

Rating	Criteria
9-10/10	Template gold standard, comprehensive
8/10	Follows Format B well, detailed code examples
7/10	Good structure but gaps in specifics
6/10	Major restructuring needed
<5/10	Fundamental issues with approach

Common Remediation Patterns

Pattern 1: Anti-Pattern Addition

For D3 (Anti-Pattern Quality) improvements:

## Anti-Patterns

### NEVER: [Action]

**WHY**: [Reason]

**BAD**:
```[language]
[bad code]
```

**GOOD**:
```[language]
[good code]
```

Pattern 2: Reference Creation

For D5 (Progressive Disclosure) improvements:

Create skills/<skill>/references/ directory
Extract detailed content from SKILL.md
Add navigation table to SKILL.md:

## Quick Reference

| Topic | Reference |
|-------|-----------|
| Topic Name | [references/topic.md](references/topic.md) |

Pattern 3: Trigger Expansion

For D7 (Pattern Recognition) improvements:

Update frontmatter description:

---
name: skill-name
description: |
  [Core description]. Use when: [trigger phrases].
  
  Keywords: [comma-separated keywords]
---

Verification

After implementing remediation:

skill-auditor evaluate <skill-name> --json
bunx markdownlint-cli2 "skills/<skill-name>/**/*.md"

Compare new score against target in plan.

framework-dimensions.md - Understanding the 8 dimensions
framework-scoring-rubric.md - How scores are calculated
aggregation-pattern.md - For larger consolidation efforts

Audit Report Analysis

Guide to interpreting skill quality audit reports and taking action based on findings.

Report Types

Quality Report (skill-audit-*.md)

Contains:

Overall skill collection statistics
Individual skill scores and grades
Grade distribution
Recommendations by priority

Duplication Report (duplication-report-*.md)

Contains:

Skill pairs with similarity percentages
High-priority consolidation candidates
Common content patterns
Remediation recommendations

Aggregation Plan (aggregation-plan-*.md)

Contains:

Source skills for consolidation
Proposed category structure
Estimated effort and ROI
Implementation steps

Analyzing Quality Reports

Grade Distribution

| Grade | Count | Percentage |
|-------|-------|------------|
| A     | 35    | 70%        |
| B     | 12    | 24%        |
| C     | 3     | 6%         |

Interpretation:

Target: 90%+ A-grade
Warning: Any C-grade skills
Critical: D or F grades

Score Analysis

| Skill | Score | Grade | Lines |
|-------|-------|-------|-------|
| bdd-testing | 98/120 | A | 64 |
| typescript-advanced | 85/120 | B | 450 |
| old-patterns | 72/120 | C | 800 |

Actions by Score:

Score	Priority	Action
108+	Maintain	Keep current, monitor
96-107	Low	Minor improvements optional
90-95	Medium	Review for improvements
78-89	High	Requires attention
<78	Critical	Immediate action needed

Common Score Patterns

High Lines, Low Score (450, 72):

Problem: Overly verbose, not focused
Solution: Progressive disclosure, extract to references

Low Lines, Low Score (80, 75):

Problem: Missing content, incomplete
Solution: Add missing dimensions (anti-patterns, examples)

High Lines, High Score (450, 105):

Problem: Good content but needs reorganization
Solution: Split into navigation hub + references

Analyzing Duplication Reports

Similarity Matrix

| Skill Pair | Similarity | Common Lines | Action |
|------------|------------|--------------|--------|
| bdd-gherkin ↔ cucumber | 42% | 287 | Aggregate |
| typescript-* family | 28% avg | 156 | Consider |

Action by Similarity:

Similarity	Priority	Action
>50%	Critical	Immediate consolidation
35-50%	High	Plan aggregation
20-35%	Medium	Review for opportunity
<20%	Low	Monitor

Family Analysis

## BDD Family (6 skills, 2,032 lines, 35% avg duplication)
- bdd-collaboration
- bdd-gherkin
- bdd-patterns
- bdd-principles
- bdd-scenarios
- cucumber-best-practices

Actions:

Calculate consolidation ROI
Plan aggregation implementation
Schedule remediation

Key Metrics to Track

Quality Metrics

Metric	Target	Calculation
A-grade rate	>90%	A-count / total
Average score	>100	Total score / count
Max file size	<500 lines	wc -l SKILL.md
Description quality	100%	With keywords / total

Duplication Metrics

Metric	Target	Calculation
Average duplication	<5%	Sum similarity / pairs
Critical pairs (>35%)	0	Count where >35%
Aggregation candidates	<5	Count where >20%

Maintenance Metrics

Metric	Target	Calculation
Deprecated skills	Minimize	Count in .deprecated/
Orphan references	0	Broken @see links
Outdated reports	<7 days	Age of latest audit

Action Planning

Immediate Actions (Critical Issues)

Address C-grade skills
- Read skill content
- Identify missing dimensions
- Add anti-patterns, examples
- Re-evaluate
Fix critical duplication
- Consolidate >35% pairs
- Follow aggregation implementation
- Verify no breakage
Fix broken references
- Identify orphan @see links
- Update or remove references
- Verify skill still works

Short-term Actions (1-2 weeks)

Improve B-grade skills
- Add missing content
- Improve descriptions
- Add examples
Plan aggregations
- Identify families
- Design category structure
- Estimate effort
Update documentation
- Refresh AGENTS.md files
- Update metrics
- Document changes

Long-term Actions (Monthly)

Review skill collection
- Identify unused skills
- Consider deprecation
- Archive outdated content
Update baselines
- Re-run full audit
- Compare with previous
- Track trends
Team review
- Present findings
- Get feedback
- Prioritize improvements

Report Comparison

Tracking Changes Over Time

# Compare with previous audit
diff .context/analysis/skill-audit-2026-01-15.md \
     .context/analysis/skill-audit-2026-02-20.md

Look for:

Grade changes (improvements/regressions)
New skills added
Skills removed/deprecated
Score trends

Trend Indicators

Trend	Meaning
A-grade increasing	Quality improving
Average score rising	Skills getting better
Duplication decreasing	Consolidation working
File sizes shrinking	Progressive disclosure applied

Reporting to Stakeholders

Executive Summary

# Skill Quality Summary

## Overall Health: Good (87/100)

- **Skills**: 50 active, 10 deprecated
- **Quality**: 72% A-grade (target: 90%)
- **Duplication**: 12% (target: <5%)
- **Trend**: Improving (+5% from last quarter)

## Key Actions
1. Consolidate BDD family (6 → 1 skill)
2. Improve 8 B-grade skills to A
3. Reduce duplication from 12% to <5%

Technical Details

Provide full reports for technical teams with:

Complete score breakdowns
All dimension scores
Specific improvement recommendations
Code examples for fixes

Quality Dashboards

Visualization approaches for skill quality metrics. Provides templates for tracking and presenting audit results.

Dashboard Overview

Purpose: Visual representation of skill collection health
Audience: Team leads, developers, stakeholders
Update Frequency: Weekly automated, on-demand manual

Metrics Dashboard

Core Metrics Panel

┌─────────────────────────────────────────────────────────────┐
│                   SKILL COLLECTION HEALTH                   │
├──────────────────┬──────────────────┬───────────────────────┤
│  Total Skills    │  A-Grade Rate    │  Avg Duplication      │
│      50          │      72%         │       12%             │
│   (target: N/A)  │ (target: 90%)    │  (target: <5%)        │
├──────────────────┴──────────────────┴───────────────────────┤
│  STATUS: NEEDS ATTENTION                                    │
│  • 8 skills below A-grade                                   │
│  • 3 aggregation candidates                                 │
└─────────────────────────────────────────────────────────────┘

Grade Distribution Chart

Grade Distribution
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
A (108+) ████████████████████████████████████ 36 (72%)
B (96-107) ████████████ 12 (24%)
C (84-95) ███ 2 (4%)
D/F (<84) 0 (0%)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Top/Bottom Skills

Top Performers          │  Needs Improvement
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
bdd-testing      98/120 │  old-patterns     72/120
typescript-adv   96/120 │  legacy-utils     78/120
bun-development  94/120 │  temp-skills      82/120

Trend Dashboard

Quality Trend (12 weeks)

Average Score
120 ┤
110 ┤       ╭───╮    ╭────╮
100 ┤   ╭───╯   ╰────╯    ╰───
 90 ┤───╯
 80 ┤
    └──────────────────────────
      W1  W3  W5  W7  W9  W11

Trend: Improving (+8 points over 12 weeks)

Duplication Trend

Duplication %
35 ┤
30 ┤╮
25 ┤╰╮
20 ┤ ╰╮
15 ┤  ╰─╮
10 ┤    ╰──╮
 5 ┤       ╰──────
 0 ┤
    └──────────────
      Jan Feb Mar

Trend: Decreasing (35% → 8%)

Duplication Heatmap

             bdd-  type-  bun-  mise- biome-
             test  script dev   plete plete
bdd-test     ───   ███    ░░    ░░    ░░
typescript   ███   ───    ██    ░░    ░░
bun-dev      ░░    ██     ───   ░░    ░░
mise-comp    ░░    ░░     ░░    ───   ███
biome-comp   ░░    ░░     ░░    ███   ───

Legend: ███ High (>30%)  ██ Medium (20-30%)  ░░ Low (<20%)  ─── Self

HTML Dashboard Template

<!DOCTYPE html>
<html>
<head>
  <title>Skill Quality Dashboard</title>
  <style>
    .metric-card {
      border: 1px solid #ddd;
      padding: 1rem;
      margin: 0.5rem;
      border-radius: 8px;
    }
    .grade-a { background: #d4edda; }
    .grade-b { background: #fff3cd; }
    .grade-c { background: #f8d7da; }
    .progress-bar {
      height: 20px;
      background: #eee;
      border-radius: 4px;
    }
    .progress-fill {
      height: 100%;
      border-radius: 4px;
    }
  </style>
</head>
<body>
  <h1>Skill Quality Dashboard</h1>
  <p>Last updated: <span id="timestamp"></span></p>
  
  <div class="metrics-row">
    <div class="metric-card">
      <h3>Total Skills</h3>
      <div class="value">50</div>
    </div>
    <div class="metric-card">
      <h3>A-Grade Rate</h3>
      <div class="value">72%</div>
      <div class="progress-bar">
        <div class="progress-fill" style="width: 72%; background: #ffc107;"></div>
      </div>
      <small>Target: 90%</small>
    </div>
    <div class="metric-card">
      <h3>Duplication</h3>
      <div class="value">12%</div>
      <div class="progress-bar">
        <div class="progress-fill" style="width: 12%; background: #28a745;"></div>
      </div>
      <small>Target: &lt;5%</small>
    </div>
  </div>
  
  <h2>Grade Distribution</h2>
  <div id="grade-chart"></div>
  
  <h2>Skills Needing Attention</h2>
  <table>
    <tr><th>Skill</th><th>Score</th><th>Grade</th><th>Issue</th></tr>
    <tr class="grade-c">
      <td>old-patterns</td><td>72/120</td><td>C</td>
      <td>Missing anti-patterns, no examples</td>
    </tr>
  </table>
  
  <script>
    // Load data from audit report
    document.getElementById('timestamp').textContent = new Date().toISOString();
  </script>
</body>
</html>

Markdown Dashboard Template

# Skill Quality Dashboard

**Last Updated**: 2026-02-20
**Status**: ⚠️ Needs Attention

## Summary Metrics

| Metric | Value | Target | Status |
|--------|-------|--------|--------|
| Total Skills | 50 | - | - |
| A-Grade Rate | 72% | 90% | ⚠️ Below |
| Avg Score | 98/120 | 108/120 | ⚠️ Below |
| Duplication | 12% | <5% | ⚠️ Above |
| Avg File Size | 180 lines | <200 lines | ✅ On Target |

## Grade Distribution

- A (108+): 36 skills (72%)
- B (96-107): 12 skills (24%)
- C (84-95): 2 skills (4%)

## Top Priority Actions

1. **Consolidate BDD family** - 6 skills → 1 aggregation
2. **Improve old-patterns** - Score 72 → 90+
3. **Reduce duplication** - 12% → <5%

## Trend (Last 4 Weeks)

| Week | A-Rate | Avg Score | Duplication |
|------|--------|-----------|-------------|
| W1 | 68% | 94 | 15% |
| W2 | 70% | 96 | 14% |
| W3 | 71% | 97 | 13% |
| W4 | 72% | 98 | 12% |

↑ Improving

Real-time Monitoring

Watch Script

#!/bin/bash
# watch-quality.sh - Real-time quality monitoring

watch -n 60 '
echo "=== Skill Quality Monitor ==="
echo "Time: $(date)"
echo ""
echo "Skills: $(find skills -name "SKILL.md" -not -path "*/.deprecated/*" | wc -l)"
echo "A-Grade: $(grep -l "grade: A" skills/*/SKILL.md 2>/dev/null | wc -l)"
echo "Pending: $(ls .context/analysis/*.md 2>/dev/null | wc -l) reports"
echo ""
echo "Recent Changes:"
git log --oneline -5 -- "skills/"
'

Alert Thresholds

Metric	Warning	Critical	Alert
A-grade rate	<80%	<70%	Slack + Email
Duplication	>15%	>25%	Slack
C-grade count	>3	>5	Email
File size	>400	>600	Slack

Export Formats

JSON Export

# Export metrics as JSON
cat > .context/analysis/metrics.json <<EOF
{
  "timestamp": "$(date -Iseconds)",
  "skills": {
    "total": $(find skills -name "SKILL.md" | wc -l),
    "aGrade": $(grep -l "grade: A" skills/*/SKILL.md | wc -l),
    "bGrade": $(grep -l "grade: B" skills/*/SKILL.md | wc -l),
    "cGrade": $(grep -l "grade: C" skills/*/SKILL.md | wc -l)
  },
  "quality": {
    "avgScore": 98,
    "duplication": 12
  }
}
EOF

CSV Export

# Export skill scores as CSV
echo "skill,score,grade,lines" > skills-report.csv
for skill in skills/*/SKILL.md; do
  name=$(basename $(dirname $skill))
  lines=$(wc -l < $skill)
  echo "$name,,$lines" >> skills-report.csv
done

Scoring Rubric

Dimension Weights

Dimension	Weight	Description
D1 Knowledge Delta	20	Non-obvious guidance depth
D2 Mindset + Procedures	15	Procedural clarity
D3 Anti-Pattern Quality	15	Specificity and enforceability
D4 Specification Compliance	15	Metadata/spec alignment
D5 Progressive Disclosure	15	Hub-to-reference balance
D6 Freedom Calibration	15	Constraint/flexibility balance
D7 Pattern Recognition	10	Trigger/intent discoverability
D8 Practical Usability	15	Actionable examples/commands
D9 Eval Validation	20	Runtime validation via tessl evals
Total	140	Overall score

Grade Scale

Grade	Score Range	Assessment
A+	133-140	Exceptional
A	126-132	Strong
B+	119-125	Solid baseline
B	112-118	Good with gaps
C+	105-111	Moderate
C	98-104	Mixed quality
D	91-97	Low quality
F	0-90	Unacceptable

Signal Levels

Strong: score >= 80% of max
Moderate: score 50-79% of max
Weak: score < 50% of max

Priority Guidance

High: weak signal, immediate remediation
Medium: moderate signal, targeted improvements
Low: strong signal, maintain and refine

Audit Workflow Automation

Complete workflow for running automated skill quality audits. Covers setup, execution, and maintenance of audit processes.

Workflow Overview

Purpose: Automate skill quality evaluation on schedule and on-demand
Outputs: Quality reports, duplication analysis, aggregation recommendations
Schedule: Weekly automated + on-demand for new skills

Prerequisites

Go 1.21+ (for building the binary)
Bun runtime (for TypeScript aggregation scripts)
Write access to .context/audits/ directory

Build the binary once from the repo root:

bun run build:skill-auditor

Audit Commands

Single skill evaluation

skill-auditor evaluate <domain/skill-name> --json

Options:

--json - Machine-readable JSON output
--store - Write results to .context/audits/<skill>/YYYY-MM-DD/
--repo-root - Explicit repo root (auto-detected if omitted)

Output: JSON score report

Batch audit

skill-auditor batch <skill1> <skill2> [skill3...]

Options:

--json - Machine-readable JSON array output
--store - Write each result to .context/audits/<skill>/YYYY-MM-DD/
--fail-below <grade> - Exit 1 if any skill scores below this grade (e.g. B+)

Features:

Sequential evaluation with per-skill error isolation
Failure tracking and summary table
Audit results stored in .context/audits/<skill-name>/YYYY-MM-DD/
Exit code reflects failures (0 = all passed, 1 = some failed)

Output: Summary table or JSON array

Use when: Auditing multiple skills in phases or batches with consolidated tracking

Duplication detection (shell helper)

./scripts/detect-duplication.sh [skills-dir]

Arguments:

skills-dir - Skills directory (default: skills)

Output: duplication-report-YYYY-MM-DD.md

Aggregation planning

bun run scripts/plan-aggregation.ts --family <prefix>

Options:

--family - Skill family prefix (e.g., bdd, typescript)

Output: Aggregation plan with recommendations

Complete Audit Workflow

Phase 1: Inventory

# Count skills
find skills -name "SKILL.md" -not -path "*/.deprecated/*" | wc -l

# List by category
ls -1 skills/ | cut -d- -f1 | sort | uniq -c | sort -rn

# Identify families
ls -1 skills/ | grep -E "^[a-z]+-" | cut -d- -f1 | sort -u

Phase 2: Quality Evaluation

# Run full batch audit
skill-auditor batch $(find skills -name "SKILL.md" | sed 's|skills/||;s|/SKILL.md||') --store

# Review stored results
cat .context/audits/*/$(date +%Y-%m-%d)/audit.json | jq '.grade'

Phase 3: Duplication Analysis

# Detect duplication
./scripts/detect-duplication.sh

# Review high-priority pairs
grep -A5 "High-Priority" .context/analysis/duplication-report-*.md

Phase 4: Aggregation Planning

# Plan aggregation for each family
bun run scripts/plan-aggregation.ts --family bdd
bun run scripts/plan-aggregation.ts --family typescript
bun run scripts/plan-aggregation.ts --family bun

Phase 5: Generate Summary

# Create summary report
cat > .context/analysis/audit-summary-$(date +%Y-%m-%d).md <<EOF
# Audit Summary - $(date +%Y-%m-%d)

## Statistics
- Total skills: $(find skills -name "SKILL.md" -not -path "*/.deprecated/*" | wc -l)
- A-grade: X
- B-grade: Y
- C-grade: Z

## Duplication
- High-priority pairs: X
- Critical (>35%): Y

## Recommendations
1. [From aggregation plans]
2. [From duplication report]
EOF

Scheduled Audits

Weekly Automated Audit

Add to CI/CD pipeline:

# .github/workflows/skill-audit.yml
name: Skill Audit
on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly on Sunday
  workflow_dispatch:

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      - name: Build skill-auditor
        run: bun run build:skill-auditor
      - name: Run full batch audit
        run: |
          skills=$(find skills -name "SKILL.md" | sed 's|skills/||;s|/SKILL.md||' | tr '\n' ' ')
          skill-auditor batch $skills --store
      - run: ./scripts/detect-duplication.sh
      - uses: actions/upload-artifact@v4
        with:
          name: audit-reports
          path: .context/audits/

Pre-Merge Quality Gate

Block PRs with C-grade skills:

# .github/workflows/skill-quality-gate.yml
name: Skill Quality Gate
on: pull_request

jobs:
  quality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      - name: Build skill-auditor
        run: bun run build:skill-auditor
      - name: Check changed skills
        run: |
          for skill in $(git diff --name-only origin/main | grep "skills/.*/SKILL.md" | sed 's|skills/||;s|/SKILL.md||'); do
            skill-auditor evaluate "$skill" --json --store
          done
          skill-auditor batch $(git diff --name-only origin/main | grep "skills/.*/SKILL.md" | sed 's|skills/||;s|/SKILL.md||' | tr '\n' ' ') --fail-below B

Single-Skill Report Format

Audit reports in .context/audits/*.md must follow the frontmatter-first format:

review_date: YYYY-MM-DD
reviewer: automated audit
skill_location: `skills/<skill-name>/SKILL.md`

Use templates/review-report-template.yaml as the canonical format source, then validate generated reports with:

././scripts/validate-review-format.sh .context/audits/<skill>-YYYY-MM-DD.md

Report Interpretation

Quality Report

| Skill | Score | Grade | Lines |
|-------|-------|-------|-------|
| bdd-testing | 98/120 | A | 64 |

Actions:

Score <90: Review and improve
Score <80: Critical issues
Lines >300: Consider progressive disclosure

Duplication Report

| Skill Pair | Similarity | Action |
|------------|------------|--------|
| bdd-gherkin ↔ cucumber | 42% | Aggregate |

Actions:

35%: Immediate aggregation
20-35%: Plan aggregation
<20%: Monitor

Maintenance

Weekly Tasks

Review automated audit reports
Check for new duplication
Update baseline metrics
Address C-grade skills

Monthly Tasks

Full collection evaluation
Update aggregation plans
Review deprecated skills
Archive old reports

Quarterly Tasks

Complete audit cycle
Major consolidation if needed
Update documentation
Team review of metrics

CI/CD Integration for Skill Quality

Setup guides for GitHub Actions, GitLab CI, and Jenkins pipelines to automate skill quality enforcement.

Integration Overview

Purpose: Automate quality checks in CI/CD pipelines
Enforcement: Block PRs with low-quality skills
Reporting: Generate quality reports on schedule

GitHub Actions

Quality Gate Workflow

Block PRs with skills below A-grade:

# .github/workflows/skill-quality.yml
name: Skill Quality Gate

on:
  pull_request:
    paths:
      - 'skills/**/SKILL.md'
  workflow_dispatch:

jobs:
  quality-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Bun
        uses: oven-sh/setup-bun@v1

      - name: Install dependencies
        run: bun install

      - name: Build skill-auditor
        run: bun run build:skill-auditor

      - name: Evaluate changed skills
        id: evaluate
        run: |
          FAILED=""
          for file in $(git diff --name-only origin/main | grep "skills/.*/SKILL.md"); do
            skill=$(echo "$file" | sed 's|skills/||;s|/SKILL.md||')
            echo "Evaluating: $skill"
            score=$(skill-auditor evaluate "$skill" --json 2>/dev/null | jq '.total')
            
            if [ -n "$score" ] && [ "$score" -lt 90 ]; then
              echo "::warning::$skill scored $score/140 (below threshold 90)"
              FAILED="$FAILED $skill"
            fi
          done
          
          if [ -n "$FAILED" ]; then
            echo "failed=true" >> $GITHUB_OUTPUT
            echo "skills=$FAILED" >> $GITHUB_OUTPUT
          fi

      - name: Check for duplication
        run: |
          ./scripts/detect-duplication.sh
          if grep -q "Critical" .context/analysis/duplication-report-*.md; then
            echo "::warning::Critical duplication detected"
          fi

      - name: Fail if quality issues
        if: steps.evaluate.outputs.failed == 'true'
        run: |
          echo "Quality gate failed for skills: ${{ steps.evaluate.outputs.skills }}"
          exit 1

      - name: Upload reports
        uses: actions/upload-artifact@v4
        with:
          name: quality-reports
          path: .context/analysis/
          retention-days: 30

Scheduled Audit Workflow

Weekly automated audits:

# .github/workflows/weekly-audit.yml
name: Weekly Skill Audit

on:
  schedule:
    - cron: '0 0 * * 0'  # Sunday at midnight
  workflow_dispatch:

jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v1

      - name: Build skill-auditor
        run: bun run build:skill-auditor

      - name: Run full audit
        run: |
          skills=$(find skills -name "SKILL.md" | sed 's|skills/||;s|/SKILL.md||' | tr '\n' ' ')
          skill-auditor batch $skills --store
          ./scripts/detect-duplication.sh

      - name: Create issue if critical issues found
        run: |
          if grep -q "C Grade" .context/analysis/skill-audit-*.md; then
            gh issue create \
              --title "Skill Quality Issues - $(date +%Y-%m-%d)" \
              --body-file .context/analysis/skill-audit-*.md \
              --label "quality,skills"
          fi
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Upload reports
        uses: actions/upload-artifact@v4
        with:
          name: weekly-audit-reports
          path: .context/analysis/

GitLab CI

Quality Gate Pipeline

# .gitlab-ci.yml
skill-quality:
  stage: test
  image: oven/bun:1
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - skills/**/SKILL.md
  script:
    - bun install && bun run build:skill-auditor
    - |
      for file in $(git diff --name-only $CI_MERGE_REQUEST_DIFF_BASE_SHA $CI_COMMIT_SHA | grep "skills/.*/SKILL.md"); do
        skill=$(echo "$file" | sed 's|skills/||;s|/SKILL.md||')
        skill-auditor evaluate "$skill" --json --store
      done
    - ./scripts/detect-duplication.sh
  artifacts:
    paths:
      - .context/analysis/
    expire_in: 1 week

Scheduled Pipeline

weekly-skill-audit:
  stage: deploy
  image: oven/bun:1
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
  script:
    - bun install && bun run build:skill-auditor
    - skills=$(find skills -name "SKILL.md" | sed 's|skills/||;s|/SKILL.md||' | tr '\n' ' ')
    - skill-auditor batch $skills --store
    - ./scripts/detect-duplication.sh
  artifacts:
    paths:
      - .context/analysis/
    expire_in: 30 days

Jenkins

Jenkinsfile

pipeline {
  agent any
  
  tools {
    nodejs 'NodeJS-18'
  }
  
  stages {
    stage('Install') {
      steps {
        sh 'bun install'
      }
    }
    
    stage('Build') {
      steps {
        sh 'bun run build:skill-auditor'
      }
    }

    stage('Quality Check') {
      when {
        anyOf {
          changeset 'skills/**/SKILL.md'
          branch 'main'
        }
      }
      steps {
        sh '''
          for file in $(git diff --name-only origin/main HEAD | grep "skills/.*/SKILL.md"); do
            skill=$(echo "$file" | sed 's|skills/||;s|/SKILL.md||')
            skill-auditor evaluate "$skill" --json --store
          done
        '''
      }
    }
    
    stage('Duplication Check') {
      steps {
        sh './scripts/detect-duplication.sh'
      }
    }
  }
  
  post {
    always {
      archiveArtifacts artifacts: '.context/analysis/**', allowEmptyArchive: true
    }
  }
}

Quality Gate Configuration

Thresholds

Metric	Warning	Error
Skill score	<100	<90
Duplication	>20%	>35%
File size	>300 lines	>500 lines
Missing description	N/A	Yes

Bypass Options

For emergency merges:

# GitHub Actions
if: "!contains(github.event.head_commit.message, '[skip quality]')"

# GitLab CI
except:
  variables:
    - $CI_COMMIT_MESSAGE =~ /skip quality/

Notifications

Slack Integration

- name: Notify on failure
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    channel-id: 'skill-quality'
    slack-message: |
      :warning: Skill quality gate failed
      PR: ${{ github.event.pull_request.html_url }}
      Failed skills: ${{ steps.evaluate.outputs.skills }}
  env:
    SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

Email Notifications

- name: Send report
  if: always()
  uses: dawidd6/action-send-mail@v3
  with:
    server_address: smtp.example.com
    to: team@example.com
    subject: Skill Audit Report - ${{ github.repository }}
    body: file://.context/analysis/skill-audit-*.md

Skill Taxonomy & Classification Guide

Purpose: Guide skill classification and domain organization for the Tekhne skill repository.

Last Updated: 2026-03-03
Domains: 12 (ci-cd, infrastructure, repository-mgmt, development, agentic-harness, testing, software-engineering, observability, documentation, package-mgmt, project-mgmt, specialized)

Domain Definitions

ci-cd/

Scope: CI/CD pipelines, deployment automation, release management

Includes:

GitHub Actions, GitLab CI, Azure Pipelines (pipeline platforms)
Jenkins (CI/CD orchestration)
Helm (Kubernetes package manager & deployment)
FluentBit (log forwarding for observability pipelines)

Excludes:

Infrastructure provisioning (use infrastructure/ instead)
Monitoring/alerting tools (use observability/ instead)

Structure: Paired generator/validator skills nested under tool name

ci-cd/
├── github-actions/{generator,validator}
├── gitlab-ci/{generator,validator}
└── ...

infrastructure/

Scope: Infrastructure as Code, cloud provisioning, container management

Includes:

Terraform, Terragrunt (IaC provisioning)
Ansible (configuration management)
Docker (containerization)
Kubernetes YAML (K8s resource definitions)
CloudFormation tools (cfn/ subdomain)
AWS CDK (aws-cdk/ subdomain)

Excludes:

Deployment pipelines (use ci-cd/ instead)
Monitoring tools (use observability/ instead)

Subdomains:

cfn/ - CloudFormation-specific tools (behavior-validator, template-compare)
aws-cdk/ - AWS CDK ecosystem (cdk-nag, future: cdk-patterns, cdk-constructs)

Structure: Paired tools nested, standalone tools at subdomain level

infrastructure/
├── terraform/{generator,validator}
├── cfn/
│   ├── behavior-validator/
│   └── template-compare/
└── aws-cdk/
    └── cdk-nag/

repository-mgmt/

Scope: Repository management, monorepo orchestration, git workflows, workspace organization

Includes:

Nx workspace tools (nx/ subdomain)
Future: Turborepo, Lerna, Rush, Moon
Git workflows, branching strategies
Workspace management patterns

Excludes:

General development tools not specific to repo management (use development/ instead)
CI/CD pipelines (use ci-cd/ instead)

Subdomains:

nx/ - Nx monorepo ecosystem

Why repository-mgmt (not monorepo): Broader scope includes general repository management, not exclusive to monorepos

Structure: Tools organized under ecosystem subdomain

repository-mgmt/
└── nx/
    ├── workspace-patterns/
    ├── executors/
    └── ...

development/

Scope: General-purpose development tools, languages, runtimes, formatters, linters

Includes:

Bun, TypeScript (languages/runtimes)
Biome (formatter/linter)
Commander.js (CLI framework)
Shell scripting tools (scripting/ subdomain)
Front-end web development tools (front-end/ subdomain)

Excludes:

Repository management (use repository-mgmt/ instead)
Agent framework configs (use agentic-harness/ instead)
Testing tools (use testing/ instead)

Subdomains:

scripting/ - Shell scripting and Makefile generation
front-end/ - Front-end web development (design tokens, theming, CSS)

Structure: Mix of standalone skills and subdomains

development/
├── bun-development/
├── typescript-advanced/
├── scripting/
│   ├── bash-script/{generator,validator}
│   └── makefile/{generator,validator}
└── front-end/
    ├── web-reference-sheet-generator/
    └── website-theme-porter/

agentic-harness/

Scope: Agent framework configurations, agent-specific documentation, agent collaboration patterns

Includes:

OpenCode configuration
AGENTS.md documentation (agent collaboration)
Future: Cursor, Claude Desktop, Windsurf, Aider configs

Excludes:

General documentation (use documentation/ instead)
Development tools not specific to agents (use development/ instead)

Why Top-Level: Agent frameworks and agent-specific tooling are a distinct category warranting their own domain for discoverability

Structure: Flat list of framework-specific skills

agentic-harness/
├── opencode/
├── agents-md/
└── [future: cursor, claude-desktop, etc.]

testing/

Scope: Testing methodologies, test frameworks, quality assurance, debugging workflows

Includes:

BDD testing (Behavior-Driven Development)
TDD (Test-Driven Development)
Skill quality auditor
UI debugging workflows

Excludes:

Software engineering principles (use software-engineering/ instead)
Observability/monitoring (use observability/ instead)

Structure: Flat list of testing methodology skills

testing/
├── bdd-testing/
├── test-driven-development/
├── skill-quality-auditor/
└── ui-debug-workflow/

software-engineering/

Scope: Software engineering principles, SOLID, design patterns, architecture patterns

Includes:

SOLID principles (SRP, OCP, LSP, ISP, DIP)
Clean Architecture (boundaries, dependencies, layers)
Design patterns (Strategy, Factory, Adapter, Observer, etc.)
Testable design (dependency injection, layer isolation)

Excludes:

Testing methodologies (use testing/ instead)
Documentation writing (use documentation/ instead)

Structure: Focused skills under unified tile

software-engineering/
├── solid-principles/
├── clean-architecture/
├── design-patterns/
├── testable-design/
└── design-principles/tile.json  (unified tile)

software-engineering/ └── software-design-principles/


---

### observability/
**Scope:** Monitoring, logging, debugging, metrics, alerting

**Includes:**
- PromQL (Prometheus query language)
- LogQL (Loki query language)
- K8s debugging tools

**Excludes:**
- Testing frameworks (use testing/ instead)
- CI/CD pipelines (use ci-cd/ instead)

**Structure:** Mix of paired tools and standalone skills

observability/ ├── promql/{generator,validator} ├── logql-generator/ └── k8s-debug/


---

### documentation/
**Scope:** General-purpose writing, technical communication, documentation practices

**Includes:**
- Markdown authoring (general markdown syntax)
- Acceptance criteria (user story requirements)
- Conventional commits (commit message standards)
- Plain English (technical writing for non-technical audiences)
- Journal entries (personal documentation)

**Excludes:**
- Agent-specific documentation (use agentic-harness/ instead)
- API documentation tools (may belong in development/)

**Why Not agents-md:** AGENTS.md is specifically for AI agent collaboration, not general technical documentation

**Structure:** Flat list of documentation skills

documentation/ ├── markdown-authoring/ ├── acceptance-criteria/ ├── conventional-commits/ ├── plain-english/ └── journal-entry-creator/


---

### package-mgmt/
**Scope:** Package management, version management, dependency management

**Includes:**
- Mise (cross-language version manager)
- Future: npm/yarn/pnpm, pip, cargo, gem, etc.

**Excludes:**
- Build tools (use development/ or repository-mgmt/ instead)
- Deployment tools (use ci-cd/ instead)

**Broad Scope:** Encompasses language-specific, cross-language, and Node ecosystem package management tools

**Structure:** Flat list of package management tools

package-mgmt/ └── mise-complete/


---

### project-mgmt/
**Scope:** Planning, prioritization, task management, project organization

**Includes:**
- Moscow prioritization (requirement prioritization)
- Implementation plan splitter (breaking down work)
- Context file creator (planning artifacts)

**Excludes:**
- Development workflows (use development/ or testing/ instead)
- Repository management (use repository-mgmt/ instead)

**Structure:** Flat list of planning/organization skills

project-mgmt/ ├── moscow-prioritization/ ├── planning-toolkit/ └── create-context-file/


---

### specialized/
**Scope:** Domain-specific tools that don't fit other categories

**Includes:**
- Colyseus multiplayer (game server framework)
- GitHub Copilot models (AI model listings)
- GitLab API (platform-specific API)

**Use Sparingly:** Only when skill truly doesn't belong elsewhere

**Structure:** Flat list of specialized skills

specialized/ ├── colyseus-multiplayer/ ├── github-copilot-models/ └── gitlab-api/


---

## Classification Decision Tree

Use this flowchart to classify new skills:

1. **Is it about deploying/releasing code?** → ci-cd/
2. **Is it about provisioning infrastructure?** → infrastructure/
3. **Is it specific to repository/workspace management?** → repository-mgmt/
4. **Is it about agent frameworks or agent collaboration?** → agentic-harness/
5. **Is it about monitoring/logging production systems?** → observability/
6. **Is it about testing or debugging?** → testing/
7. **Is it about software engineering principles/patterns?** → software-engineering/
8. **Is it about general-purpose writing/documentation?** → documentation/
9. **Is it about package/version management?** → package-mgmt/
10. **Is it a general development tool?** → development/
11. **Is it about project planning/organization?** → project-mgmt/
12. **Doesn't fit anywhere else?** → specialized/ (use sparingly)

---

## Borderline Cases

### agents-md (AGENTS.md documentation)
**Placement:** agentic-harness/  
**Rationale:** AGENTS.md files are specifically for AI agent collaboration and orchestration  
**Alternative considered:** documentation/ (general documentation) - rejected because agent-specific, not general-purpose writing

### design-principles tile (solid-principles, clean-architecture, design-patterns, testable-design)
**Placement:** software-engineering/ (top-level domain)  
**Rationale:** Foundational engineering principles split into focused single-responsibility skills  
**Alternative considered:** Keep monolithic hub - rejected for violation of single-responsibility and progressive disclosure
**Migration note:** Replaced monolithic `software-design-principles` hub (254 lines, 44 refs) with 4 focused skills under unified `pantheon-ai/design-principles` tile

### mise-complete
**Placement:** package-mgmt/ (new top-level domain)  
**Rationale:** Cross-language version/package management tool  
**Alternative considered:** development/ (dev tool) - rejected because package management is a distinct domain with future growth potential

### extending-nx-plugins
**Placement:** repository-mgmt/nx/  
**Rationale:** Teaches extending Nx itself, which is specific to repository management  
**Alternative considered:** development/ (general tooling) - rejected because too Nx-specific

### cdk-nag
**Placement:** infrastructure/aws-cdk/  
**Rationale:** AWS CDK-specific validation tool, warrants CDK subdomain  
**Alternative considered:** infrastructure/cfn/ (CFN tools) - rejected because CDK is distinct from CloudFormation, even though it generates CFN

### cfn-behavior-validator, cfn-template-compare
**Placement:** infrastructure/cfn/  
**Rationale:** Grouped CloudFormation-specific tools under subdomain  
**Alternative considered:** infrastructure/ (flat) - rejected because grouping related CFN tools improves organization

### bash-script, makefile
**Placement:** development/scripting/  
**Rationale:** Shell scripting is a specialized development activity  
**Alternative considered:** top-level scripting/ domain - rejected because scripting is fundamentally a development tool, nesting under development/ keeps related tools together

### ui-debug-workflow
**Placement:** testing/  
**Rationale:** Testing methodology for UI changes  
**Alternative considered:** development/ (dev tool) - rejected because primarily about testing, not general development

### web-reference-sheet-generator, website-theme-porter
**Placement:** development/front-end/  
**Rationale:** Front-end web development tools for design tokens, theming, and CSS workflows; general development tools not specific to testing, CI/CD, or infrastructure  
**Alternative considered:** specialized/ - rejected because they serve a broad, well-defined front-end development use case, not a niche domain that doesn't fit anywhere else

---

## Adding New Skills

When adding a new skill:

1. **Read domain definitions** above to understand scope and boundaries
2. **Run through decision tree** to identify best-fit domain
3. **Check for existing related skills** in candidate domain for consistency
4. **Consider generator/validator pairing:**
   - If creating both, use nested structure: `domain/tool/{generator,validator}/`
   - If standalone, place directly in domain or subdomain: `domain/skill-name/`
5. **Consider subdomain grouping:**
   - If 3+ related skills exist, consider creating subdomain
   - Example: infrastructure/cfn/ groups CloudFormation tools
6. **Document borderline decisions** in this file for future reference
7. **Update this guide** if skill doesn't fit existing domains

---

## Creating New Domains

Before creating a new domain:

1. **Verify at least 3-5 skills** would belong in the new domain
2. **Ensure it's not a subset** of existing domains
3. **Define clear scope** that doesn't overlap with existing domains
4. **Consider future growth:** Will this domain attract more skills?
5. **Update this guide** with domain definition and decision tree
6. **Update AGENTS.md** with new domain information
7. **Get team consensus** before restructuring

**Recent Examples:**
- `software-engineering/` created for design principles (foundational, cross-cutting)
- `agentic-harness/` created for agent frameworks (distinct category, future growth)
- `package-mgmt/` created for version managers (broad scope, future growth)

---

## Subdomain Strategy

**When to create a subdomain:**
- 3+ related skills under a common tool/platform (e.g., nx/, cfn/, aws-cdk/)
- Clear separation from other skills in the domain
- Future growth expected in that subdomain

**Current subdomains:**
- `infrastructure/aws-cdk/` - AWS CDK ecosystem (allows cdk-patterns, cdk-constructs)
- `infrastructure/cfn/` - CloudFormation tools (grouped related functionality)
- `repository-mgmt/nx/` - Nx ecosystem (allows turborepo, lerna, rush)
- `development/scripting/` - Shell scripting tools (bash, makefile)

**Future subdomain candidates:**
- `ci-cd/github/` - If we add github-release, github-checks, etc.
- `development/nodejs/` - If we add multiple Node.js-specific tools
- `agentic-harness/cursor/` - If we add multiple Cursor-specific skills

---

## Generator/Validator Pairing

**When to nest generator/validator:**
- Both skills exist for the same tool
- They share common concepts and workflows
- Users typically need both for complete workflow

**Structure:**

domain/ └── tool/ ├── generator/ │ ├── SKILL.md │ └── tile.json └── validator/ ├── SKILL.md └── tile.json

Examples:

ci-cd/github-actions/{generator,validator}
infrastructure/terraform/{generator,validator}
development/scripting/bash-script/{generator,validator}

When NOT to nest:

Only generator OR validator exists (place directly in domain)
Generator and validator are conceptually different tools (place separately)

Taxonomy Maintenance

Quarterly Review Process

Check domain balance - Avoid over-concentration in single domain
Evaluate subdomain candidates - Are there 3+ related skills that should be grouped?
Review borderline cases - Are any skills misclassified based on new context?
Update decision tree - Add new questions based on recent classification challenges
Document new patterns - Add borderline cases as they arise

Indicators for Domain Refinement

Domain has 20+ skills - Consider splitting into subdomains or multiple domains
Subdomain has 1 skill for 6+ months - Consider flattening into parent domain
Frequent classification debates - Scope definition needs clarification
Cross-domain dependencies - May indicate skills belong together

When to Split a Domain

Example: If infrastructure/ grows to 25+ skills, consider:

Split by cloud provider: infrastructure/aws/, infrastructure/gcp/, infrastructure/azure/
Split by tool type: infrastructure/iac/ (Terraform, etc.), infrastructure/containers/ (Docker, K8s)

When to Merge Domains

Example: If package-mgmt/ remains at 1-2 skills for 12+ months:

Consider merging into development/ domain
Document why package management didn’t need separate domain

Common Classification Questions

Q: Where do API client skills belong?

A: Depends on specificity:

Platform-specific (GitLab API) → specialized/
General HTTP/REST skills → development/
Integration with existing domains (AWS API) → infrastructure/

Q: Where do language-specific tools belong?

General-purpose language tools (TypeScript) → development/
Language-specific testing frameworks → testing/
Language package managers → package-mgmt/

Q: Where do deployment tools belong?

CI/CD pipelines and automation → ci-cd/
Infrastructure provisioning → infrastructure/
Container orchestration → infrastructure/

Q: Where do documentation generation tools belong?

General documentation → documentation/
Agent-specific documentation → agentic-harness/
API documentation (might belong in development/, case-by-case)

Q: What if a skill spans multiple domains?

Choose primary domain based on main use case
Document cross-domain nature in skill frontmatter
Consider splitting into multiple focused skills

Taxonomy Evolution History

2026-03-03 - Initial 12-Domain Structure

Reorganized from flat 63-skill structure
Created domains: ci-cd, infrastructure, repository-mgmt, development, agentic-harness, testing, software-engineering, observability, documentation, package-mgmt, project-mgmt, specialized
Renamed monorepo → repository-mgmt (broader scope)
Moved agents-md from documentation to agentic-harness
Created subdomains: infrastructure/cfn/, infrastructure/aws-cdk/, repository-mgmt/nx/, development/scripting/

Rationale: Improve discoverability with 63 skills, logical grouping, room for future growth

References

Agent Skills Specification - Cross-harness compatibility
Repository: /Users/thomas.roche/Projects/github/pantheon-org/tekhne
AGENTS.md: Repository collaboration guide with domain references

Maintainers: Update this guide when adding domains, reclassifying skills, or encountering new classification challenges.

Canonical SKILL.md Template

Use this as the structural blueprint when authoring or refactoring any SKILL.md file. Copy the sections that apply; omit optional sections only when genuinely not needed.

Minimal Compliant SKILL.md

---
name: {kebab-case-name}
description: "{150-300 char description with domain keywords and trigger phrases. Use when...}"
---

# {Title Case Skill Name}

## When to Use

- {Trigger scenario 1}
- {Trigger scenario 2}

## When Not to Use

- {Anti-trigger scenario 1}

## Principles

1. {Core principle or philosophy — the mental model the agent must adopt}
2. {Second principle}

## Workflow

1. {Step 1} — **Verify:** {how to confirm this succeeded}
2. {Step 2}
3. {Step 3} — **Stop if:** {blockers that require human input}

## Quick Commands

```bash
# {Command description}
{command}
```

Expected result: {what success looks like}

## Anti-Patterns

### NEVER {do X}

**WHY:** {reason this fails}

**BAD:** {concrete example of the anti-pattern}
**GOOD:** {concrete example of the correct approach}

**Consequence:** {what breaks when this anti-pattern is used}

## References

| Topic | Reference | When to Use |
| --- | --- | --- |
| {What this reference covers} | [{Display Name}](references/{file}.md) | {Scenario when agent should load this} |
| {External resource description} | [{Title}](https://example.com) | {When to consult official docs} |

Section-by-Section Rules

Frontmatter

---
name: skill-name          # Required. Must match directory name. kebab-case only.
description: "..."        # Required. 150-300 chars. Include domain keywords + trigger phrases.
---

Heading

H1 (#) is the skill title — title case, human-readable
Do not repeat the frontmatter name verbatim; expand it

When to Use / When Not to Use

List format, 2-5 bullets each
“When Not to Use” prevents misfire on adjacent skills
Required for D2 score

Principles

2-5 numbered items
Each is a short declarative statement the agent should internalize
These are the philosophical framing (D2 Mindset component)

Workflow

Numbered steps (not bullets)
Each step includes a Verify: checkpoint OR a Stop if: gate
Maximum 8 steps before the workflow should be split into sub-sections

Quick Commands

One fenced code block per command group
Every block ends with Expected result: on its own line
Use bunx, npx, or language-agnostic paths — no harness-specific prefixes

Anti-Patterns

H3 heading: ### NEVER <imperative phrase>
WHY: explains the underlying risk or failure mode
BAD: / GOOD: shows concrete code or config examples side-by-side
Consequence: states what breaks — security, reliability, maintainability
Minimum 3 anti-patterns for D3 score; 5+ for A-grade

References (Table Standard)

The ## References section MUST:

Be the last H2 in the file
Use a Markdown table with exactly these column headers: Topic, Reference, When to Use
Have every Reference cell contain a markdown link [text](url) — no bare paths, no bare URLs
Have Topic describe what the reference covers
Have When to Use state the concrete scenario that tells an agent to load it

Optional H3 sub-headings are allowed to group rows by theme (e.g. ### Generators, ### Executors).

Full example:

## References

### Core

| Topic | Reference | When to Use |
| --- | --- | --- |
| Rule pack options, Aspects API, and suppression patterns | [Implementation Guide](references/implementation-guide.md) | First-time setup or rule pack selection |
| Complete list of AwsSolutions rules and severity levels | [Rule Packs](references/rule-packs.md) | Triaging an unfamiliar finding |

### External

| Topic | Reference | When to Use |
| --- | --- | --- |
| Official cdk-nag rule catalog and release notes | [cdk-nag GitHub](https://github.com/cdklabs/cdk-nag) | Checking rule IDs or upgrade behavior |

Common Mistakes to Avoid

Mistake	Fix
Bullet list in `## References` instead of table	Convert to `Topic \| Reference \| When to Use` table
Heading `## Resources` or `## See Also`	Rename to exactly `## References`
Bare URL in Reference column: `https://...`	Wrap as `[Title](https://...)`
Missing `When to Use` column	Add column — “When to consult” forces actionable descriptions
`## References` is not the last H2	Move it to the end of the file
References section appears mid-file before Anti-Patterns	Reorder: Anti-Patterns → References

Tessl Registry Compliance Framework

Supplementary validation checks for skills intended for Tessl registry submission. These checks extend the core 9-dimension framework with agent-agnostic and performance-focused evaluations.

Use after: Core 9-dimension evaluation (≥126 points required) Target: 100% tessl compliance for registry acceptance

Overview

Tessl focuses on performance-evaluated, agent-agnostic skills that provide measurable effectiveness improvements. This framework adds 3 supplementary validation areas:

Agent-Agnostic Validation - Ensure cross-platform compatibility
Performance Metrics Integration - Quantify effectiveness improvements
Cross-Platform Compatibility - Validate tool/feature support

Agent-Agnostic Validation (Pass/Fail)

Purpose: Ensure skills work across different AI assistant platforms without agent-specific dependencies.

Validation Checks

❌ NEVER: Agent-Specific Tool Dependencies

Check allowed-tools frontmatter for agent-specific tools:

# Bad - Claude Code specific
allowed-tools: [claude-artifact, claude-codebase]

# Good - Universal tools
allowed-tools: [bash, edit, read, write]

Auto-check pattern: Flag tools containing agent names (claude-, cursor-, openai-, etc.)

❌ NEVER: Platform-Specific Instructions

Scan content for agent-specific references:

❌ BAD: "Tell Claude to run the command"
❌ BAD: "Use Cursor's autocomplete feature"  
❌ BAD: "In OpenAI's interface, click..."

✅ GOOD: "Run the command using your bash tool"
✅ GOOD: "Use your code completion capabilities"
✅ GOOD: "Execute the following workflow"

❌ NEVER: Hardcoded Agent Behaviors

Avoid assuming specific agent capabilities:

❌ BAD: "Since you can't execute code directly..."
❌ BAD: "Use your web browsing to..."
❌ BAD: "Your image generation will..."

✅ GOOD: "If code execution tools are available..."
✅ GOOD: "When web access is supported..."
✅ GOOD: "For agents with image capabilities..."

Scoring

PASS: No agent-specific dependencies detected
FAIL: Any agent-specific references found

Performance Metrics Integration (Pass/Fail)

Purpose: Ensure skills define measurable effectiveness improvements that can be evaluated.

Required Components

1. Success Metrics Definition

Skills must include quantifiable outcomes:

## Success Metrics

This skill provides:
- ✅ 85% reduction in configuration errors
- ✅ 3x faster setup time (5 minutes vs 15 minutes)
- ✅ 100% compliance with security standards

2. Before/After Scenarios

Show clear improvement examples:

## Effectiveness Examples

### Before Using This Skill
- Manual setup takes 30+ commands
- 40% failure rate on first attempt
- Inconsistent configuration across environments

### After Using This Skill  
- One-command deployment
- <5% failure rate
- Standardized, reproducible environments

3. Measurable Outcomes

Define what “effective use” looks like:

## Expected Outcomes

When applied correctly, this skill delivers:
- Time savings: 60-90% reduction in task duration
- Quality improvement: 95%+ adherence to best practices
- Error reduction: <10% incident rate vs 30% baseline

Validation Checks

Required sections: “Success Metrics”, “Expected Outcomes”, or equivalent
Quantified claims: Must include specific numbers (percentages, time, error rates)
Comparative data: Before/after or baseline comparisons

Scoring

PASS: Contains measurable effectiveness claims with quantification
FAIL: No performance metrics or only qualitative claims

Cross-Platform Compatibility (Pass/Fail)

Purpose: Validate that skill instructions work across different development environments and agent platforms.

Tool Compatibility Checks

Universal Tools Only

Verify all referenced tools are widely supported:

✅ GOOD: bash, read, write, edit, glob, grep
✅ GOOD: Standard CLI tools (git, npm, docker)
✅ GOOD: Common development commands

❌ BAD: Agent-specific tools
❌ BAD: Proprietary extensions
❌ BAD: Platform-locked features

Command Portability

Ensure shell commands work across operating systems:

# Bad - macOS specific
brew install package

# Good - Cross-platform with options
# Install using your package manager:
# - macOS: brew install package  
# - Ubuntu: apt install package
# - Windows: choco install package

Path References

Use portable path conventions:

❌ BAD: /usr/local/bin/tool (Unix-specific)
❌ BAD: C:\Program Files\tool (Windows-specific)

✅ GOOD: Add tool to your PATH
✅ GOOD: $(which tool) or equivalent

Agent Feature Assumptions

Avoid assuming specific agent capabilities:

❌ BAD: "Use your built-in web scraping"
❌ BAD: "Generate an image with DALL-E"
❌ BAD: "Create a diagram with your drawing tools"

✅ GOOD: "If web scraping tools are available..."
✅ GOOD: "Using image generation capabilities..."
✅ GOOD: "With diagram creation tools..."

Validation Process

Tool Audit: Check all tool references for universality
Command Review: Verify cross-platform shell commands
Feature Check: Flag agent-specific capability assumptions
Documentation Review: Ensure instructions work for any agent

Scoring

PASS: No platform-specific dependencies detected
FAIL: Contains non-portable tools or commands

Implementation Guide

For Skill Authors

When preparing skills for Tessl submission:

Run core evaluation first: Achieve A-grade (≥126 points)
Apply tessl validations: Use checks in this framework
Fix compatibility issues: Remove agent-specific dependencies
Add performance metrics: Quantify effectiveness improvements
Verify portability: Test commands across platforms

For Auditors

Integration with existing skill-quality-auditor workflow:

# Standard evaluation first
skill-auditor evaluate <skill-name> --json

# Then apply tessl compliance checks
sh ./scripts/tessl-compliance-check.sh <skill-name>

Automated Validation

Agent-Agnostic Check:

# Check for agent-specific terms
grep -ri "claude\|cursor\|openai\|copilot\|gemini" skills/<skill>/

Tool Compatibility Check:

# Extract and validate allowed-tools
yq '.allowed-tools[]?' skills/<skill>/SKILL.md | grep -E "(claude|cursor|openai)-"

Performance Metrics Check:

# Look for quantified outcomes
grep -E "[0-9]+(%|x|times|\s(seconds|minutes|hours)|reduction|improvement)" skills/<skill>/

Integration with Core Framework

This framework supplements, not replaces, the 9-dimension evaluation:

Check Type	When to Apply	Pass Criteria
Core 9-Dimension	Always	≥126 points (A-grade)
Agent-Agnostic	Tessl submission	No agent-specific deps
Performance Metrics	Tessl submission	Quantified effectiveness
Cross-Platform	Tessl submission	Universal compatibility

Skill Quality Auditor

Prerequisites

Quick Start

When to Use

When Not to Use

Workflow

Mindset

Anti-Patterns (Summary)

Examples

Self-Audit

References

Framework

Operations

Custom Metrics

Overview

When to Add Custom Metrics

Custom Metric Design

Metric Structure

Example Custom Metrics

D9: Security Compliance (15 points)

D10: Accessibility (10 points)

D11: Performance (10 points)

Implementation

Custom Evaluation Script

Custom Configuration

Organization-Specific Standards

Enterprise Compliance

Industry-Specific

Healthcare (HIPAA)

Finance (PCI-DSS)

Metric Integration

Modified Grade Scale

Combined Report

Best Practices

DO

DON’T

Metric Maintenance

Quarterly Review

Metric Deprecation

See Also

Advanced Pattern Recognition for Skill Quality

Quality Patterns

A-Grade Skills (≥108) typically exhibit

Common Failure Patterns

Improvement Strategies

For Knowledge Delta gaps

For Progressive Disclosure gaps

For Anti-Pattern gaps

Advanced Pattern Matching

Skill Maturity Indicators

Content Quality Signals

Red Flags for Quality Issues

Activation Trigger Patterns

Example: Comprehensive Trigger Coverage

Anti-Pattern: Narrow Triggers

🤖 Algorithmic Pattern Recognition

Enhanced Duplication Detection

Algorithm: Multi-Metric Similarity Analysis

Semantic Similarity Engine

Algorithm: Multi-Layer Semantic Analysis

Machine Learning Quality Prediction

Algorithm: 50-Dimension Feature Classification

Pattern Recognition Workflow

Advanced Pattern Libraries

Trends Analysis

Overview

Data Collection

Weekly Snapshot

Snapshot Format

Trend Analysis

Quality Score Trend

Grade Distribution Trend

Duplication Trend

Trend Reports

Monthly Trend Report

Regression Detection

Historical Data Storage

Directory Structure

Data Retention

Comparative Analysis