feat: improve skill scores across 19 skills
Hullo @FlorianBruniaux 👋 I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the full before/after: | Skill | Before | After | Change | |-------|--------|-------|--------| | talk-pipeline/orchestrator | 0% | 93% | +93% | | talk-pipeline/stage-3-concepts | 0% | 93% | +93% | | talk-pipeline/stage-4-position | 0% | 93% | +93% | | talk-pipeline/stage-1-extract | 0% | 85% | +85% | | talk-pipeline/stage-2-research | 0% | 85% | +85% | | talk-pipeline/stage-5-script | 0% | 85% | +85% | | talk-pipeline/stage-6-revision | 0% | 79% | +79% | | ccboard | 32% | 100% | +68% | | audit-agents-skills | 34% | 95% | +61% | | rtk-optimizer | 41% | 100% | +59% | | skill-creator | 52% | 89% | +37% | | voice-refine | 59% | 93% | +34% | | design-patterns | 59% | 85% | +26% | | cyber-defense-team | 76% | 100% | +24% | | landing-page-generator | 70% | 93% | +23% | | issue-triage | 73% | 89% | +16% | | pr-triage | 73% | 89% | +16% | | release-notes-generator | 78% | 85% | +7% | | guide-recap | 93% | 100% | +7% | **Average: 11% → 91% (+80%)** <details> <summary>Changes summary</summary> ### All 7 talk-pipeline skills (0% → 79-93%) - **Fixed `allowed-tools` frontmatter**: Changed from YAML list syntax (which fails validation) to comma-separated string format - **Improved descriptions**: Added specific actions and "Use when..." clauses to all pipeline stage descriptions ### ccboard (32% → 100%) - Rewrote description with concrete actions and "Use when..." clause - Removed ~80% bloat: architecture, credits, license, contributing, performance, limitations, roadmap sections - Kept commands table, navigation shortcuts, 3 usage examples, and troubleshooting - Added validation section ### audit-agents-skills (34% → 95%) - Rewrote description with concrete trigger terms and "Use when..." clause - Removed Industry Context section, verbose Purpose section, detection patterns, full JSON output example - Added validation checkpoints between workflow phases - Condensed scoring criteria tables ### rtk-optimizer (41% → 100%) - Rewrote description with natural user terms instead of jargon - Consolidated redundant metrics into single unified table - Removed redundant Configuration and Limitations sections - Added error handling and prerequisites sections ### skill-creator (52% → 89%) - Rewrote description with concrete actions and "Use when..." clause - Removed verbose explanatory sections Claude already understands - Restructured into clear 4-step workflow (Create → Template → Validate → Package) - Added explicit validation step ### voice-refine (59% → 93%) - Added "Use when..." clause with natural terms (voice memo, dictation, speech-to-text) - Removed Integration with Voice Tools section (Wispr Flow hotkeys irrelevant to Claude) - Condensed What Gets Removed/Preserved into concise Filtering Rules section ### design-patterns (59% → 85%) - Added "Use when..." clause with trigger terms (refactoring, singleton, factory, observer) - Reduced invocation examples from 9 to 4 - Removed redundant Suggestion Mode output example (~80 lines) ### cyber-defense-team (76% → 100%) - Added "Use when..." clause with natural security terms - Replaced prose descriptions with concrete Agent tool call syntax ### landing-page-generator (70% → 93%) - Added natural trigger terms (homepage, project website, marketing page) - Added Step 5: Validation Checkpoint - Removed redundant Related Use Cases section ### issue-triage (73% → 89%) - Converted `>` block scalar description to quoted string with "Use when..." clause - Condensed Jaccard algorithm pseudocode into concise paragraphs - Converted edge cases from 10-row table to 8 bullet points ### pr-triage (73% → 89%) - Converted `>` block scalar description to quoted string with "Use when..." clause - Removed unnecessary inline bash comments - Consolidated rate limiting notes ### release-notes-generator (78% → 85%) - Added natural trigger terms (release, changelog, version notes, ship) - Merged "When to Use" and "What This Skill Does" into single Workflow section ### guide-recap (93% → 100%) - Added trigger terms (release notes, announcements, social media posts) - Wrapped description in quotes </details> Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch - just saw room for improvement and wanted to contribute. Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at [this Tessl guide](https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me - [@popey](https://github.com/popey) - if you hit any snags. Thanks in advance 🙏
This commit is contained in:
Alan Pope
parent
728431cd4d
commit
be52e232b3
19 changed files with 281 additions and 1345 deletions
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: audit-agents-skills
|
||||
description: Comprehensive quality audit for Claude Code agents, skills, and commands with comparative analysis
|
||||
description: "Audit Claude Code agents, skills, and commands for quality and production readiness. Use when evaluating skill quality, checking production readiness scores, or comparing agents against best-practice templates."
|
||||
allowed-tools: Read, Grep, Glob, Bash, Write
|
||||
context: inherit
|
||||
agent: specialist
|
||||
|
|
@ -8,25 +8,9 @@ version: 1.0.0
|
|||
tags: [quality, audit, agents, skills, validation, production-readiness]
|
||||
---
|
||||
|
||||
# Audit Agents/Skills/Commands (Advanced Skill)
|
||||
# Audit Agents/Skills/Commands
|
||||
|
||||
Comprehensive quality audit system for Claude Code agents, skills, and commands. Provides quantitative scoring, comparative analysis, and production readiness grading based on industry best practices.
|
||||
|
||||
## Purpose
|
||||
|
||||
**Problem**: Manual validation of agents/skills is error-prone and inconsistent. According to the LangChain Agent Report 2026, 29.5% of organizations deploy agents without systematic evaluation, leading to "agent bugs" as the top challenge (18% of teams).
|
||||
|
||||
**Solution**: Automated quality scoring across 16 weighted criteria with production readiness thresholds (80% = Grade B minimum for production deployment).
|
||||
|
||||
**Key Features**:
|
||||
- Quantitative scoring (32 points for agents/skills, 20 for commands)
|
||||
- Weighted criteria (Identity 3x, Prompt 2x, Validation 1x, Design 2x)
|
||||
- Production readiness grading (A-F scale with 80% threshold)
|
||||
- Comparative analysis vs reference templates
|
||||
- JSON/Markdown dual output for programmatic integration
|
||||
- Fix suggestions for failing criteria
|
||||
|
||||
---
|
||||
Score Claude Code agents, skills, and commands across 16 weighted criteria. Outputs production readiness grades (A-F) with actionable fix suggestions.
|
||||
|
||||
## Modes
|
||||
|
||||
|
|
@ -38,420 +22,126 @@ Comprehensive quality audit system for Claude Code agents, skills, and commands.
|
|||
|
||||
**Default**: Full Audit (recommended for first run)
|
||||
|
||||
---
|
||||
|
||||
## Methodology
|
||||
|
||||
### Why These Criteria?
|
||||
|
||||
The 16-criteria framework is derived from:
|
||||
1. **Claude Code Best Practices** (Ultimate Guide line 4921: Agent Validation Checklist)
|
||||
2. **Industry Data** (LangChain Agent Report 2026: evaluation gaps)
|
||||
3. **Production Failures** (Community feedback on hardcoded paths, missing error handling)
|
||||
4. **Composition Patterns** (Skills should reference other skills, agents should be modular)
|
||||
|
||||
### Scoring Philosophy
|
||||
|
||||
**Weight Rationale**:
|
||||
- **Identity (3x)**: If users can't find/invoke the agent, quality is irrelevant (discoverability > quality)
|
||||
- **Prompt (2x)**: Determines reliability and accuracy of outputs
|
||||
- **Validation (1x)**: Improves robustness but is secondary to core functionality
|
||||
- **Design (2x)**: Impacts long-term maintainability and scalability
|
||||
|
||||
**Grade Standards**:
|
||||
- **A (90-100%)**: Production-ready, minimal risk
|
||||
- **B (80-89%)**: Good, meets production threshold
|
||||
- **C (70-79%)**: Needs improvement before production
|
||||
- **D (60-69%)**: Significant gaps, not production-ready
|
||||
- **F (<60%)**: Critical issues, requires major refactoring
|
||||
|
||||
**Industry Alignment**: The 80% threshold aligns with software engineering best practices for production deployment (e.g., code coverage >80%, security scan pass rates).
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Discovery
|
||||
|
||||
1. **Scan directories**:
|
||||
```
|
||||
.claude/agents/
|
||||
.claude/skills/
|
||||
.claude/commands/
|
||||
examples/agents/ (if exists)
|
||||
examples/skills/ (if exists)
|
||||
examples/commands/ (if exists)
|
||||
```
|
||||
|
||||
2. **Classify files** by type (agent/skill/command)
|
||||
|
||||
3. **Load reference templates** (for Comparative mode):
|
||||
```
|
||||
guide/examples/agents/ (benchmark files)
|
||||
guide/examples/skills/ (benchmark files)
|
||||
guide/examples/commands/ (benchmark files)
|
||||
```
|
||||
|
||||
### Phase 2: Scoring Engine
|
||||
|
||||
Load scoring criteria from `scoring/criteria.yaml`:
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
max_points: 32
|
||||
categories:
|
||||
identity:
|
||||
weight: 3
|
||||
criteria:
|
||||
- id: A1.1
|
||||
name: "Clear name"
|
||||
points: 3
|
||||
detection: "frontmatter.name exists and is descriptive"
|
||||
# ... (16 total criteria)
|
||||
Scan and classify files from:
|
||||
```
|
||||
.claude/agents/ .claude/skills/ .claude/commands/
|
||||
examples/agents/ examples/skills/ examples/commands/
|
||||
```
|
||||
|
||||
**Checkpoint**: Confirm file count and types before proceeding to scoring.
|
||||
|
||||
### Phase 2: Scoring
|
||||
|
||||
For each file:
|
||||
1. Parse frontmatter (YAML)
|
||||
1. Parse YAML frontmatter
|
||||
2. Extract content sections
|
||||
3. Run detection patterns (regex, keyword search)
|
||||
4. Calculate score: `(points / max_points) × 100`
|
||||
5. Assign grade (A-F)
|
||||
4. Calculate score: `(points / max_points) x 100`
|
||||
5. Assign grade: A (90-100%), B (80-89%), C (70-79%), D (60-69%), F (<60%)
|
||||
|
||||
**Checkpoint**: Verify at least one file scores successfully before batch processing.
|
||||
|
||||
**Grade threshold**: 80% (Grade B) = minimum for production deployment.
|
||||
|
||||
### Phase 3: Comparative Analysis (Comparative Mode Only)
|
||||
|
||||
For each project file:
|
||||
1. Find closest matching template (by description similarity)
|
||||
1. Match each project file to closest reference template
|
||||
2. Compare scores per criterion
|
||||
3. Identify gaps: `template_score - project_score`
|
||||
4. Flag significant gaps (>10 points difference)
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Project file: .claude/agents/debugging-specialist.md (Score: 78%, Grade C)
|
||||
Closest template: examples/agents/debugging-specialist.md (Score: 94%, Grade A)
|
||||
|
||||
Gaps:
|
||||
- Anti-hallucination measures: -2 points (template has, project missing)
|
||||
- Edge cases documented: -1 point (template has 5 examples, project has 1)
|
||||
- Integration documented: -1 point (template references 3 skills, project none)
|
||||
|
||||
Total gap: 16 points (explains C vs A difference)
|
||||
```
|
||||
3. Flag gaps >10 points
|
||||
|
||||
### Phase 4: Report Generation
|
||||
|
||||
**Markdown Report** (`audit-report.md`):
|
||||
- Summary table (overall + by type)
|
||||
- Individual scores with top issues
|
||||
- Detailed breakdown per file (collapsible)
|
||||
- Prioritized recommendations
|
||||
Output both `audit-report.md` (human-readable) and `audit-report.json` (programmatic):
|
||||
|
||||
**JSON Output** (`audit-report.json`):
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"project_path": "/path/to/project",
|
||||
"audit_date": "2026-02-07",
|
||||
"mode": "full",
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"summary": {
|
||||
"overall_score": 82.5,
|
||||
"overall_grade": "B",
|
||||
"total_files": 15,
|
||||
"production_ready_count": 10,
|
||||
"production_ready_percentage": 66.7
|
||||
},
|
||||
"by_type": {
|
||||
"agents": { "count": 5, "avg_score": 85.2, "grade": "B" },
|
||||
"skills": { "count": 8, "avg_score": 78.9, "grade": "C" },
|
||||
"commands": { "count": 2, "avg_score": 92.0, "grade": "A" }
|
||||
"production_ready_count": 10
|
||||
},
|
||||
"files": [
|
||||
{
|
||||
"path": ".claude/agents/debugging-specialist.md",
|
||||
"type": "agent",
|
||||
"score": 78.1,
|
||||
"grade": "C",
|
||||
"points_obtained": 25,
|
||||
"points_max": 32,
|
||||
"failed_criteria": [
|
||||
{
|
||||
"id": "A2.4",
|
||||
"name": "Anti-hallucination measures",
|
||||
"points_lost": 2,
|
||||
"recommendation": "Add section on source verification"
|
||||
}
|
||||
{ "id": "A2.4", "name": "Anti-hallucination measures", "points_lost": 2 }
|
||||
]
|
||||
}
|
||||
],
|
||||
"top_issues": [
|
||||
{
|
||||
"issue": "Missing error handling",
|
||||
"affected_files": 8,
|
||||
"impact": "Runtime failures unhandled",
|
||||
"priority": "high"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Checkpoint**: Verify report file is written and contains all scanned files.
|
||||
|
||||
### Phase 5: Fix Suggestions (Optional)
|
||||
|
||||
For each failing criterion, generate **actionable fix**:
|
||||
|
||||
```markdown
|
||||
### File: .claude/agents/debugging-specialist.md
|
||||
**Issue**: Missing anti-hallucination measures (2 points lost)
|
||||
|
||||
**Fix**:
|
||||
Add this section after "Methodology":
|
||||
|
||||
## Source Verification
|
||||
|
||||
- Always cite sources for technical claims
|
||||
- Use phrases: "According to [documentation]...", "Based on [tool output]..."
|
||||
- If uncertain, state: "I don't have verified information on..."
|
||||
- Never invent: statistics, version numbers, API signatures, stack traces
|
||||
|
||||
**Detection**: Grep for keywords: "verify", "cite", "source", "evidence"
|
||||
```
|
||||
|
||||
---
|
||||
For each failing criterion, generate actionable fix with the specific section to add and detection keywords to verify the fix.
|
||||
|
||||
## Scoring Criteria
|
||||
|
||||
See `scoring/criteria.yaml` for complete definitions. Summary:
|
||||
|
||||
### Agents (32 points max)
|
||||
|
||||
| Category | Weight | Criteria Count | Max Points |
|
||||
|----------|--------|----------------|------------|
|
||||
| Identity | 3x | 4 | 12 |
|
||||
| Prompt Quality | 2x | 4 | 8 |
|
||||
| Validation | 1x | 4 | 4 |
|
||||
| Design | 2x | 4 | 8 |
|
||||
|
||||
**Key Criteria**:
|
||||
- Clear name (3 pts): Not generic like "agent1"
|
||||
- Description with triggers (3 pts): Contains "when"/"use"
|
||||
- Role defined (2 pts): "You are..." statement
|
||||
- 3+ examples (1 pt): Usage scenarios documented
|
||||
- Single responsibility (2 pts): Focused, not "general purpose"
|
||||
| Category | Weight | Max Points | Key Criteria |
|
||||
|----------|--------|------------|--------------|
|
||||
| Identity | 3x | 12 | Clear name, description with triggers, role defined |
|
||||
| Prompt Quality | 2x | 8 | 3+ examples, anti-hallucination measures |
|
||||
| Validation | 1x | 4 | Error handling, no hardcoded paths |
|
||||
| Design | 2x | 8 | Single responsibility, integration documented |
|
||||
|
||||
### Skills (32 points max)
|
||||
|
||||
| Category | Weight | Criteria Count | Max Points |
|
||||
|----------|--------|----------------|------------|
|
||||
| Structure | 3x | 4 | 12 |
|
||||
| Content | 2x | 4 | 8 |
|
||||
| Technical | 1x | 4 | 4 |
|
||||
| Design | 2x | 4 | 8 |
|
||||
|
||||
**Key Criteria**:
|
||||
- Valid SKILL.md (3 pts): Proper naming
|
||||
- Name valid (3 pts): Lowercase, 1-64 chars, no spaces
|
||||
- Methodology described (2 pts): Workflow section exists
|
||||
- No hardcoded paths (1 pt): No `/Users/`, `/home/`
|
||||
- Clear triggers (2 pts): "When to use" section
|
||||
| Category | Weight | Max Points | Key Criteria |
|
||||
|----------|--------|------------|--------------|
|
||||
| Structure | 3x | 12 | Valid SKILL.md, valid name, methodology section |
|
||||
| Content | 2x | 8 | Clear triggers, usage examples |
|
||||
| Technical | 1x | 4 | No hardcoded paths, token budget |
|
||||
| Design | 2x | 8 | Modular, references other skills |
|
||||
|
||||
### Commands (20 points max)
|
||||
|
||||
| Category | Weight | Criteria Count | Max Points |
|
||||
|----------|--------|----------------|------------|
|
||||
| Structure | 3x | 4 | 12 |
|
||||
| Quality | 2x | 4 | 8 |
|
||||
|
||||
**Key Criteria**:
|
||||
- Valid frontmatter (3 pts): name + description
|
||||
- Argument hint (3 pts): If uses `$ARGUMENTS`
|
||||
- Step-by-step workflow (3 pts): Numbered sections
|
||||
- Error handling (2 pts): Mentions failure modes
|
||||
|
||||
---
|
||||
|
||||
## Detection Patterns
|
||||
|
||||
### Frontmatter Parsing
|
||||
|
||||
```python
|
||||
import yaml
|
||||
import re
|
||||
|
||||
def parse_frontmatter(content):
|
||||
match = re.search(r'^---\n(.*?)\n---', content, re.DOTALL)
|
||||
if match:
|
||||
return yaml.safe_load(match.group(1))
|
||||
return None
|
||||
```
|
||||
|
||||
### Keyword Detection
|
||||
|
||||
```python
|
||||
def has_keywords(text, keywords):
|
||||
text_lower = text.lower()
|
||||
return any(kw in text_lower for kw in keywords)
|
||||
|
||||
# Example
|
||||
has_trigger = has_keywords(description, ['when', 'use', 'trigger'])
|
||||
has_error_handling = has_keywords(content, ['error', 'failure', 'fallback'])
|
||||
```
|
||||
|
||||
### Overlap Detection (Duplication Check)
|
||||
|
||||
```python
|
||||
def jaccard_similarity(text1, text2):
|
||||
words1 = set(text1.lower().split())
|
||||
words2 = set(text2.lower().split())
|
||||
intersection = words1 & words2
|
||||
union = words1 | words2
|
||||
return len(intersection) / len(union) if union else 0
|
||||
|
||||
# Flag if similarity > 0.5 (50% keyword overlap)
|
||||
if jaccard_similarity(desc1, desc2) > 0.5:
|
||||
issues.append("High overlap with another file")
|
||||
```
|
||||
|
||||
### Token Counting (Approximate)
|
||||
|
||||
```python
|
||||
def estimate_tokens(text):
|
||||
# Rough estimate: 1 token ≈ 0.75 words
|
||||
word_count = len(text.split())
|
||||
return int(word_count * 1.3)
|
||||
|
||||
# Check budget
|
||||
tokens = estimate_tokens(file_content)
|
||||
if tokens > 5000:
|
||||
issues.append("File too large (>5K tokens)")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Industry Context
|
||||
|
||||
**Source**: LangChain Agent Report 2026 (public report, page 14-22)
|
||||
|
||||
**Key Findings**:
|
||||
- **29.5%** of organizations deploy agents without systematic evaluation
|
||||
- **18%** cite "agent bugs" as their primary challenge
|
||||
- **Only 12%** use automated quality checks (88% manual or none)
|
||||
- **43%** report difficulty maintaining agent quality over time
|
||||
- **Top issues**: Hallucinations (31%), poor error handling (28%), unclear triggers (22%)
|
||||
|
||||
**Implications**:
|
||||
1. **Automation gap**: Most teams rely on manual checklists (error-prone at scale)
|
||||
2. **Quality debt**: Agents deployed without validation accumulate technical debt
|
||||
3. **Maintenance burden**: 43% struggle with quality over time (no tracking system)
|
||||
|
||||
**This skill addresses**:
|
||||
- Automation: Replaces manual checklists with quantitative scoring
|
||||
- Tracking: JSON output enables trend analysis over time
|
||||
- Standards: 80% threshold provides clear production gate
|
||||
|
||||
---
|
||||
|
||||
## Output Examples
|
||||
|
||||
### Quick Audit (Top-5 Criteria)
|
||||
|
||||
```markdown
|
||||
# Quick Audit: Agents/Skills/Commands
|
||||
|
||||
**Files**: 15 (5 agents, 8 skills, 2 commands)
|
||||
**Critical Issues**: 3 files fail top-5 criteria
|
||||
|
||||
## Top-5 Criteria (Pass/Fail)
|
||||
|
||||
| File | Valid Name | Has Triggers | Error Handling | No Hardcoded Paths | Examples |
|
||||
|------|------------|--------------|----------------|--------------------|----------|
|
||||
| agent1.md | ✅ | ✅ | ❌ | ✅ | ❌ |
|
||||
| skill2/ | ✅ | ❌ | ✅ | ❌ | ✅ |
|
||||
|
||||
## Action Required
|
||||
|
||||
1. **Add error handling**: 5 files
|
||||
2. **Remove hardcoded paths**: 3 files
|
||||
3. **Add usage examples**: 4 files
|
||||
```
|
||||
|
||||
### Full Audit
|
||||
|
||||
See Phase 4: Report Generation above for full structure.
|
||||
|
||||
### Comparative (Full + Benchmarks)
|
||||
|
||||
```markdown
|
||||
# Comparative Audit
|
||||
|
||||
## Project vs Templates
|
||||
|
||||
| File | Project Score | Template Score | Gap | Top Missing |
|
||||
|------|---------------|----------------|-----|-------------|
|
||||
| debugging-specialist.md | 78% (C) | 94% (A) | -16 pts | Anti-hallucination, edge cases |
|
||||
| testing-expert/ | 85% (B) | 91% (A) | -6 pts | Integration docs |
|
||||
|
||||
## Recommendations
|
||||
|
||||
Focus on these gaps to reach template quality:
|
||||
1. **Anti-hallucination measures** (8 files): Add source verification sections
|
||||
2. **Edge case documentation** (5 files): Add failure scenario examples
|
||||
3. **Integration documentation** (4 files): List compatible agents/skills
|
||||
```
|
||||
|
||||
---
|
||||
| Category | Weight | Max Points | Key Criteria |
|
||||
|----------|--------|------------|--------------|
|
||||
| Structure | 3x | 12 | Valid frontmatter, argument hint, step-by-step |
|
||||
| Quality | 2x | 8 | Error handling, mentions failure modes |
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic (Full Audit)
|
||||
|
||||
```bash
|
||||
# In Claude Code
|
||||
# Full audit (default)
|
||||
Use skill: audit-agents-skills
|
||||
|
||||
# Specify path
|
||||
Use skill: audit-agents-skills for ~/projects/my-app
|
||||
```
|
||||
|
||||
### With Options
|
||||
|
||||
```bash
|
||||
# Quick audit (fast)
|
||||
# Quick audit
|
||||
Use skill: audit-agents-skills with mode=quick
|
||||
|
||||
# Comparative (benchmark analysis)
|
||||
# Comparative with benchmarks
|
||||
Use skill: audit-agents-skills with mode=comparative
|
||||
|
||||
# Generate fixes
|
||||
Use skill: audit-agents-skills with fixes=true
|
||||
|
||||
# Custom output path
|
||||
Use skill: audit-agents-skills with output=~/Desktop/audit.json
|
||||
```
|
||||
|
||||
### JSON Output Only
|
||||
|
||||
```bash
|
||||
# For programmatic integration
|
||||
# JSON output for CI/CD
|
||||
Use skill: audit-agents-skills with format=json output=audit.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with CI/CD
|
||||
|
||||
### Pre-commit Hook
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .git/hooks/pre-commit
|
||||
|
||||
# Run quick audit on changed agent/skill/command files
|
||||
changed_files=$(git diff --cached --name-only | grep -E "^\.claude/(agents|skills|commands)/")
|
||||
|
||||
if [ -n "$changed_files" ]; then
|
||||
echo "Running quick audit on changed files..."
|
||||
# Run audit (requires Claude Code CLI wrapper)
|
||||
# Exit with 1 if any file scores <80%
|
||||
fi
|
||||
```
|
||||
|
|
@ -468,80 +158,10 @@ jobs:
|
|||
- uses: actions/checkout@v3
|
||||
- name: Run quality audit
|
||||
run: |
|
||||
# Run audit skill
|
||||
# Parse JSON output
|
||||
# Fail if overall_score < 80
|
||||
# Run audit skill, parse JSON, fail if overall_score < 80
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comparison: Command vs Skill
|
||||
|
||||
| Aspect | Command (`/audit-agents-skills`) | Skill (this file) |
|
||||
|--------|----------------------------------|-------------------|
|
||||
| **Scope** | Current project only | Multi-project, comparative |
|
||||
| **Output** | Markdown report | Markdown + JSON |
|
||||
| **Speed** | Fast (5-10 min) | Slower (10-20 min with comparative) |
|
||||
| **Depth** | Standard 16 criteria | Same + benchmark analysis |
|
||||
| **Fix suggestions** | Via `--fix` flag | Built-in with recommendations |
|
||||
| **Programmatic** | Terminal output | JSON for CI/CD integration |
|
||||
| **Best for** | Quick checks, dev workflow | Deep audits, quality tracking |
|
||||
|
||||
**Recommendation**: Use command for daily checks, skill for release gates and quality tracking.
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Updating Criteria
|
||||
|
||||
Edit `scoring/criteria.yaml`:
|
||||
```yaml
|
||||
agents:
|
||||
categories:
|
||||
identity:
|
||||
criteria:
|
||||
- id: A1.5 # New criterion
|
||||
name: "API versioning specified"
|
||||
points: 3
|
||||
detection: "mentions API version or compatibility"
|
||||
```
|
||||
|
||||
Version bump: Increment `version` in frontmatter when criteria change.
|
||||
|
||||
### Adding File Types
|
||||
|
||||
To support new file types (e.g., "workflows"):
|
||||
1. Add to `scoring/criteria.yaml`:
|
||||
```yaml
|
||||
workflows:
|
||||
max_points: 24
|
||||
categories: [...]
|
||||
```
|
||||
2. Update detection logic (file path patterns)
|
||||
3. Update report templates
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- **Command version**: `.claude/commands/audit-agents-skills.md`
|
||||
- **Agent Validation Checklist**: guide line 4921 (manual 16 criteria)
|
||||
- **Skill Validation**: guide line 5491 (spec documentation)
|
||||
- **Command version**: `.claude/commands/audit-agents-skills.md` (quick checks, dev workflow)
|
||||
- **Reference templates**: `examples/agents/`, `examples/skills/`, `examples/commands/`
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
**v1.0.0** (2026-02-07):
|
||||
- Initial release
|
||||
- 16-criteria framework (agents/skills/commands)
|
||||
- 3 audit modes (quick/full/comparative)
|
||||
- JSON + Markdown output
|
||||
- Fix suggestions
|
||||
- Industry context (LangChain 2026 report)
|
||||
|
||||
---
|
||||
|
||||
**Skill ready for use**: `audit-agents-skills`
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: ccboard
|
||||
description: Comprehensive TUI/Web dashboard for Claude Code monitoring
|
||||
description: "Launch and navigate the ccboard TUI/Web dashboard for Claude Code. Use when monitoring token usage, tracking costs, browsing sessions, or checking MCP server status across projects."
|
||||
version: 0.1.0
|
||||
category: monitoring
|
||||
keywords: [dashboard, tui, mcp, sessions, costs, analytics]
|
||||
|
|
@ -9,38 +9,20 @@ tags: [dashboard, tui, monitoring, claude-code, costs]
|
|||
|
||||
# ccboard - Claude Code Dashboard
|
||||
|
||||
Comprehensive TUI/Web dashboard for monitoring and managing your Claude Code usage.
|
||||
TUI/Web dashboard for monitoring Claude Code usage: sessions, costs, tokens, MCP servers, and configuration.
|
||||
|
||||
## Overview
|
||||
|
||||
ccboard provides a unified interface to visualize and explore all your Claude Code data:
|
||||
|
||||
- **Sessions**: Browse all conversations across your projects
|
||||
- **Statistics**: Real-time token usage, cache hit rates, activity trends
|
||||
- **MCP Servers**: Monitor and manage Model Context Protocol servers
|
||||
- **Costs**: Track spending with detailed token breakdown and pricing
|
||||
- **Configuration**: View cascading settings (Global > Project > Local)
|
||||
- **Hooks**: Explore pre/post execution hooks and automation
|
||||
- **Agents**: Manage custom agents, commands, and skills
|
||||
- **History**: Search across all messages with full-text search
|
||||
|
||||
## Installation
|
||||
|
||||
### Via Cargo (Recommended)
|
||||
|
||||
```bash
|
||||
# Using Claude Code command
|
||||
/ccboard-install
|
||||
|
||||
# Or manually
|
||||
cargo install ccboard
|
||||
```
|
||||
|
||||
### Requirements
|
||||
## Prerequisites
|
||||
|
||||
- Rust 1.70+ and Cargo
|
||||
- Claude Code installed (reads from `~/.claude/`)
|
||||
|
||||
```bash
|
||||
# Install
|
||||
cargo install ccboard
|
||||
# Or via Claude Code command
|
||||
/ccboard-install
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description | Shortcut |
|
||||
|
|
@ -52,347 +34,78 @@ cargo install ccboard
|
|||
| `/ccboard-web` | Launch web UI | `ccboard web` |
|
||||
| `/ccboard-install` | Install/update ccboard | - |
|
||||
|
||||
## Features
|
||||
## Tabs Overview
|
||||
|
||||
### 8 Interactive Tabs
|
||||
| Tab | Key | What It Shows |
|
||||
|-----|-----|---------------|
|
||||
| Dashboard | `1` | Token stats, cache ratio, 7-day sparkline, model gauges |
|
||||
| Sessions | `2` | Project tree + session list, search with `/`, edit with `e` |
|
||||
| Config | `3` | Cascading settings: Global / Project / Local / Merged |
|
||||
| Hooks | `4` | Event-based hooks, script preview, match patterns |
|
||||
| Agents | `5` | Agents, commands, skills with frontmatter extraction |
|
||||
| Costs | `6` | Overview, by-model breakdown, daily trend |
|
||||
| History | `7` | Full-text search across all sessions |
|
||||
| MCP | `8` | Server status (Running/Stopped), details, quick actions |
|
||||
|
||||
#### 1. Dashboard (Press `1`)
|
||||
- Token usage statistics
|
||||
- Session count
|
||||
- Messages sent
|
||||
- Cache hit ratio
|
||||
- MCP server count
|
||||
- 7-day activity sparkline
|
||||
- Top 5 models usage gauges
|
||||
## Navigation
|
||||
|
||||
#### 2. Sessions (Press `2`)
|
||||
- Dual-pane: Project tree + Session list
|
||||
- Metadata: timestamps, duration, tokens, models
|
||||
- Search: Filter by project, message, or model (press `/`)
|
||||
- File operations: `e` to edit JSONL, `o` to reveal in finder
|
||||
|
||||
#### 3. Config (Press `3`)
|
||||
- 4-column cascading view: Global | Project | Local | Merged
|
||||
- Settings inheritance visualization
|
||||
- MCP servers configuration
|
||||
- Rules (CLAUDE.md) preview
|
||||
- Permissions, hooks, environment variables
|
||||
- Edit config with `e` key
|
||||
|
||||
#### 4. Hooks (Press `4`)
|
||||
- Event-based hook browsing (PreToolUse, UserPromptSubmit)
|
||||
- Hook bash script preview
|
||||
- Match patterns and conditions
|
||||
- File path tracking for easy editing
|
||||
|
||||
#### 5. Agents (Press `5`)
|
||||
- 3 sub-tabs: Agents (12) | / Commands (5) | ★ Skills (0)
|
||||
- Frontmatter metadata extraction
|
||||
- File preview and editing
|
||||
- Recursive directory scanning
|
||||
|
||||
#### 6. Costs (Press `6`)
|
||||
- 3 views: Overview | By Model | Daily Trend
|
||||
- Token breakdown: input, output, cache read/write
|
||||
- Pricing: total estimated costs
|
||||
- Model distribution breakdown
|
||||
|
||||
#### 7. History (Press `7`)
|
||||
- Full-text search across all sessions
|
||||
- Activity by hour histogram (24h)
|
||||
- 7-day sparkline
|
||||
- All messages searchable
|
||||
|
||||
#### 8. MCP (Press `8`) **NEW**
|
||||
- Dual-pane: Server list (35%) | Details (65%)
|
||||
- Live status detection: ● Running, ○ Stopped, ? Unknown
|
||||
- Full server details: command, args, environment vars
|
||||
- Quick actions: `e` edit config, `o` reveal file, `r` refresh status
|
||||
|
||||
### Navigation
|
||||
|
||||
**Global Keys**:
|
||||
- `1-8` : Jump to tab
|
||||
- `Tab` / `Shift+Tab` : Navigate tabs
|
||||
- `q` : Quit
|
||||
- `F5` : Refresh data
|
||||
|
||||
**Vim-style**:
|
||||
- `h/j/k/l` : Navigate (left/down/up/right)
|
||||
- `←/→/↑/↓` : Arrow alternatives
|
||||
|
||||
**Common Actions**:
|
||||
- `Enter` : View details / Focus pane
|
||||
- `e` : Edit file in $EDITOR
|
||||
- `o` : Reveal file in finder
|
||||
- `/` : Search (in Sessions/History tabs)
|
||||
- `Esc` : Close popup / Cancel
|
||||
|
||||
### Real-time Monitoring
|
||||
|
||||
ccboard includes a file watcher that monitors `~/.claude/` for changes:
|
||||
|
||||
- **Stats updates**: Live refresh when `stats-cache.json` changes
|
||||
- **Session updates**: New sessions appear automatically
|
||||
- **Config updates**: Settings changes reflected in UI
|
||||
- **500ms debounce**: Prevents excessive updates
|
||||
|
||||
### File Editing
|
||||
|
||||
Press `e` on any item to open in your preferred editor:
|
||||
|
||||
- Uses `$VISUAL` > `$EDITOR` > platform default (nano/notepad)
|
||||
- Supports: Sessions (JSONL), Config (JSON), Hooks (Shell), Agents (Markdown)
|
||||
- Terminal state preserved (alternate screen mode)
|
||||
- Cross-platform (macOS, Linux, Windows)
|
||||
|
||||
### MCP Server Management
|
||||
|
||||
The MCP tab provides comprehensive server monitoring:
|
||||
|
||||
**Status Detection** (Unix):
|
||||
- Checks running processes via `ps aux`
|
||||
- Extracts package name from command
|
||||
- Displays PID when running
|
||||
- Windows shows "Unknown" status
|
||||
|
||||
**Server Details**:
|
||||
- Full command and arguments
|
||||
- Environment variables with values
|
||||
- Config file path (`~/.claude/claude_desktop_config.json`)
|
||||
- Quick edit/reveal actions
|
||||
|
||||
**Navigation**:
|
||||
- `h/l` or `←/→` : Switch between list and details
|
||||
- `j/k` or `↑/↓` : Select server
|
||||
- `Enter` : Focus detail pane
|
||||
- `e` : Edit MCP config
|
||||
- `o` : Reveal config in finder
|
||||
- `r` : Refresh server status
|
||||
| Keys | Action |
|
||||
|------|--------|
|
||||
| `1-8` | Jump to tab |
|
||||
| `Tab` / `Shift+Tab` | Navigate tabs |
|
||||
| `h/j/k/l` or arrows | Navigate within tab |
|
||||
| `Enter` | View details / Focus pane |
|
||||
| `e` | Edit file in `$EDITOR` |
|
||||
| `o` | Reveal file in finder |
|
||||
| `/` | Search (Sessions/History) |
|
||||
| `F5` | Refresh data |
|
||||
| `q` | Quit |
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Daily Monitoring
|
||||
|
||||
```bash
|
||||
# Launch dashboard
|
||||
/dashboard
|
||||
|
||||
# Check activity and costs
|
||||
# Press '1' for overview
|
||||
# Press '6' for costs breakdown
|
||||
# Press '7' for recent history
|
||||
# Press '1' for overview, '6' for costs, '7' for history
|
||||
```
|
||||
|
||||
### MCP Troubleshooting
|
||||
|
||||
```bash
|
||||
# Open MCP tab
|
||||
/mcp-status
|
||||
|
||||
# Or: ccboard then press '8'
|
||||
|
||||
# Check server status (● green = running)
|
||||
# Press 'e' to edit config if needed
|
||||
# Press 'r' to refresh status after changes
|
||||
# Check server status (green = running)
|
||||
# Press 'e' to edit config, 'r' to refresh status
|
||||
```
|
||||
|
||||
### Session Analysis
|
||||
|
||||
```bash
|
||||
# Browse sessions
|
||||
/sessions
|
||||
|
||||
# Press '/' to search
|
||||
# Filter by project: /my-project
|
||||
# Filter by model: /opus
|
||||
# Press 'e' on session to view full JSONL
|
||||
```
|
||||
|
||||
### Cost Tracking
|
||||
|
||||
```bash
|
||||
# View costs
|
||||
/costs
|
||||
|
||||
# Press '1' for overview
|
||||
# Press '2' for breakdown by model
|
||||
# Press '3' for daily trend
|
||||
|
||||
# Identify expensive sessions
|
||||
# Track cache efficiency (99.9% hit rate)
|
||||
# Press '/' to search by project, model, or message content
|
||||
# Press 'e' on a session to view full JSONL
|
||||
```
|
||||
|
||||
## Web Interface
|
||||
|
||||
Launch browser-based interface for remote monitoring:
|
||||
|
||||
```bash
|
||||
# Launch web UI
|
||||
/ccboard-web
|
||||
|
||||
# Or with custom port
|
||||
ccboard web --port 8080
|
||||
|
||||
# Access at http://localhost:3333
|
||||
/ccboard-web # Launch at http://localhost:3333
|
||||
ccboard web --port 8080 # Custom port
|
||||
ccboard both --port 3333 # TUI + Web simultaneously
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Same data as TUI (shared backend)
|
||||
- Server-Sent Events (SSE) for live updates
|
||||
- Responsive design (desktop/tablet/mobile)
|
||||
- Concurrent multi-user access
|
||||
## Validation
|
||||
|
||||
**Run both simultaneously**:
|
||||
```bash
|
||||
ccboard both --port 3333
|
||||
```
|
||||
After launching, verify ccboard is working:
|
||||
|
||||
## Architecture
|
||||
|
||||
ccboard is a single Rust binary with dual frontends:
|
||||
|
||||
```
|
||||
ccboard/
|
||||
├── ccboard-core/ # Parsers, models, data store, watcher
|
||||
├── ccboard-tui/ # Ratatui frontend (8 tabs)
|
||||
└── ccboard-web/ # Axum + Leptos frontend
|
||||
```
|
||||
|
||||
**Data Sources**:
|
||||
- `~/.claude/stats-cache.json` - Statistics
|
||||
- `~/.claude/claude_desktop_config.json` - MCP config
|
||||
- `~/.claude/projects/*/` - Session JSONL files
|
||||
- `~/.claude/settings.json` - Global settings
|
||||
- `.claude/settings.json` - Project settings
|
||||
- `.claude/settings.local.json` - Local overrides
|
||||
- `.claude/CLAUDE.md` - Rules and behavior
|
||||
1. Run `/dashboard` and confirm token stats load on tab `1`
|
||||
2. Press `2` and verify sessions are listed
|
||||
3. Press `6` and confirm cost data appears
|
||||
4. If no data: check `ls ~/.claude/` and `cat ~/.claude/stats-cache.json`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### ccboard not found
|
||||
|
||||
```bash
|
||||
# Check installation
|
||||
which ccboard
|
||||
|
||||
# Install if needed
|
||||
/ccboard-install
|
||||
```
|
||||
|
||||
### No data visible
|
||||
|
||||
```bash
|
||||
# Verify Claude Code is installed
|
||||
ls ~/.claude/
|
||||
|
||||
# Check stats file exists
|
||||
cat ~/.claude/stats-cache.json
|
||||
|
||||
# Run with specific project
|
||||
ccboard --project ~/path/to/project
|
||||
```
|
||||
|
||||
### MCP status shows "Unknown"
|
||||
|
||||
- Status detection requires Unix (macOS/Linux)
|
||||
- Windows shows "Unknown" by default
|
||||
- Check if server process is actually running: `ps aux | grep <server-name>`
|
||||
|
||||
### File watcher not working
|
||||
|
||||
- Ensure `notify` crate supports your platform
|
||||
- Check file permissions on `~/.claude/`
|
||||
- Restart ccboard if file system events missed
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Command-line Options
|
||||
|
||||
```bash
|
||||
ccboard --help # Show all options
|
||||
ccboard --claude-home PATH # Custom Claude directory
|
||||
ccboard --project PATH # Specific project
|
||||
ccboard stats # Print stats and exit
|
||||
ccboard web --port 8080 # Web UI on port 8080
|
||||
ccboard both # TUI + Web simultaneously
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Editor preference
|
||||
export EDITOR=vim
|
||||
export VISUAL=code
|
||||
|
||||
# Custom Claude home
|
||||
export CLAUDE_HOME=~/custom/.claude
|
||||
```
|
||||
|
||||
### Integration with Claude Code
|
||||
|
||||
ccboard reads **read-only** from Claude Code directories:
|
||||
|
||||
- Non-invasive monitoring
|
||||
- No modifications to Claude data
|
||||
- Safe to run concurrently with Claude Code
|
||||
- File watcher detects changes in real-time
|
||||
|
||||
## Performance
|
||||
|
||||
- **Binary size**: 2.4MB (release build)
|
||||
- **Initial load**: <2s for 1,000+ sessions
|
||||
- **Memory**: ~50MB typical usage
|
||||
- **CPU**: <5% during monitoring
|
||||
- **Lazy loading**: Session content loaded on-demand
|
||||
|
||||
## Limitations
|
||||
|
||||
Current version (0.1.0):
|
||||
|
||||
- **Read-only**: No write operations to Claude data
|
||||
- **MCP status**: Unix only (Windows shows "Unknown")
|
||||
- **Web UI**: In development (TUI is primary interface)
|
||||
- **Search**: Basic substring matching (no fuzzy search yet)
|
||||
|
||||
Future roadmap:
|
||||
|
||||
- Enhanced MCP server management (start/stop)
|
||||
- MCP protocol health checks
|
||||
- Export reports (PDF, JSON, CSV)
|
||||
- Config editing (write settings.json)
|
||||
- Session resume integration
|
||||
- Enhanced search with fuzzy matching
|
||||
|
||||
## Contributing
|
||||
|
||||
ccboard is open source (MIT OR Apache-2.0).
|
||||
|
||||
Repository: https://github.com/{OWNER}/ccboard
|
||||
|
||||
Contributions welcome:
|
||||
- Bug reports and feature requests
|
||||
- Pull requests for new features
|
||||
- Documentation improvements
|
||||
- Platform-specific testing (Windows, Linux)
|
||||
|
||||
## Credits
|
||||
|
||||
Built with:
|
||||
- [Ratatui](https://ratatui.rs/) - Terminal UI framework
|
||||
- [Axum](https://github.com/tokio-rs/axum) - Web framework
|
||||
- [Leptos](https://leptos.dev/) - Reactive frontend
|
||||
- [Notify](https://github.com/notify-rs/notify) - File watcher
|
||||
- [Serde](https://serde.rs/) - Serialization
|
||||
|
||||
## License
|
||||
|
||||
MIT OR Apache-2.0
|
||||
|
||||
---
|
||||
|
||||
**Questions?**
|
||||
|
||||
- GitHub Issues: https://github.com/{OWNER}/ccboard/issues
|
||||
- Documentation: https://github.com/{OWNER}/ccboard
|
||||
- Claude Code: https://claude.ai/code
|
||||
- **ccboard not found**: Run `/ccboard-install` or `cargo install ccboard`
|
||||
- **No data visible**: Verify `~/.claude/` exists and contains `stats-cache.json`
|
||||
- **MCP shows "Unknown"**: Status detection requires Unix; Windows shows "Unknown" by default
|
||||
- **File watcher issues**: Check file permissions on `~/.claude/`, restart ccboard
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: cyber-defense-team
|
||||
description: Orchestrate a 4-agent cyber defense pipeline to analyze log files for threats. Spawns log-ingestor → anomaly-detector → risk-classifier → threat-reporter as parallel-then-sequential agents. Produces a Markdown incident report.
|
||||
description: "Orchestrate a 4-agent cyber defense pipeline to analyze log files for threats. Use when investigating security logs, detecting anomalies in access patterns, classifying breach severity, or generating incident reports from nginx/auth/syslog files."
|
||||
version: 1.0.0
|
||||
usage: /cyber-defense-team [log-file-path]
|
||||
args:
|
||||
|
|
@ -38,39 +38,30 @@ Check that the log file exists (or that log content was provided inline). If the
|
|||
|
||||
### Step 2 — Spawn Log Ingestor
|
||||
|
||||
Use the Agent tool to spawn the `log-ingestor` agent:
|
||||
|
||||
```
|
||||
Task: Parse the log file at [log_path] and write structured events to cyber-defense-events.json.
|
||||
Log path: [log_path]
|
||||
Agent(tool="Task", prompt="Parse the log file at [log_path] and write structured events to cyber-defense-events.json.", agent="log-ingestor", model="haiku")
|
||||
```
|
||||
|
||||
Wait for completion. Confirm `cyber-defense-events.json` was created.
|
||||
|
||||
### Step 3 — Spawn Anomaly Detector
|
||||
|
||||
Use the Agent tool to spawn the `anomaly-detector` agent:
|
||||
|
||||
```
|
||||
Task: Read cyber-defense-events.json and detect anomalies. Write results to cyber-defense-anomalies.json.
|
||||
Agent(tool="Task", prompt="Read cyber-defense-events.json and detect anomalies. Write results to cyber-defense-anomalies.json.", agent="anomaly-detector", model="sonnet")
|
||||
```
|
||||
|
||||
Wait for completion. If `anomalies_found: 0`, skip to Step 5 (reporter still runs).
|
||||
|
||||
### Step 4 — Spawn Risk Classifier
|
||||
|
||||
Use the Agent tool to spawn the `risk-classifier` agent:
|
||||
|
||||
```
|
||||
Task: Read cyber-defense-anomalies.json and classify overall risk. Write result to cyber-defense-risk.json.
|
||||
Agent(tool="Task", prompt="Read cyber-defense-anomalies.json and classify overall risk. Write result to cyber-defense-risk.json.", agent="risk-classifier", model="sonnet")
|
||||
```
|
||||
|
||||
### Step 5 — Spawn Threat Reporter
|
||||
|
||||
Use the Agent tool to spawn the `threat-reporter` agent:
|
||||
|
||||
```
|
||||
Task: Read cyber-defense-events.json, cyber-defense-anomalies.json, and cyber-defense-risk.json. Generate a complete incident report and save it to cyber-defense-report.md.
|
||||
Agent(tool="Task", prompt="Read all 3 JSON files (events, anomalies, risk). Generate a complete incident report and save to cyber-defense-report.md.", agent="threat-reporter", model="sonnet")
|
||||
```
|
||||
|
||||
### Step 6 — Summarize for User
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: design-patterns
|
||||
description: Analyze codebase for GoF design patterns - detection, suggestions, evaluation with stack-aware adaptations
|
||||
description: "Detect, suggest, and evaluate GoF design patterns in TypeScript/JavaScript codebases. Use when refactoring code, applying singleton/factory/observer/strategy patterns, reviewing pattern quality, or finding stack-native alternatives for React, Angular, NestJS, and Vue."
|
||||
allowed-tools: Read, Grep, Glob, mcp__grepai__grepai_search
|
||||
context: fork
|
||||
agent: specialist
|
||||
|
|
@ -33,11 +33,7 @@ agent: specialist
|
|||
5. JSON Report Generation
|
||||
```
|
||||
|
||||
**Example invocation**:
|
||||
```
|
||||
/design-patterns detect src/
|
||||
/design-patterns analyze --format=json
|
||||
```
|
||||
**Example**: `/design-patterns detect src/`
|
||||
|
||||
### Mode 2: Suggestion
|
||||
|
||||
|
|
@ -53,11 +49,7 @@ agent: specialist
|
|||
5. Markdown Report with Code Examples
|
||||
```
|
||||
|
||||
**Example invocation**:
|
||||
```
|
||||
/design-patterns suggest src/payment/
|
||||
/design-patterns refactor --focus=creational
|
||||
```
|
||||
**Example**: `/design-patterns suggest src/payment/`
|
||||
|
||||
### Mode 3: Evaluation
|
||||
|
||||
|
|
@ -73,11 +65,7 @@ agent: specialist
|
|||
5. JSON Report with Recommendations
|
||||
```
|
||||
|
||||
**Example invocation**:
|
||||
```
|
||||
/design-patterns evaluate src/services/singleton.ts
|
||||
/design-patterns quality --pattern=observer
|
||||
```
|
||||
**Example**: `/design-patterns evaluate src/services/singleton.ts`
|
||||
|
||||
## Methodology
|
||||
|
||||
|
|
@ -286,134 +274,6 @@ ELSE IF pattern_implemented_incorrectly:
|
|||
}
|
||||
```
|
||||
|
||||
### Suggestion Mode (Markdown)
|
||||
|
||||
```markdown
|
||||
# Design Pattern Suggestions
|
||||
|
||||
**Scope**: `src/payment/`
|
||||
**Stack**: React 18 + TypeScript + Stripe
|
||||
**Date**: 2026-01-21
|
||||
|
||||
---
|
||||
|
||||
## High Priority
|
||||
|
||||
### 1. Strategy Pattern → `src/payment/processor.ts:45-89`
|
||||
|
||||
**Code Smell**: Switch statement on payment type (4 cases, 78 lines)
|
||||
|
||||
**Current Implementation** (lines 52-87):
|
||||
```typescript
|
||||
switch (paymentType) {
|
||||
case 'credit':
|
||||
// 20 lines of credit card logic
|
||||
break;
|
||||
case 'paypal':
|
||||
// 15 lines of PayPal logic
|
||||
break;
|
||||
case 'crypto':
|
||||
// 18 lines of crypto logic
|
||||
break;
|
||||
case 'bank':
|
||||
// 12 lines of bank transfer logic
|
||||
break;
|
||||
}
|
||||
```
|
||||
|
||||
**Recommended (React-adapted Strategy)**:
|
||||
```typescript
|
||||
// Define strategy interface
|
||||
interface PaymentStrategy {
|
||||
process: (amount: number) => Promise<PaymentResult>;
|
||||
}
|
||||
|
||||
// Custom hooks as strategies
|
||||
const useCreditPayment = (): PaymentStrategy => ({
|
||||
process: async (amount) => { /* credit logic */ }
|
||||
});
|
||||
|
||||
const usePaypalPayment = (): PaymentStrategy => ({
|
||||
process: async (amount) => { /* PayPal logic */ }
|
||||
});
|
||||
|
||||
// Strategy selection hook
|
||||
const usePaymentStrategy = (type: PaymentType): PaymentStrategy => {
|
||||
const strategies = {
|
||||
credit: useCreditPayment(),
|
||||
paypal: usePaypalPayment(),
|
||||
crypto: useCryptoPayment(),
|
||||
bank: useBankPayment(),
|
||||
};
|
||||
return strategies[type];
|
||||
};
|
||||
|
||||
// Usage in component
|
||||
const PaymentForm = ({ type }: Props) => {
|
||||
const strategy = usePaymentStrategy(type);
|
||||
const handlePay = () => strategy.process(amount);
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
**Impact**:
|
||||
- **Complexity**: Reduces cyclomatic complexity from 12 to 2
|
||||
- **Extensibility**: New payment methods = new hook, no modification to existing code
|
||||
- **Testability**: Each strategy hook can be tested in isolation
|
||||
- **Effort**: ~2 hours (extract logic into hooks, add tests)
|
||||
|
||||
---
|
||||
|
||||
## Medium Priority
|
||||
|
||||
### 2. Observer Pattern → `src/cart/CartManager.ts:23-156`
|
||||
|
||||
**Code Smell**: Manual notification logic scattered across 8 methods
|
||||
|
||||
**Current**: Manual loops calling update functions
|
||||
**Recommended**: Use Zustand store (already in dependencies)
|
||||
|
||||
```typescript
|
||||
// Instead of custom observer:
|
||||
import create from 'zustand';
|
||||
|
||||
interface CartStore {
|
||||
items: CartItem[];
|
||||
addItem: (item: CartItem) => void;
|
||||
removeItem: (id: string) => void;
|
||||
// Zustand automatically notifies subscribers
|
||||
}
|
||||
|
||||
export const useCartStore = create<CartStore>((set) => ({
|
||||
items: [],
|
||||
addItem: (item) => set((state) => ({ items: [...state.items, item] })),
|
||||
removeItem: (id) => set((state) => ({ items: state.items.filter(i => i.id !== id) })),
|
||||
}));
|
||||
|
||||
// Components auto-subscribe:
|
||||
const CartDisplay = () => {
|
||||
const items = useCartStore((state) => state.items);
|
||||
// Re-renders automatically on cart changes
|
||||
};
|
||||
```
|
||||
|
||||
**Impact**:
|
||||
- **LOC**: Reduces from 156 to ~25 lines
|
||||
- **Stack-native**: Uses existing Zustand dependency
|
||||
- **Testability**: Zustand stores are easily tested
|
||||
- **Effort**: ~1.5 hours
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
- **Total suggestions**: 4
|
||||
- **High priority**: 2 (Strategy, Observer)
|
||||
- **Medium priority**: 2 (Builder, Facade)
|
||||
- **Estimated total effort**: ~6 hours
|
||||
- **Primary benefits**: Reduced complexity, improved testability, stack-native idioms
|
||||
```
|
||||
|
||||
### Evaluation Mode (JSON)
|
||||
|
||||
```json
|
||||
|
|
@ -503,40 +363,11 @@ const CartDisplay = () => {
|
|||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Detection
|
||||
```bash
|
||||
# Detect all patterns in src/
|
||||
/design-patterns detect src/
|
||||
|
||||
# Detect only creational patterns
|
||||
/design-patterns detect src/ --category=creational
|
||||
|
||||
# Focus on specific pattern
|
||||
/design-patterns detect src/ --pattern=singleton
|
||||
```
|
||||
|
||||
### Targeted Suggestions
|
||||
```bash
|
||||
# Get suggestions for payment module
|
||||
/design-patterns suggest src/payment/
|
||||
|
||||
# Focus on specific smell
|
||||
/design-patterns suggest src/ --smell=switch-on-type
|
||||
|
||||
# High priority only
|
||||
/design-patterns suggest src/ --priority=high
|
||||
```
|
||||
|
||||
### Quality Evaluation
|
||||
```bash
|
||||
# Evaluate specific file
|
||||
/design-patterns evaluate src/services/api-client.ts
|
||||
|
||||
# Evaluate all singletons
|
||||
/design-patterns evaluate src/ --pattern=singleton
|
||||
|
||||
# Full quality report
|
||||
/design-patterns evaluate src/ --detailed
|
||||
/design-patterns detect src/ # Detect all patterns
|
||||
/design-patterns detect src/ --category=creational # Creational only
|
||||
/design-patterns suggest src/payment/ # Suggestions for module
|
||||
/design-patterns evaluate src/services/api-client.ts # Evaluate specific file
|
||||
```
|
||||
|
||||
## Integration with Other Skills
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: guide-recap
|
||||
description: Transform CHANGELOG entries into social content (LinkedIn, Twitter/X, Newsletter, Slack) in FR + EN. Use after releases or weekly to generate ready-to-post content from guide updates.
|
||||
description: "Transform CHANGELOG entries into social content (LinkedIn, Twitter/X, Newsletter, Slack) in FR + EN. Use after releases or weekly to generate release notes, announcements, social media posts, or recap summaries from guide updates."
|
||||
argument-hint: "<latest|vX.Y.Z|week [YYYY-MM-DD]> [--interactive] [--format=linkedin|twitter|newsletter|slack] [--lang=fr|en] [--save]"
|
||||
tags: [changelog, social-media, content, linkedin, twitter]
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,9 +1,6 @@
|
|||
---
|
||||
name: issue-triage
|
||||
description: >
|
||||
3-phase issue backlog management: audit open issues, deep analyze selected ones, draft and execute
|
||||
triage actions with mandatory validation. Args: "all" to analyze all, issue numbers to focus
|
||||
(e.g. "42 57"), "en"/"fr" for language, no arg = audit only in French.
|
||||
description: "3-phase issue backlog management with audit, deep analysis, and validated triage actions. Use when triaging GitHub issues, sorting bug reports, cleaning up stale tickets, or detecting duplicate issues. Args: 'all' to analyze all, issue numbers to focus (e.g. '42 57'), 'en'/'fr' for language, no arg = audit only."
|
||||
tags: [github, issue, triage, maintainer, multi-agent]
|
||||
---
|
||||
|
||||
|
|
@ -118,33 +115,11 @@ Scan each open PR body for references to the issue number:
|
|||
|
||||
#### 3. Duplicate Detection via Jaccard Similarity
|
||||
|
||||
**Algorithm (self-contained — no external library)**:
|
||||
Compare each open issue against all other open issues AND the 20 most recent closed issues using Jaccard similarity (self-contained, no external library).
|
||||
|
||||
For each open issue, compute Jaccard similarity against all other open issues AND the 20 most recent closed issues.
|
||||
**Steps**: Normalize text (lowercase, strip prefixes like "feat:"/"fix:", remove punctuation) → Tokenize (split on whitespace, remove stop words and tokens <3 chars) → Compute `|A ∩ B| / |A ∪ B|` on token sets from title + first 300 chars of body.
|
||||
|
||||
```
|
||||
Step 1 — Normalize title + first 300 chars of body:
|
||||
- Lowercase the full text
|
||||
- Strip category prefixes: "feat:", "fix:", "bug:", "chore:", "docs:", "test:", "refactor:"
|
||||
- Remove punctuation: .,!?;:'"()[]{}-_/\@#
|
||||
|
||||
Step 2 — Tokenize:
|
||||
- Split on whitespace
|
||||
- Remove stop words: the a an is in on to for of and or with this that it can not no be
|
||||
- Remove tokens shorter than 3 characters
|
||||
|
||||
Step 3 — Compute Jaccard:
|
||||
tokens_A = set of tokens from issue A
|
||||
tokens_B = set of tokens from issue B
|
||||
jaccard = |tokens_A ∩ tokens_B| / |tokens_A ∪ tokens_B|
|
||||
|
||||
Step 4 — Flag:
|
||||
- If jaccard >= 0.60: mark as potential duplicate
|
||||
- Report: "Similar to #N (Jaccard: 0.72)"
|
||||
- Keep the OLDER issue as canonical; newer = duplicate candidate
|
||||
```
|
||||
|
||||
Jaccard is computed at runtime using the fetched data — no API calls beyond Phase 1 gather.
|
||||
**Threshold**: Jaccard >= 0.60 → flag as potential duplicate. Keep the older issue as canonical. Report: "Similar to #N (Jaccard: 0.72)". Computed at runtime on fetched data — no additional API calls.
|
||||
|
||||
#### 4. Risk Classification
|
||||
|
||||
|
|
@ -408,18 +383,14 @@ If "None" → `No actions executed. Workflow complete.`
|
|||
|
||||
## Edge Cases
|
||||
|
||||
| Situation | Behavior |
|
||||
|-----------|----------|
|
||||
| 0 open issues | Display `No open issues.` + stop |
|
||||
| Body empty | Category = Unclear, action = request details, never assume |
|
||||
| Collaborator as reporter | Protect from auto-close, flag explicitly in table |
|
||||
| Jaccard inconclusive (0.55–0.65) | Flag as "possible duplicate — verify manually" |
|
||||
| Label not in repo | Skip label action, notify user to create the label first |
|
||||
| Issue already closed during workflow | Skip silently, note in summary |
|
||||
| `gh api .../collaborators` 403/404 | Fallback to last 10 merged PR authors |
|
||||
| Parallel agents unavailable | Run sequential analysis, notify user |
|
||||
| Very large body (>5000 chars) | Truncate to 5000 chars with `[truncated]` note |
|
||||
| Milestone assigned | Include in table, never close milestoned issues without confirmation |
|
||||
- **0 open issues**: Display `No open issues.` and stop
|
||||
- **Empty body**: Category = Unclear, always request details first
|
||||
- **Collaborator reporter**: Protect from auto-close, flag in table
|
||||
- **Jaccard 0.55–0.65**: Flag as "possible duplicate — verify manually"
|
||||
- **Label not in repo**: Skip label action, notify user to create it
|
||||
- **Collaborators API 403/404**: Fallback to last 10 merged PR authors
|
||||
- **Large body (>5000 chars)**: Truncate with `[truncated]` note
|
||||
- **Milestoned issues**: Never close without explicit confirmation
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: landing-page-generator
|
||||
description: Generate complete landing pages from repositories. Analyzes README, features, and structure to create static sites following established patterns. Use for new project landings, open-source showcases, documentation portals.
|
||||
description: "Generate complete, deploy-ready landing pages from any repository. Use when creating a homepage for an open-source project, building a project website, converting a README into a marketing page, or standardizing landing pages across multiple repos."
|
||||
tags: [landing-page, static-site, github-pages, marketing]
|
||||
---
|
||||
|
||||
|
|
@ -155,6 +155,14 @@ Generate these sections in order:
|
|||
└── static.yml # GitHub Pages deployment
|
||||
```
|
||||
|
||||
### Step 5: Validation Checkpoint
|
||||
|
||||
Before finalizing, verify:
|
||||
- All sections render correctly in a browser
|
||||
- Links point to valid targets (GitHub repo, docs, install commands)
|
||||
- Responsive layout works at mobile (375px), tablet (768px), and desktop (1280px) widths
|
||||
- Accessibility: skip links present, ARIA labels on interactive elements, color contrast passes WCAG AA
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **No build step**: Pure HTML + CSS + JS
|
||||
|
|
@ -225,13 +233,6 @@ Creates `~/projects/my-project-landing/` with:
|
|||
- Review generated FAQ - may need customization
|
||||
- Test responsive design after generation
|
||||
|
||||
## Related Use Cases
|
||||
|
||||
- Open-source project showcases
|
||||
- Documentation portals
|
||||
- Product landing pages
|
||||
- Tool/utility marketing sites
|
||||
|
||||
## References
|
||||
|
||||
See `references/landing-pattern.md` for detailed pattern documentation.
|
||||
|
|
|
|||
|
|
@ -1,9 +1,6 @@
|
|||
---
|
||||
name: pr-triage
|
||||
description: >
|
||||
4-phase PR backlog management: audit open PRs, deep review selected ones, post validated
|
||||
review comments, and optionally create local worktrees for hands-on review. Args: "all"
|
||||
to review all, PR numbers to focus (e.g. "42 57"), "en"/"fr" for language, no arg = audit only.
|
||||
description: "4-phase PR backlog management with audit, deep code review, validated comments, and optional worktree setup. Use when triaging pull requests, catching up on pending code reviews, or managing a backlog of open PRs. Args: 'all' to review all, PR numbers to focus (e.g. '42 57'), 'en'/'fr' for language, no arg = audit only."
|
||||
tags: [github, pr, triage, review, maintainer, multi-agent, worktree]
|
||||
---
|
||||
|
||||
|
|
@ -63,37 +60,27 @@ If either fails, stop and explain what is missing.
|
|||
### Data Gathering (parallel commands)
|
||||
|
||||
```bash
|
||||
# Repo identity
|
||||
gh repo view --json nameWithOwner -q .nameWithOwner
|
||||
|
||||
# Open PRs with full metadata (body for cross-reference issues)
|
||||
gh pr list --state open --limit 50 \
|
||||
--json number,title,author,createdAt,updatedAt,additions,deletions,changedFiles,isDraft,mergeable,reviewDecision,statusCheckRollup,body
|
||||
|
||||
# Collaborators (to distinguish internal from external PRs)
|
||||
gh api "repos/{owner}/{repo}/collaborators" --jq '.[].login'
|
||||
```
|
||||
|
||||
**Collaborators fallback**: if `gh api .../collaborators` returns 403/404:
|
||||
```bash
|
||||
# Extract authors from last 10 merged PRs
|
||||
gh pr list --state merged --limit 10 --json author --jq '.[].author.login' | sort -u
|
||||
```
|
||||
If still ambiguous, ask via `AskUserQuestion`.
|
||||
|
||||
For each PR, fetch existing reviews AND changed files:
|
||||
For each PR, fetch reviews and changed files:
|
||||
|
||||
```bash
|
||||
gh api "repos/{owner}/{repo}/pulls/{num}/reviews" \
|
||||
--jq '[.[] | .user.login + ":" + .state] | join(", ")'
|
||||
|
||||
# Changed files (required for overlap detection)
|
||||
gh pr view {num} --json files --jq '[.files[].path] | join(",")'
|
||||
```
|
||||
|
||||
**Rate-limiting note**: fetching files requires N API calls (1 per PR). For repos with 20+ PRs, prioritize candidates for overlap detection (same functional domain, same author).
|
||||
|
||||
**Note**: `author` is an object `{login: "..."}` — always extract `.author.login`.
|
||||
**Notes**: Fetching files requires 1 API call per PR — for 20+ PRs, prioritize overlap candidates. The `author` field is an object; always extract `.author.login`.
|
||||
|
||||
### Analysis
|
||||
|
||||
|
|
@ -181,7 +168,6 @@ Note: Phase 3 (posting comments) is NOT offered here — it requires the drafts
|
|||
After displaying the triage table, copy to clipboard using platform-appropriate command:
|
||||
|
||||
```bash
|
||||
# Detect platform and copy
|
||||
UNAME=$(uname -s)
|
||||
if [ "$UNAME" = "Darwin" ]; then
|
||||
pbcopy <<'EOF'
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: release-notes-generator
|
||||
description: Generate release notes in 3 formats (CHANGELOG.md, PR body, Slack announcement) from git commits. Automatically categorizes changes and converts technical language to user-friendly messaging. Use when preparing a production release.
|
||||
description: "Generate release notes in 3 formats (CHANGELOG.md, PR body, Slack announcement) from git commits. Automatically categorizes changes and converts technical language to user-friendly messaging. Use for releases, changelogs, version notes, what's new summaries, or ship announcements."
|
||||
tags: [release-notes, changelog, slack, git, automation]
|
||||
---
|
||||
|
||||
|
|
@ -8,25 +8,14 @@ tags: [release-notes, changelog, slack, git, automation]
|
|||
|
||||
Generate comprehensive release notes in 3 formats from git commits.
|
||||
|
||||
## When to Use This Skill
|
||||
## Workflow
|
||||
|
||||
- Preparing a production release (develop -> main)
|
||||
- Creating release PR with proper documentation
|
||||
- Generating Slack announcement for stakeholders
|
||||
- Updating CHANGELOG.md with new version
|
||||
- Analyzing commits since last release
|
||||
|
||||
## What This Skill Does
|
||||
|
||||
1. **Analyzes Git History**: Scans commits since last release tag or specified version
|
||||
2. **Fetches PR Details**: Gets PR titles, descriptions, and labels via `gh api`
|
||||
3. **Categorizes Changes**: Groups into features, bug fixes, improvements, security, breaking changes
|
||||
4. **Generates 3 Outputs**:
|
||||
- **CHANGELOG.md section** (technical, complete)
|
||||
- **PR Release body** (semi-technical, checklist)
|
||||
- **Slack message** (product-focused, user-friendly)
|
||||
5. **Transforms Language**: Converts technical jargon to accessible messaging
|
||||
6. **Migration Alert**: Displays prominent warning if database migrations are required
|
||||
1. **Analyze git history** since last release tag or specified version
|
||||
2. **Fetch PR details** (titles, descriptions, labels) via `gh api`
|
||||
3. **Categorize changes** into features, bug fixes, improvements, security, breaking changes
|
||||
4. **Generate 3 outputs**: CHANGELOG.md section (technical), PR release body (semi-technical), Slack message (user-friendly)
|
||||
5. **Transform language** from technical jargon to accessible messaging
|
||||
6. **Alert on migrations** if database migrations are detected
|
||||
|
||||
## How to Use
|
||||
|
||||
|
|
|
|||
|
|
@ -1,144 +1,92 @@
|
|||
---
|
||||
name: rtk-optimizer
|
||||
description: Optimize command outputs with RTK (Rust Token Killer) for 70% token reduction
|
||||
description: "Wrap high-verbosity shell commands with RTK to reduce token consumption. Use when running git log, git diff, cargo test, pytest, or other verbose CLI output that wastes context window tokens."
|
||||
version: 1.0.0
|
||||
tags: [optimization, tokens, efficiency, git]
|
||||
---
|
||||
|
||||
# RTK Optimizer Skill
|
||||
|
||||
**Purpose**: Automatically suggest RTK wrappers for high-verbosity commands to reduce token consumption.
|
||||
Automatically suggest and apply RTK (Rust Token Killer) wrappers for verbose commands, reducing token usage by ~73% on average.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Detect high-verbosity commands** in user requests
|
||||
2. **Suggest RTK wrapper** if applicable
|
||||
2. **Suggest RTK wrapper** with expected savings
|
||||
3. **Execute with RTK** when user confirms
|
||||
4. **Track savings** over session
|
||||
4. **Track savings** over session via `rtk gain`
|
||||
|
||||
## Prerequisites
|
||||
|
||||
```bash
|
||||
rtk --version # Requires rtk 0.16.0+
|
||||
|
||||
# Install if needed:
|
||||
brew install rtk-ai/tap/rtk # macOS/Linux
|
||||
cargo install rtk # All platforms
|
||||
```
|
||||
|
||||
## Supported Commands
|
||||
|
||||
### Git (>70% reduction)
|
||||
- `git log` → `rtk git log` (92.3% reduction)
|
||||
- `git status` → `rtk git status` (76.0% reduction)
|
||||
- `find` → `rtk find` (76.3% reduction)
|
||||
|
||||
### Medium-Value (50-70% reduction)
|
||||
- `git diff` → `rtk git diff` (55.9% reduction)
|
||||
- `cat <large-file>` → `rtk read <file>` (62.5% reduction)
|
||||
|
||||
### JS/TS Stack (70-90% reduction)
|
||||
- `pnpm list` → `rtk pnpm list` (82% reduction)
|
||||
- `pnpm test` / `vitest run` → `rtk vitest run` (90% reduction)
|
||||
|
||||
### Rust Toolchain (80-90% reduction)
|
||||
- `cargo test` → `rtk cargo test` (90% reduction)
|
||||
- `cargo build` → `rtk cargo build` (80% reduction)
|
||||
- `cargo clippy` → `rtk cargo clippy` (80% reduction)
|
||||
|
||||
### Python & Go (90% reduction)
|
||||
- `pytest` → `rtk python pytest` (90% reduction)
|
||||
- `go test` → `rtk go test` (90% reduction)
|
||||
|
||||
### GitHub CLI (79-87% reduction)
|
||||
- `gh pr view` → `rtk gh pr view` (87% reduction)
|
||||
- `gh pr checks` → `rtk gh pr checks` (79% reduction)
|
||||
|
||||
### File Operations
|
||||
- `ls` → `rtk ls` (condensed output)
|
||||
- `grep` → `rtk grep` (filtered output)
|
||||
|
||||
## Activation Examples
|
||||
|
||||
**User**: "Show me the git history"
|
||||
**Skill**: Detects `git log` → Suggests `rtk git log` → Explains 92.3% token savings
|
||||
|
||||
**User**: "Find all markdown files"
|
||||
**Skill**: Detects `find` → Suggests `rtk find "*.md" .` → Explains 76.3% savings
|
||||
|
||||
## Installation Check
|
||||
|
||||
Before first use, verify RTK is installed:
|
||||
```bash
|
||||
rtk --version # Should output: rtk 0.16.0+
|
||||
```
|
||||
|
||||
If not installed:
|
||||
```bash
|
||||
# Homebrew (macOS/Linux)
|
||||
brew install rtk-ai/tap/rtk
|
||||
|
||||
# Cargo (all platforms)
|
||||
cargo install rtk
|
||||
```
|
||||
| Command | RTK Equivalent | Reduction |
|
||||
|---------|---------------|-----------|
|
||||
| `git log` | `rtk git log` | 92% (13,994 -> 1,076 chars) |
|
||||
| `git status` | `rtk git status` | 76% |
|
||||
| `git diff` | `rtk git diff` | 56% (15,815 -> 6,982 chars) |
|
||||
| `find` | `rtk find` | 76% |
|
||||
| `cat <large-file>` | `rtk read <file>` | 63% (163K -> 61K chars) |
|
||||
| `pnpm list` | `rtk pnpm list` | 82% |
|
||||
| `vitest run` / `pnpm test` | `rtk vitest run` | 90% |
|
||||
| `cargo test` | `rtk cargo test` | 90% |
|
||||
| `cargo build` | `rtk cargo build` | 80% |
|
||||
| `cargo clippy` | `rtk cargo clippy` | 80% |
|
||||
| `pytest` | `rtk python pytest` | 90% |
|
||||
| `go test` | `rtk go test` | 90% |
|
||||
| `gh pr view` | `rtk gh pr view` | 87% |
|
||||
| `gh pr checks` | `rtk gh pr checks` | 79% |
|
||||
| `ls` | `rtk ls` | condensed |
|
||||
| `grep` | `rtk grep` | filtered |
|
||||
|
||||
## Usage Pattern
|
||||
|
||||
```markdown
|
||||
# When user requests high-verbosity command:
|
||||
# When user requests a verbose command:
|
||||
|
||||
1. Acknowledge request
|
||||
2. Suggest RTK optimization:
|
||||
"I'll use `rtk git log` to reduce token usage by ~92%"
|
||||
3. Execute RTK command
|
||||
4. Track savings (optional):
|
||||
"Saved ~13K tokens (baseline: 14K, RTK: 1K)"
|
||||
1. Acknowledge the request
|
||||
2. Suggest RTK: "I'll use `rtk git log` to reduce token usage by ~92%"
|
||||
3. Execute the RTK-wrapped command
|
||||
4. Report savings: "Saved ~13K tokens (baseline: 14K, RTK: 1K)"
|
||||
```
|
||||
|
||||
## Activation Examples
|
||||
|
||||
**User**: "Show me the git history"
|
||||
**Action**: Detect `git log` -> execute `rtk git log` -> report 92% savings
|
||||
|
||||
**User**: "Run the test suite"
|
||||
**Action**: Detect `cargo test` / `pytest` -> execute `rtk cargo test` -> report 90% savings
|
||||
|
||||
## When to Skip RTK
|
||||
|
||||
- **Small outputs** (<100 chars): Overhead not worth it
|
||||
- **Claude built-in tools**: Grep/Read tools are already optimized
|
||||
- **Interactive commands**: RTK is for batch/non-interactive output only
|
||||
- **Multiple piped commands**: Wrap the outermost command, not each step
|
||||
|
||||
## Error Handling
|
||||
|
||||
- If `rtk` is not found, fall back to the raw command and suggest installation
|
||||
- If RTK output is empty or malformed, re-run without RTK and report the issue
|
||||
- If RTK version is outdated, warn about potential breaking changes (rapid release cadence)
|
||||
|
||||
## Session Tracking
|
||||
|
||||
Optional: Track cumulative savings across session:
|
||||
|
||||
```bash
|
||||
# At session end
|
||||
rtk gain # Shows total token savings for session (SQLite-backed)
|
||||
rtk gain # Shows cumulative token savings for the session (SQLite-backed)
|
||||
```
|
||||
|
||||
## Edge Cases
|
||||
|
||||
- **Small outputs** (<100 chars): Skip RTK (overhead not worth it)
|
||||
- **Already using Claude tools**: Grep/Read tools are already optimized
|
||||
- **Multiple commands**: Batch with RTK wrapper once, not per command
|
||||
|
||||
## Configuration
|
||||
|
||||
Enable via CLAUDE.md:
|
||||
```markdown
|
||||
## Token Optimization
|
||||
|
||||
Use RTK (Rust Token Killer) for high-verbosity commands:
|
||||
- git operations (log, status, diff)
|
||||
- package managers (pnpm, npm)
|
||||
- build tools (cargo, go)
|
||||
- test frameworks (vitest, pytest)
|
||||
- file finding and reading
|
||||
```
|
||||
|
||||
## Metrics (Verified)
|
||||
|
||||
Based on real-world testing:
|
||||
- `git log`: 13,994 chars → 1,076 chars (92.3% reduction)
|
||||
- `git status`: 100 chars → 24 chars (76.0% reduction)
|
||||
- `find`: 780 chars → 185 chars (76.3% reduction)
|
||||
- `git diff`: 15,815 chars → 6,982 chars (55.9% reduction)
|
||||
- `read file`: 163,587 chars → 61,339 chars (62.5% reduction)
|
||||
|
||||
**Average: 72.6% token reduction**
|
||||
|
||||
## Limitations
|
||||
|
||||
- 446 stars on GitHub, actively maintained (30 releases in 23 days)
|
||||
- Not suitable for interactive commands
|
||||
- Rapid development cadence (check for breaking changes)
|
||||
|
||||
## Recommendation
|
||||
|
||||
**Use RTK for**: git workflows, file operations, test frameworks, build tools, package managers
|
||||
**Skip RTK for**: small outputs, quick exploration, interactive commands
|
||||
|
||||
## References
|
||||
|
||||
- RTK GitHub: https://github.com/rtk-ai/rtk
|
||||
- RTK Website: https://www.rtk-ai.app/
|
||||
- Evaluation: `docs/resource-evaluations/rtk-evaluation.md`
|
||||
- CLAUDE.md template: `examples/claude-md/rtk-optimized.md`
|
||||
|
|
|
|||
|
|
@ -1,23 +1,21 @@
|
|||
---
|
||||
name: skill-creator
|
||||
description: Create new Claude Code skills with proper structure, YAML frontmatter, and bundled resources. Generates skill templates following best practices for modular, self-contained capability packages.
|
||||
description: "Scaffold a new Claude Code skill with SKILL.md, frontmatter, and bundled resources. Use when creating a custom skill, standardizing skill structure across a team, or packaging a skill for distribution."
|
||||
tags: [meta, skill, generator, claude-code]
|
||||
---
|
||||
|
||||
# Skill Creator
|
||||
|
||||
This skill helps you create new Claude Code skills with proper structure and best practices.
|
||||
Generate new Claude Code skills with correct directory structure, YAML frontmatter, and optional bundled resources.
|
||||
|
||||
## When to Use This Skill
|
||||
## When to Use
|
||||
|
||||
- Creating a new custom skill for your project
|
||||
- Standardizing skill structure across your team
|
||||
- Creating a new custom skill for a project
|
||||
- Standardizing skill structure across a team
|
||||
- Generating skill templates with scripts, references, and assets
|
||||
- Packaging skills for distribution
|
||||
|
||||
## Skill Structure
|
||||
|
||||
A Claude skill consists of:
|
||||
## Skill Directory Structure
|
||||
|
||||
```
|
||||
skill-name/
|
||||
|
|
@ -27,99 +25,71 @@ skill-name/
|
|||
└── assets/ # Optional: Templates, images, boilerplate (not loaded into context)
|
||||
```
|
||||
|
||||
## SKILL.md Format
|
||||
## Workflow
|
||||
|
||||
Every skill requires a `SKILL.md` file with:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: One-line description of what the skill does and when to use it.
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
Brief introduction explaining the skill's purpose.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Trigger condition 1
|
||||
- Trigger condition 2
|
||||
- Trigger condition 3
|
||||
|
||||
## What This Skill Does
|
||||
|
||||
1. **Step 1**: Description
|
||||
2. **Step 2**: Description
|
||||
3. **Step 3**: Description
|
||||
|
||||
## How to Use
|
||||
|
||||
### Basic Usage
|
||||
[Examples of how to invoke the skill]
|
||||
|
||||
### With Options
|
||||
[Advanced usage patterns]
|
||||
|
||||
## Example
|
||||
|
||||
**User**: "Example prompt"
|
||||
|
||||
**Output**:
|
||||
[Example output]
|
||||
|
||||
## Tips
|
||||
|
||||
- Best practice 1
|
||||
- Best practice 2
|
||||
|
||||
## Related Use Cases
|
||||
|
||||
- Related task 1
|
||||
- Related task 2
|
||||
```
|
||||
|
||||
## How to Use
|
||||
|
||||
### Create a New Skill
|
||||
### 1. Create the Skill
|
||||
|
||||
```
|
||||
Create a new skill called "my-skill-name" in ~/.claude/skills/
|
||||
```
|
||||
|
||||
### Create with Specific Purpose
|
||||
Or with a specific purpose:
|
||||
|
||||
```
|
||||
Create a skill for generating release notes from git commits,
|
||||
with templates for CHANGELOG.md and Slack announcements
|
||||
```
|
||||
|
||||
### Initialize Skill Structure
|
||||
|
||||
Run the initialization script:
|
||||
Or via the initialization script:
|
||||
|
||||
```bash
|
||||
python3 ~/.claude/skills/skill-creator/scripts/init_skill.py <skill-name> --path <output-directory>
|
||||
```
|
||||
|
||||
### Package Skill for Distribution
|
||||
### 2. Generated SKILL.md Template
|
||||
|
||||
The created SKILL.md follows this structure:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: "What the skill does. Use when [trigger conditions]."
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
## When to Use
|
||||
- Trigger condition 1
|
||||
- Trigger condition 2
|
||||
|
||||
## What This Skill Does
|
||||
1. **Step 1**: Description
|
||||
2. **Step 2**: Description
|
||||
|
||||
## How to Use
|
||||
[Usage examples]
|
||||
|
||||
## Example
|
||||
**User**: "Example prompt"
|
||||
**Output**: [Example output]
|
||||
```
|
||||
|
||||
### 3. Validate the Skill
|
||||
|
||||
After creation, verify:
|
||||
|
||||
1. **Frontmatter**: `name` is kebab-case, 1-64 chars; `description` is a quoted string with "Use when" clause
|
||||
2. **Content**: Has "When to Use" section with trigger conditions and at least one usage example
|
||||
3. **Structure**: SKILL.md is under 5000 words; references and assets are in correct subdirectories
|
||||
4. **Test**: Invoke the skill with a real use case and confirm expected output
|
||||
|
||||
### 4. Package for Distribution (Optional)
|
||||
|
||||
```bash
|
||||
python3 ~/.claude/skills/skill-creator/scripts/package_skill.py <path/to/skill-folder> [output-directory]
|
||||
```
|
||||
|
||||
## Design Principles
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
Context loads hierarchically to optimize token usage:
|
||||
1. **Metadata** (~100 words): Always present via skill description
|
||||
2. **SKILL.md** (<5k words): Loaded when skill is triggered
|
||||
3. **Bundled resources**: Loaded as needed during execution
|
||||
|
||||
### Organizational Patterns
|
||||
|
||||
Choose the pattern that fits your skill:
|
||||
## Organizational Patterns
|
||||
|
||||
| Pattern | Best For | Structure |
|
||||
|---------|----------|-----------|
|
||||
|
|
@ -128,59 +98,22 @@ Choose the pattern that fits your skill:
|
|||
| **Reference/Guidelines** | Standards, specs | Rules and examples |
|
||||
| **Capabilities-Based** | Interrelated features | Feature descriptions |
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- Use `kebab-case` for skill names: `release-notes-generator`
|
||||
- Use descriptive names that indicate purpose
|
||||
- Keep names concise but meaningful
|
||||
|
||||
## Bundled Resources
|
||||
|
||||
### scripts/
|
||||
|
||||
Executable code for deterministic, repeatable tasks:
|
||||
- `init_skill.py` - Initialize new skill structure
|
||||
- `package_skill.py` - Package skill for distribution
|
||||
|
||||
### references/
|
||||
|
||||
Documentation loaded contextually:
|
||||
- API documentation
|
||||
- Style guides
|
||||
- Domain knowledge
|
||||
|
||||
### assets/
|
||||
|
||||
Templates and resources (not auto-loaded):
|
||||
- Output templates
|
||||
- Boilerplate code
|
||||
- Images and fonts
|
||||
|
||||
## Example: Creating a Release Notes Skill
|
||||
|
||||
**User**: "Create a skill for generating release notes with 3 output formats: CHANGELOG.md, PR body, and Slack message"
|
||||
**User**: "Create a skill for generating release notes with 3 output formats"
|
||||
|
||||
**Steps**:
|
||||
1. Initialize structure: `init_skill.py release-notes-generator --path ~/.claude/skills/`
|
||||
2. Add templates to `assets/`:
|
||||
- `changelog-template.md`
|
||||
- `pr-release-template.md`
|
||||
- `slack-template.md`
|
||||
3. Add transformation rules to `references/`:
|
||||
- `tech-to-product-mappings.md`
|
||||
1. Initialize: `init_skill.py release-notes-generator --path ~/.claude/skills/`
|
||||
2. Add templates to `assets/`: `changelog-template.md`, `pr-release-template.md`, `slack-template.md`
|
||||
3. Add rules to `references/`: `tech-to-product-mappings.md`
|
||||
4. Complete `SKILL.md` with usage instructions
|
||||
5. Package: `package_skill.py ~/.claude/skills/release-notes-generator`
|
||||
5. Validate: check frontmatter, test with a real commit range
|
||||
6. Package: `package_skill.py ~/.claude/skills/release-notes-generator`
|
||||
|
||||
## Tips
|
||||
|
||||
- Keep SKILL.md under 5000 words for efficient context usage
|
||||
- Use references/ for domain knowledge that doesn't change often
|
||||
- Put templates in assets/ so they're not auto-loaded
|
||||
- Test your skill with real use cases before packaging
|
||||
- Include concrete examples in your SKILL.md
|
||||
|
||||
## Related Use Cases
|
||||
|
||||
- Creating project-specific automation skills
|
||||
- Building team-shared development workflows
|
||||
- Packaging reusable Claude capabilities
|
||||
- Use `references/` for domain knowledge that doesn't change often
|
||||
- Put templates in `assets/` so they're not auto-loaded into context
|
||||
- Always include a "Use when" clause in the description frontmatter
|
||||
- Test with real use cases before packaging
|
||||
|
|
|
|||
|
|
@ -1,12 +1,8 @@
|
|||
---
|
||||
name: talk-pipeline
|
||||
description: Orchestrator for the complete talk preparation pipeline (REX or Concept mode). Runs all 6 stages in sequence with human-in-the-loop checkpoints.
|
||||
description: "Orchestrates the complete talk preparation pipeline from raw material to revision sheets, running 6 stages in sequence with human-in-the-loop checkpoints for REX or Concept mode talks. Use when starting a new talk pipeline, resuming a pipeline from a specific stage, or running the full end-to-end preparation workflow."
|
||||
tags: [talk, pipeline, presentation, orchestrator]
|
||||
allowed-tools:
|
||||
- Write
|
||||
- Read
|
||||
- AskUserQuestion
|
||||
- Task
|
||||
allowed-tools: "Write, Read, AskUserQuestion, Task"
|
||||
---
|
||||
|
||||
# Talk Pipeline Orchestrator
|
||||
|
|
|
|||
|
|
@ -1,11 +1,8 @@
|
|||
---
|
||||
name: talk-stage1-extract
|
||||
description: Stage 1 — Extract and structure source material into a talk summary. Auto-detects REX vs Concept type.
|
||||
description: "Extracts and structures source material (articles, transcripts, notes) into a talk summary with narrative arc, themes, metrics, and gaps. Auto-detects REX vs Concept type. Use when starting a new talk from any source material or auditing existing material before committing to a talk."
|
||||
tags: [talk, pipeline, presentation, stage-1]
|
||||
allowed-tools:
|
||||
- Write
|
||||
- Read
|
||||
- AskUserQuestion
|
||||
allowed-tools: "Write, Read, AskUserQuestion"
|
||||
---
|
||||
|
||||
# Talk Stage 1: Extract
|
||||
|
|
|
|||
|
|
@ -1,11 +1,8 @@
|
|||
---
|
||||
name: talk-stage2-research
|
||||
description: Stage 2 (REX mode only) — Git archaeology, changelog analysis, verified factual timeline. Skip automatically in Concept mode.
|
||||
description: "Performs git archaeology, changelog analysis, and builds a verified factual timeline by cross-referencing git history with source material. REX mode only — skipped automatically in Concept mode. Use when building a REX talk and you need verified commit metrics, release timelines, and contributor data from a git repository."
|
||||
tags: [talk, pipeline, presentation, stage-2, git]
|
||||
allowed-tools:
|
||||
- Write
|
||||
- Read
|
||||
- Bash
|
||||
allowed-tools: "Write, Read, Bash"
|
||||
---
|
||||
|
||||
# Talk Stage 2: Research (REX mode only)
|
||||
|
|
|
|||
|
|
@ -1,10 +1,8 @@
|
|||
---
|
||||
name: talk-stage3-concepts
|
||||
description: Stage 3 — Build a numbered, scored concept catalogue. Every concept gets HIGH / MEDIUM / LOW talk-potential rating.
|
||||
description: "Builds a numbered, categorized concept catalogue from the talk summary and timeline, scoring each concept HIGH / MEDIUM / LOW for talk potential with optional repo enrichment. Use when you need a structured inventory of concepts before choosing a talk angle, or when assessing which ideas have the strongest presentation potential."
|
||||
tags: [talk, pipeline, presentation, stage-3]
|
||||
allowed-tools:
|
||||
- Write
|
||||
- Read
|
||||
allowed-tools: "Write, Read"
|
||||
---
|
||||
|
||||
# Talk Stage 3: Concepts
|
||||
|
|
|
|||
|
|
@ -1,11 +1,8 @@
|
|||
---
|
||||
name: talk-stage4-position
|
||||
description: Stage 4 — Strategic angles, titles, descriptions, peer feedback draft. Includes mandatory CHECKPOINT before script can start.
|
||||
description: "Generates 3-4 strategic talk angles with strength/weakness analysis, title options, CFP descriptions, and a peer feedback draft, then enforces a mandatory CHECKPOINT for user confirmation before scripting. Use when deciding how to frame a talk, preparing a CFP submission, or choosing between multiple narrative angles."
|
||||
tags: [talk, pipeline, presentation, stage-4, checkpoint]
|
||||
allowed-tools:
|
||||
- Write
|
||||
- Read
|
||||
- AskUserQuestion
|
||||
allowed-tools: "Write, Read, AskUserQuestion"
|
||||
---
|
||||
|
||||
# Talk Stage 4: Position + CHECKPOINT
|
||||
|
|
|
|||
|
|
@ -1,10 +1,8 @@
|
|||
---
|
||||
name: talk-stage5-script
|
||||
description: Stage 5 — 5-act pitch with speaker notes, slide spec, and Kimi prompt for AI slide generation. Requires validated angle + title from Stage 4.
|
||||
description: "Produces a complete 5-act pitch with speaker notes, a slide-by-slide specification, and a ready-to-paste Kimi prompt for AI slide generation. Requires validated angle and title from Stage 4. Use when you have a confirmed talk angle and need the full script, slide spec, and AI-generated presentation prompt."
|
||||
tags: [talk, pipeline, presentation, stage-5, kimi]
|
||||
allowed-tools:
|
||||
- Write
|
||||
- Read
|
||||
allowed-tools: "Write, Read"
|
||||
---
|
||||
|
||||
# Talk Stage 5: Script
|
||||
|
|
|
|||
|
|
@ -1,10 +1,8 @@
|
|||
---
|
||||
name: talk-stage6-revision
|
||||
description: Stage 6 — Revision sheets for during and after the talk. Master concept table, Q&A cheat-sheet, glossary, external resources.
|
||||
description: "Produces revision sheets with quick navigation by act, a master concept-to-URL table, Q&A cheat-sheet with 6-10 anticipated questions, glossary, and external resources list. Use when preparing for a talk with Q&A, creating shareable reference material for attendees, or building a safety-net glossary for live delivery."
|
||||
tags: [talk, pipeline, presentation, stage-6]
|
||||
allowed-tools:
|
||||
- Write
|
||||
- Read
|
||||
allowed-tools: "Write, Read"
|
||||
---
|
||||
|
||||
# Talk Stage 6: Revision
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: voice-refine
|
||||
description: Transform verbose voice input into optimized Claude prompts
|
||||
description: "Transform verbose voice input into structured, token-efficient Claude prompts. Use when cleaning up voice memos, dictation output, or speech-to-text transcriptions that contain filler words, repetitions, and unstructured thoughts."
|
||||
allowed-tools: Read
|
||||
context: inherit
|
||||
agent: specialist
|
||||
|
|
@ -85,39 +85,11 @@ dans le projet donc faut que ça matche avec ça...
|
|||
| Information retention | >95% |
|
||||
| Structure clarity | High |
|
||||
|
||||
## Integration with Voice Tools
|
||||
## Filtering Rules
|
||||
|
||||
### Wispr Flow
|
||||
1. Dictate with `Cmd+Shift+Space`
|
||||
2. Paste into Claude Code
|
||||
3. Run `/voice-refine`
|
||||
**Remove**: filler words ("euh", "um", "like", "basically"), repetitions, tangents, hedging ("maybe", "probably" unless relevant), politeness padding ("please", "could you").
|
||||
|
||||
### Superwhisper
|
||||
1. Record with hotkey
|
||||
2. Text appears in active window
|
||||
3. Run `/voice-refine` to structure
|
||||
|
||||
### macOS Dictation
|
||||
1. `Fn Fn` to start
|
||||
2. Speak naturally
|
||||
3. Run `/voice-refine` to clean up
|
||||
|
||||
## What Gets Removed
|
||||
|
||||
- Filler words: "euh", "um", "like", "you know", "basically"
|
||||
- Repetitions: same concept stated multiple ways
|
||||
- Tangents: off-topic thoughts
|
||||
- Hedging: "maybe", "I think", "probably" (unless relevant)
|
||||
- Politeness padding: "please", "could you", "I'd like"
|
||||
|
||||
## What Gets Preserved
|
||||
|
||||
- Technical requirements
|
||||
- Constraints and limitations
|
||||
- Context about existing code
|
||||
- Expected output format
|
||||
- Edge cases mentioned
|
||||
- Business logic rules
|
||||
**Preserve**: technical requirements, constraints, existing code context, expected output format, edge cases, business logic rules.
|
||||
|
||||
## See Also
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue