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/agent-creator.md

View on GitHub
# Agent Creator

Repo agents are retired (plan 009). A request to create an agent in this repo produces a skill reference: `skills/<category>/<skill>/references/<slug>.md`, with depth in `references/<slug>/`. When no skill fits the domain, create a new skill (Create Skill mode) and put the reference under it. Work runs in the main thread; when dispatch pays, a fresh `general-purpose` worker gets a prompt that starts: "Read ~/.claude/skills/<skill>/references/<slug>.md and follow it; load every file its Reference Loading Table matches."

A reference is a contract: it sets constraints, expertise, and phases, not application code.

An agent `.md` file is written only when the owner asks for a private overlay agent. See "Private overlay agent (owner request only)" at the end.

Phases: **DISCOVER → DESIGN → SCAFFOLD → REGISTER → VALIDATE**

---

## Phase 1 — DISCOVER

Check for domain overlap before creating anything.

```bash
grep -ril "<domain-keyword>" skills/*/*/SKILL.md skills/*/*/references/*.md | sort -u
ls skills/*/*/references/ | grep "<domain-prefix>"
```

Gate 1: If an existing skill reference covers the domain, extend it (or add a depth file under its `references/<slug>/`) instead of creating a new one. Proceed only when no reference covers the domain, or the user confirms after seeing the overlap.

Read `docs/PHILOSOPHY.md` before proceeding — the philosophy governs operator context structure, progressive disclosure, positive framing, and tool restrictions. Components that violate it will fail CI.

---

## Phase 2 — DESIGN

Decide the reference's home and loading contract before writing a single line.

| Decision | Question to answer |
|----------|--------------------|
| Owning skill | Which existing skill's domain does this extend? If none, which new skill (Create Skill mode)? |
| Role type | Reviewer/auditor, code modifier/engineer, or orchestrator method? |
| Worker tools | What a `general-purpose` worker that loads it may use: reviewers→Read/Glob/Grep; engineers→+Edit/Write/Bash; orchestrators→Read/Agent/Bash. State read-only rules in the reference body. |
| Complexity | Low (single-file, read-only), Medium (multi-file, routing), High (full sweeps, orchestration) |
| Signals | 3–6 specific phrases for the skill's Reference Loading Table — not generic verbs |
| Related references | 2–3 sibling references or skills commonly loaded with it; verify each exists on disk |
| Depth files | Domains needing depth — each goes in `references/<slug>/` loaded on demand |
| Signal craft | Intent verb + domain object, 2–3 adjacent terms, one false-positive boundary with redirect |
| Activation cases | 3 should-trigger / 2 should-not-trigger / 2 near-miss phrases drafted now, saved at scaffold time |

Load `references/agent-design-patterns.md` for operator context structure, hook design, routing design, authority/trust framing, and smells-to-rewrite guidance.

Load `references/agent-eval-design.md` when drafting the signals and activation cases — the case classes and worked example live there.

Gate 2: All nine decisions answered before writing reference content.

---

## Phase 3 — SCAFFOLD

**File layout:**

```
skills/<category>/<skill>/
├── SKILL.md                 # add one Reference Loading Table row for the new reference
└── references/
    ├── <slug>.md            # the reference — the contract a worker loads
    └── <slug>/
        └── *.md             # depth, loaded on demand
```

**Writing the reference body:**

1. Role statement: what work it covers and what domain it owns
2. Expertise list: concrete capabilities with specific sub-skills
3. Mandatory pre-action protocol: what to read before acting and why
4. Operator context block: hardcoded behaviors, default behaviors (ON), optional behaviors (OFF)
5. Capabilities and limitations table: CAN / CANNOT, naming the skill or reference that owns out-of-scope requests
6. Reference loading table: `| Signal | Load These Files | Why |` — required when a `references/<slug>/` directory exists
7. Workflow section: phase-by-phase with gates
8. Error handling: cause/solution pairs for common failures
9. Preferred patterns: what good looks like (positive framing)
10. Anti-rationalization table: common rationalizations with required action

**Owning skill row:** add `| <signals> | references/<slug>.md | <why> |` to the skill's Reference Loading Table. A reference no table names is never loaded.

**Positive framing (CI gate):** Every instruction tells the reader what to do. Run the check after writing:

```bash
python3 scripts/validate_positive_instruction_docs.py
```

Exit code 1 means violations. Rewrite flagged instructions in action form before proceeding.

**Progressive disclosure:** The reference stays navigable. Deep material goes in `references/<slug>/`, loaded on demand. If `--check-size` flags the file, extract content to the depth directory first.

Gate 3: Reference written, and the owning skill's loading table names it.

---

## Phase 4 — REGISTER

The router finds the skill, and the skill's loading table finds the reference. Regenerate the skill index when skill frontmatter changed (new skill, new triggers):

```bash
python3 scripts/generate-skill-index.py
```

Gate 4: A new skill appears in `skills/INDEX.json`; a new reference appears in its skill's Reference Loading Table.

---

## Phase 5 — VALIDATE

