Skip to content

notque/vexjoy-agent / skills/meta/toolkit

toolkit

Verified

Toolkit management: create and evaluate skills and agents, manage routing tables, generate Claude.md.

FileKindSize
SKILL.mdskill md15.5 KB
agents/skill-creator/analyzer.mdmarkdown4.8 KB
agents/skill-creator/comparator.mdmarkdown4.7 KB
agents/skill-creator/grader.mdmarkdown3.9 KB
assets/skill-creator/eval_viewer.htmlother57.1 KB
references/agent-comparison.mdmarkdown11.5 KB
references/agent-comparison/benchmark-tasks.mdmarkdown6.8 KB
references/agent-comparison/do-creation-compliance-tasks.jsonconfig8.5 KB
references/agent-comparison/examples-and-errors.mdmarkdown1.0 KB
references/agent-comparison/grading-rubric.mdmarkdown4.3 KB
references/agent-comparison/methodology.mdmarkdown7.4 KB
references/agent-comparison/optimization-guide.mdmarkdown12.0 KB
references/agent-comparison/optimization-tasks.example.jsonconfig853 B
references/agent-comparison/optimize-phase.mdmarkdown9.3 KB
references/agent-comparison/read-only-ops-short-tasks.jsonconfig375 B
references/agent-comparison/report-template.mdmarkdown3.8 KB
references/agent-comparison/socratic-debugging-body-short-tasks.jsonconfig372 B
references/agent-comparison/socratic-debugging-trigger-tasks.jsonconfig2.8 KB
references/agent-creator.mdmarkdown10.9 KB
references/agent-creator/agent-design-patterns.mdmarkdown12.4 KB
references/agent-creator/agent-eval-design.mdmarkdown7.7 KB
references/agent-creator/agent-frontmatter-template.mdmarkdown9.3 KB
references/agent-evaluation.mdmarkdown10.6 KB
references/agent-evaluation/batch-evaluation.mdmarkdown1.6 KB
references/agent-evaluation/common-issues.mdmarkdown2.1 KB
references/agent-evaluation/report-templates.mdmarkdown2.2 KB
references/agent-evaluation/scoring-rubric.mdmarkdown2.4 KB
references/blind-ab-tests.mdmarkdown7.8 KB
references/generate-claudemd.mdmarkdown11.0 KB
references/generate-claudemd/CLAUDEMD_TEMPLATE.mdmarkdown4.1 KB
references/generate-claudemd/examples-and-errors.mdmarkdown7.4 KB
references/github-profile-rules.mdmarkdown7.5 KB
references/github-profile-rules/github-api-patterns.mdmarkdown8.2 KB
references/github-profile-rules/rule-categories.mdmarkdown4.8 KB
references/hook-development.mdmarkdown10.9 KB
references/hook-development/architecture.mdmarkdown3.7 KB
references/hook-development/code-examples.mdmarkdown9.4 KB
references/hook-development/preferred-patterns.mdmarkdown6.5 KB
references/hook-development/telemetry-database.mdmarkdown6.5 KB
references/routing-table-updater.mdmarkdown10.2 KB
references/routing-table-updater/batch-mode.mdmarkdown2.1 KB
references/routing-table-updater/conflict-resolution.mdmarkdown3.8 KB
references/routing-table-updater/error-handling.mdmarkdown1.9 KB
references/routing-table-updater/examples.mdmarkdown4.8 KB
references/routing-table-updater/extraction-patterns.mdmarkdown2.2 KB
references/routing-table-updater/routing-format.mdmarkdown3.6 KB
references/routing-table-updater/skill-examples.mdmarkdown2.7 KB
references/skill-composer.mdmarkdown9.1 KB
references/skill-composer/compatibility-matrix.mdmarkdown13.0 KB
references/skill-composer/composition-patterns.mdmarkdown4.9 KB
references/skill-composer/examples.mdmarkdown17.1 KB
references/skill-composer/skill-patterns.mdmarkdown12.5 KB
references/skill-creator.mdmarkdown28.9 KB
references/skill-creator/agent-template.mdmarkdown18.5 KB
references/skill-creator/artifact-schemas.mdmarkdown8.2 KB
references/skill-creator/bundled-components.mdmarkdown2.3 KB
references/skill-creator/complexity-tiers.mdmarkdown8.0 KB
references/skill-creator/domain-research-targets.mdmarkdown13.2 KB
references/skill-creator/enrichment-workflow.mdmarkdown9.9 KB
references/skill-creator/error-catalog.mdmarkdown9.9 KB
references/skill-creator/preferred-patterns.mdmarkdown11.7 KB
references/skill-creator/progressive-disclosure.mdmarkdown8.5 KB
references/skill-creator/skill-template.mdmarkdown14.6 KB
references/skill-creator/workflow-patterns.mdmarkdown7.6 KB
references/system-upgrade.mdmarkdown11.0 KB
references/system-upgrade/component-audit-checklists.mdmarkdown8.4 KB
references/system-upgrade/upgrade-failure-modes.mdmarkdown8.7 KB
references/system-upgrade/upgrade-signal-parsing.mdmarkdown7.3 KB
references/toolkit-evolution.mdmarkdown14.5 KB
references/toolkit-evolution/diagnose-scripts.mdmarkdown9.5 KB
references/toolkit-evolution/evolution-history.mdmarkdown5.5 KB
references/toolkit-evolution/evolution-report-template.mdmarkdown716 B
references/toolkit-evolution/evolve-preferred-patterns.mdmarkdown6.9 KB
references/toolkit-evolution/evolve-scripts.mdmarkdown3.7 KB
references/toolkit-governance.mdmarkdown16.0 KB
references/toolkit-governance/adr-lifecycle.mdmarkdown10.9 KB
references/toolkit-governance/frontmatter-compliance.mdmarkdown11.1 KB
references/toolkit-governance/hook-standardization.mdmarkdown21.5 KB
references/toolkit-governance/routing-table-patterns.mdmarkdown11.6 KB
references/weak-model-uplift.mdmarkdown10.3 KB
scripts/agent-comparison/compare.pyscript2.3 KB
scripts/agent-comparison/generate_variant.pyscript19.6 KB
scripts/agent-comparison/optimize_loop.pyscript89.3 KB
scripts/agent-comparison/trigger_eval.pyscript19.5 KB
scripts/routing-table-updater/extract_metadata.pyscript10.8 KB
scripts/routing-table-updater/generate_routes.pyscript10.5 KB
scripts/routing-table-updater/scan.pyscript4.7 KB
scripts/routing-table-updater/update_routing.pyscript12.4 KB
scripts/routing-table-updater/validate.pyscript7.3 KB
scripts/skill-composer/build_dag.pyscript12.5 KB
scripts/skill-composer/discover_skills.pyscript12.1 KB
scripts/skill-composer/validate.pyscript12.3 KB
scripts/skill-creator/aggregate_benchmark.pyscript10.0 KB
scripts/skill-creator/eval_compare.pyscript10.2 KB
scripts/skill-creator/optimize_description.pyscript12.5 KB
scripts/skill-creator/package_results.pyscript7.8 KB
scripts/skill-creator/run_eval.pyscript6.3 KB

references/skill-composer/skill-patterns.md

View on GitHub
# Common Skill Composition Patterns

This document describes proven patterns for composing multiple skills into effective workflows.

## Pattern Catalog

### 1. Feature Development Pipeline

**Pattern**: `workflow-orchestrator → test-driven-development → verification-before-completion`

**When to Use**:
- Adding new features to codebase
- Need structured task breakdown
- Require comprehensive testing
- Want verification before completion

**Example Task**: "Add user authentication feature with tests"

**Execution Flow**:
1. **workflow-orchestrator**: Breaks feature into 2-5 minute subtasks with exact file paths
2. **test-driven-development**: Implements each subtask with RED-GREEN-REFACTOR cycle
3. **verification-before-completion**: Validates tests pass, code quality meets standards

**Expected Duration**: 20-40 minutes depending on feature complexity

**Success Criteria**:
- All subtasks completed
- Tests pass (RED → GREEN achieved)
- Code refactored for quality
- Verification gates passed

---

### 2. Debug and Document

**Pattern**: `systematic-debugging → comment-quality`

**When to Use**:
- Fixing bugs in production code
- Need root cause analysis
- Want proper documentation of fixes
- Prevent temporal references in comments

**Example Task**: "Debug authentication timeout and document the fix"

**Execution Flow**:
1. **systematic-debugging**: 4-phase root cause analysis (Reproduce → Isolate → Identify → Verify)
2. **comment-quality**: Reviews fix comments to ensure they explain WHAT/WHY, not WHEN