Run all validation checks before declaring the reference shippable.

```bash
# Loading-table signals, reference sizes, Skill-tool call and dispatch names
python3 scripts/validate-references.py --check-placeholders
python3 scripts/validate-references.py --check-size
python3 scripts/validate-references.py --check-skill-calls

# Positive framing gate (scans all tracked .md files)
python3 scripts/validate_positive_instruction_docs.py
```

Gate 5: All scripts exit 0. No phantom related-reference entries. No positive-framing violations.

**Manual review** (the scripts cannot check these):

- **Signal craft**: read the loading-table signals aloud. Do they state intent, name 2–3 adjacent terms, mark one false-positive boundary? See `references/agent-creator/agent-frontmatter-template.md` Description Craft.
- **Activation cases checked**: mental-pass 3 should-trigger / 2 should-not-trigger / 2 near-miss phrases against the skill's triggers and the loading-table signals. See `references/agent-eval-design.md`.

---

## Error Handling

### Signal conflict with an existing reference
Cause: Two references claim the same loading signal in one skill, or two skills claim the same trigger.
Solution: Run the duplicate detection script in `references/toolkit-governance/routing-table-patterns.md`. Make this reference's signals more specific.

### Reference never loads
Cause: The owning skill's Reference Loading Table has no row for it, or the row's signals miss the user's phrasing.
Solution: Add or sharpen the row. Re-run the activation cases.

### Reference loading table missing from validation
Cause: The reference has a `references/<slug>/` directory but no `| Signal | Load These Files | Why |` table.
Solution: Add a reference loading table with at least one row. See `references/agent-design-patterns.md` for the required format.

### YAML parse error (new skill or overlay agent)
Cause: Unquoted colon in description, or bad indentation in routing block.
Solution: Wrap description in double quotes. Parse the frontmatter with `yaml.safe_load`; the traceback pinpoints the line.

---

## Preferred Patterns

### Role-matched worker tools
State in the reference which tools its worker uses — reviewers read only, engineers write, orchestrators dispatch. Claude Code does not enforce a reference's tool list, so the body carries the read-only rule.

### Signals that match natural speech
Write loading signals as phrases a first-time user would naturally say, not internal system identifiers. "fix a bug in Go" routes better than "golang-debugging-invocation".

### Reference loading table as required section
Every reference with a depth directory includes a loading table mapping signals to files. References without this table load depth eagerly, violating the progressive disclosure principle from `docs/PHILOSOPHY.md`.

### Expertise list over motivational framing
List concrete capabilities: version-specific idiom tables, failure mode catalogs, concrete commands. Skip "you are an expert in X" — it adds no information the model will act on.

---

## Private overlay agent (owner request only)

Use this path only when the owner asks for an agent file. Overlay agents never ship in the repo index.

1. **Discover.** `ls private-agents/` and `python3 -c "import json; print(list(json.load(open('agents/INDEX.local.json'))['agents']))"` to check overlap.
2. **Design.** Answer the Phase 2 decisions, with `allowed-tools` in frontmatter and `pairs_with` naming skills that exist on disk.
3. **Scaffold.** Load `references/agent-creator/agent-frontmatter-template.md` for the complete template. Layout:

   ```
   private-agents/
   ├── {agent-name}.md          # operator file — the system prompt contract
   └── {agent-name}/
       ├── references/
       │   └── *.md             # deep context, loaded on demand
       └── SPEC.md              # optional: contract for complex/high-impact agents
   ```

   If the file exceeds 600 lines, extract content to `references/` first.
4. **Register.** `python3 scripts/generate-agent-index.py --include-private` writes `agents/INDEX.local.json`. Gate: the index contains the new agent; the router cannot discover unregistered agents.
5. **Validate.**

   ```bash
   python3 scripts/validate-references.py --agent {agent-name} --agents-dir private-agents
   python3 scripts/validate_positive_instruction_docs.py
   python3 -c "import yaml; yaml.safe_load(open('private-agents/{agent-name}.md').read().split('---')[1]); print('YAML OK')"
   ```

   Verify each `pairs_with` entry exists on disk, and that the agent is not at `agents/{name}.md` in a tracked path. If the agent does not appear in routing after regeneration, confirm `routing.triggers` is a non-empty list.

---

## Reference Loading Table

| Signal | Load These Files | Why |
|--------|-----------------|-----|
| operator context structure, reference loading table format, phase/gate pattern, hook design, routing design, authority/trust framing, smells to rewrite | `references/agent-design-patterns.md` | Vexjoy-specific architecture patterns, instruction hierarchy, and rewrite catalog for vague framing |
| overlay agent frontmatter fields, YAML template, complexity tiers, INDEX.local.json registration, description craft | `references/agent-frontmatter-template.md` | Complete annotated template with all required fields, valid values, and description-writing guide |
| activation eval, output eval, should-trigger / should-not-trigger / near-miss, routing failure, signal tuning | `references/agent-eval-design.md` | How to design activation and output evals at scaffold time so the right reference gets loaded and produces correct work |
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