**Expected Duration**: 15-30 minutes

**Success Criteria**:
- Bug root cause identified
- Fix verified with tests
- Comments explain logic, not history
- No temporal references ("fixed bug", "TODO")

---

### 3. Parallel Quality Checks

**Pattern**: `[code-linting, comment-quality] → verification-before-completion`

**When to Use**:
- Improving existing code quality
- Pre-commit validation
- Preparing code for review
- Independent quality dimensions

**Example Task**: "Check code quality and documentation before PR"

**Execution Flow**:
1. **Phase 1 (Parallel)**:
   - `code-linting`: Run ruff (Python) or Biome (JS) linters
   - `comment-quality`: Check for temporal references in comments
2. **Phase 2 (Sequential)**:
   - `verification-before-completion`: Ensure all quality gates pass

**Expected Duration**: 5-10 minutes

**Parallelization Benefit**: ~50% time reduction compared to sequential

**Success Criteria**:
- Linting passes (or auto-fixed)
- Comments are timeless
- All verification checks pass

---

### 4. Research-Driven Implementation

**Pattern**: `pr-workflow (miner) → codebase-analyzer → workflow-orchestrator → test-driven-development`

**When to Use**:
- Implementing features in unfamiliar codebase
- Want to learn existing patterns first
- Need coding standards from PR reviews
- Building on established conventions

**Example Task**: "Add rate limiting following existing patterns"

**Execution Flow**:
1. **pr-workflow (miner)**: Mine GitHub PR review comments for tribal knowledge
2. **codebase-analyzer**: Extract implementation patterns from existing code
3. **workflow-orchestrator**: Plan implementation based on learned patterns
4. **test-driven-development**: Implement following discovered conventions

**Expected Duration**: 40-60 minutes

**Success Criteria**:
- Patterns extracted from existing code
- Implementation follows established conventions
- Tests validate behavior
- Code style matches project standards

---

### 5. Language-Specific Quality Gate

**Pattern**: `test-driven-development → (if Go: go-patterns, else: code-linting)`

**When to Use**:
- Multi-language projects
- Language-specific quality requirements
- Different validation tools per language

**Example Task**: "Implement feature with language-appropriate quality checks"

**Execution Flow**:
1. **test-driven-development**: Implement feature with tests
2. **Conditional Branch**:
   - If Go: `go-patterns` (golangci-lint, go test, go build)
   - Else: `code-linting` (ruff for Python, Biome for JS)

**Expected Duration**: 20-35 minutes

**Success Criteria**:
- Feature implemented with tests
- Language-specific linting passes
- Quality gates appropriate to language

---

### 6. Documentation Audit and Enhancement

**Pattern**: `codebase-analyzer → comment-quality → (generate docs)`

**When to Use**:
- Auditing documentation quality
- Preparing for external users
- Improving maintainability
- Removing outdated comments

**Example Task**: "Audit and improve documentation quality"

**Execution Flow**:
1. **codebase-analyzer**: Analyze code structure and patterns
2. **comment-quality**: Identify temporal references and poor documentation
3. **Generate docs**: Create/update documentation based on findings

**Expected Duration**: 25-40 minutes

**Success Criteria**:
- Code structure documented
- Temporal references removed
- Comments explain WHAT/WHY
- Documentation reflects current state

---

### 7. Comprehensive Quality Gate

**Pattern**: `test-driven-development → (language-specific-quality-gate) → verification-before-completion`

**When to Use**:
- Need comprehensive language-specific validation
- Running multiple quality tools in one step
- Want automated language detection for multi-language projects

**Example Task**: "Implement feature with comprehensive quality checks"

**Execution Flow**:
1. **test-driven-development**: Implement with RED-GREEN-REFACTOR
2. **Language-specific gate**:
   - Go projects: `go-patterns` (golangci-lint, tests, race detector, build)
   - Python projects: `python-quality-gate` (ruff, pytest, mypy, bandit)
   - Multi-language: `universal-quality-gate` (auto-detect and run appropriate tools)
3. **verification-before-completion**: Final validation

**Expected Duration**: 20-35 minutes

**Success Criteria**:
- All tests pass with good coverage
- Language-specific linting passes
- No security issues detected
- Type checking passes (where applicable)
- Code ready for production

---

### 8. Loop Until Clean

**Pattern**: `code-linting → (if violations: fix-violations → code-linting, else: done)`

**When to Use**:
- Iteratively fixing linting violations
- Auto-fix not sufficient alone
- Want guarantee of clean code

**Example Task**: "Fix all linting violations in module"

**Execution Flow**:
1. **code-linting**: Identify violations
2. **Loop Decision**:
   - If violations > 0: Fix violations and re-lint
   - Else: Exit loop
3. **Maximum iterations**: 5 (prevent infinite loops)

**Expected Duration**: 5-20 minutes depending on violations

**Success Criteria**:
- Zero linting violations
- Code follows style guidelines
- Loop completed in < 5 iterations

---

## Composition Guidelines

### Sequential vs Parallel Decision Tree

```
Can skills run independently?
│
├─ YES → Consider parallel execution
│   ├─ Do they share resources?
│   │   ├─ YES → Sequential (avoid conflicts)
│   │   └─ NO → Parallel (maximize speed)
│   └─ Is output needed by another skill?
│       ├─ YES → Sequential (dependency)
│       └─ NO → Parallel
│
└─ NO → Sequential execution required
    └─ What's the dependency order?
        └─ Use topological sort
```

### Conditional Execution Guidelines

**When to use conditionals**:
- Language-specific tooling (Go vs Python vs JS)
- Error recovery paths (if fails, try alternative)
- Optional enhancements (if time permits, add feature)
- Environment-specific (if production, extra validation)

**When NOT to use conditionals**:
- Core workflow steps (always run)
- Simple linear sequences (just chain them)
- Overly complex branching (split into separate compositions)

### Loop Composition Guidelines

**Safe loop patterns**:
```
loop until clean:
  - linting → fix → re-lint
  - test → fix failures → re-test
  - validate → improve → re-validate
```

**Required safeguards**:
- **Maximum iterations**: Always set (typically 3-5)
- **Progress check**: Ensure each iteration improves (fewer violations, fewer failures)
- **Exit condition**: Clear definition of "done"
- **Timeout**: Overall time limit for loop

**Watch for**:
- Infinite loops; always set max iterations
- No progress detection; require a progress check
- Complex multi-skill loops; split them when the flow is harder to debug

---

## Patterns to Detect and Fix

### Signal 1: Over-Composition
**Signal**: Chaining too many skills (6+) in a single workflow
**Why It Matters**: The workflow becomes harder to reason about and easier to break
**Preferred Action**: Break the work into multiple compositions or use workflow-orchestrator to manage complexity

### Signal 2: Circular Dependencies
**Signal**: Skill A depends on B, B depends on C, C depends on A
**Why It Matters**: Cycles make routing and execution order ambiguous
**Preferred Action**: Redesign to remove cycles or split the work into independent workflows

### Signal 3: False Parallelism
**Signal**: Running skills "in parallel" that actually share resources
**Why It Matters**: Shared resources create contention and non-deterministic behavior
**Preferred Action**: Identify the resource conflicts and run the steps sequentially

### Signal 4: Missing Verification
**Signal**: Implementing features without a verification step
**Why It Matters**: Unverified work can regress silently
**Preferred Action**: End with `verification-before-completion` or an equivalent check

### Signal 5: Premature Optimization
**Signal**: Forcing parallelism where sequential is clearer
**Why It Matters**: Early parallelism adds coordination cost before there is evidence it helps
**Preferred Action**: Start sequential and parallelize only when a bottleneck is confirmed

---

## Pattern Selection Guide

| Task Type | Recommended Pattern | Duration | Complexity |
|-----------|---------------------|----------|------------|
| Add feature | Feature Development Pipeline | 20-40 min | Medium |
| Fix bug | Debug and Document | 15-30 min | Low |
| Quality check | Parallel Quality Checks | 5-10 min | Low |
| Learn codebase | Research-Driven Implementation | 40-60 min | High |
| Multi-language | Language-Specific Quality Gate | 20-35 min | Medium |
| Doc audit | Documentation Audit | 25-40 min | Medium |
| Style enforcement | Style Compliance | 10-15 min | Low |
| Fix violations | Loop Until Clean | 5-20 min | Low |

---

## Advanced Techniques

### Pattern Composition

Combine patterns for complex workflows:

```
Research-Driven Implementation + Style Compliance:
  pr-workflow (miner) → codebase-analyzer → workflow-orchestrator →
  verification-before-completion
```

### Adaptive Composition

Modify execution based on intermediate results:

```
Initial: test-driven-development
If tests reveal complexity: insert systematic-debugging before continue
If code quality low: insert code-linting after tests
```

### Nested Composition

Use workflow-orchestrator to manage sub-compositions:

```
workflow-orchestrator:
  Subtask 1: Feature Development Pipeline
  Subtask 2: Parallel Quality Checks
  Subtask 3: Documentation Audit
```

---

## Performance Optimization

### Parallelization Strategies

**Maximum Benefit**:
- Independent code analysis (linting + documentation)
- Multiple test suites (unit + integration)
- Different quality dimensions (style + security)

**Overhead Considerations**:
- Skill invocation: ~2-3 seconds per skill
- Context passing: ~0.5-1 second per transition
- Parallel coordination: ~10% overhead

**When to Parallelize**:
- Skills take > 30 seconds each
- No shared resource conflicts
- Independent outputs
- 2-4 skills in parallel (sweet spot)

**When to Stay Sequential**:
- Skills take < 10 seconds each
- Output needed by next skill
- Shared resource access
- Complex error recovery needed

---

## Troubleshooting Compositions

### Common Issues

**Issue**: "Skills selected don't match task"
**Cause**: Task analysis failed to identify goals
**Fix**: Make task description more explicit about goals

**Issue**: "Circular dependency detected"
**Cause**: Skills reference each other cyclically
**Fix**: Remove one dependency or split into separate compositions

**Issue**: "Skill outputs incompatible"
**Cause**: Output format doesn't match next skill's input
**Fix**: Add transformation step or choose different skills

**Issue**: "Parallel execution slower than expected"
**Cause**: Resource contention or coordination overhead
**Fix**: Make sequential or reduce parallel skill count

**Issue**: "Loop never terminates"
**Cause**: Exit condition never met or max iterations too high
**Fix**: Lower max iterations or fix exit condition logic

---

This pattern catalog provides proven compositions for common development workflows. Use these as starting points and adapt to your specific needs.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall