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/github-profile-rules/github-api-patterns.md

View on GitHub
# GitHub REST API Patterns Reference

> **Scope**: Efficient API usage for code analysis — repos, trees, content, PR reviews, rate limiting. Not Actions/webhooks.
> **Version range**: GitHub REST API v3; GraphQL not covered

Rate limits: 60 req/hr unauth, 5000 req/hr auth. Patterns below minimize request count.

## Efficient Analysis Sequence

```
1. GET /users/{username}                    → 1 req — public_repos count
2. GET /users/{username}/repos?sort=stars   → 1-2 req — top repos by activity
3. GET /repos/{owner}/{repo}/git/trees/{sha}?recursive=1  → 1 req per repo — full file tree
4. GET /repos/{owner}/{repo}/contents/{path}  → 1 req per file — file content (base64)
5. GET /repos/{owner}/{repo}/pulls?state=all  → 1-2 req per repo — PR list
6. GET /repos/{owner}/{repo}/pulls/{pr}/reviews  → 1 req per PR — review comments
```

Total for 5 repos × 10 files × 3 PRs each: ~5 + 5 + 50 + 15 = **75 requests**. Well within authenticated limits.

---

## Pattern Table

| Endpoint | Optimal Use | Request Count | Notes |
|----------|-------------|---------------|-------|
| `/users/{username}/repos?sort=stars&per_page=5` | Get top 5 repos by stars | 1 | Add `&type=owner` to exclude forked repos |
| `/repos/{o}/{r}/git/trees/{sha}?recursive=1` | Full file tree in one call | 1 per repo | Truncated above ~100k files — check `truncated` field |
| `/repos/{o}/{r}/contents/{path}` | Single file content (base64) | 1 per file | `content` field is base64 — decode before parsing |
| `/repos/{o}/{r}/pulls?state=closed&per_page=10` | Most recent merged PRs | 1-2 per repo | Use `closed` for historical preference signals |
| `/repos/{o}/{r}/pulls/{n}/reviews` | Review comments per PR | 1 per PR | `body` field has the comment text |
| `/rate_limit` | Check remaining before large batches | 1 | Check before each analysis phase |

---

## Correct Patterns

### Rate Limit Check Before Batch Operations

Always check rate limits before starting a new analysis phase:

```python
def check_rate_limit(headers: dict) -> None:
    """Raise if fewer than 10 requests remaining."""
    remaining = int(headers.get("X-RateLimit-Remaining", 0))
    reset_time = int(headers.get("X-RateLimit-Reset", 0))

    if remaining < 10:
        wait_seconds = reset_time - time.time()
        raise RateLimitError(
            f"Rate limit nearly exhausted ({remaining} remaining). "
            f"Resets in {wait_seconds:.0f}s. "
            "Provide a GitHub token for 5000 req/hr: --token <your_token>"
        )
```

---

### Fetch File Tree (Recursive, One Request)

```python
def get_file_tree(owner: str, repo: str, branch: str = "HEAD") -> list[str]:
    """Return all file paths in a repo using one API call."""
    # First get the commit SHA for branch
    resp = github_get(f"/repos/{owner}/{repo}/commits/{branch}")
    tree_sha = resp["commit"]["tree"]["sha"]

    # Fetch entire tree recursively
    resp = github_get(f"/repos/{owner}/{repo}/git/trees/{tree_sha}?recursive=1")

    if resp.get("truncated"):
        # Repo has >100k files — fall back to directory-by-directory
        return get_file_tree_paged(owner, repo, tree_sha)

    return [item["path"] for item in resp["tree"] if item["type"] == "blob"]
```

One request vs N+1 recursive directory calls. 500-file repo saves 30+ requests.

---

### Decode File Content

```python
import base64

def get_file_content(owner: str, repo: str, path: str) -> str:
    """Fetch and decode file content from GitHub API."""
    resp = github_get(f"/repos/{owner}/{repo}/contents/{path}")

    if resp.get("encoding") != "base64":
        raise ValueError(f"Unexpected encoding: {resp.get('encoding')}")

    # Content has newlines inserted by GitHub — strip before decoding
    return base64.b64decode(resp["content"].replace("\n", "")).decode("utf-8", errors="replace")
```

GitHub `content` includes `\n` that must be stripped before base64 decode.

---

### Prioritize Top Repos

```python
def get_analysis_repos(username: str, max_repos: int = 5) -> list[dict]:
    """Return repos sorted by relevance: stars + recent activity, excluding forks."""
    repos = github_get(f"/users/{username}/repos?sort=pushed&per_page=20&type=owner")

    # Sort by stars (strongest signal), filter forks (project-specific style)
    owned = [r for r in repos if not r["fork"]]
    owned.sort(key=lambda r: r["stargazers_count"], reverse=True)

    return owned[:max_repos]
```

Forks contain upstream style, not user's. Star-sorted owned repos = most polished work.

---

## Pattern Catalog

### Use Recursive Tree Endpoint for File Listing
**Detection** (in your own code pattern):
```bash
grep -rn 'GET /repos.*contents' scripts/ | grep -v 'tree'
```

**Signal**:
```python
# Expensive: 1 request per directory level, recursive
def list_files(owner, repo, path=""):
    items = github_get(f"/repos/{owner}/{repo}/contents/{path}")
    for item in items:
        if item["type"] == "dir":
            yield from list_files(owner, repo, item["path"])  # N+1 requests!
        else:
            yield item["path"]
```

**Why**: 200-file repo = 21 requests. Recursive tree = 1.

**Fix**: `GET /repos/{owner}/{repo}/git/trees/{sha}?recursive=1`

---

### Handle Pagination for All List Endpoints
**Detection**:
```bash
grep -rn 'per_page' scripts/ | grep -v 'pagination\|next\|link'
```

**Signal**:
```python
repos = github_get(f"/users/{username}/repos?per_page=100")
# Assumes all repos fit in one page — fails for users with 100+ repos
```

**Why**: Max 100 items/page. 100+ repos = silently incomplete.

**Fix**:
```python
def paginate(url: str) -> list:
    results = []
    while url:
        resp = requests.get(url, headers=auth_headers)
        results.extend(resp.json())
        # GitHub uses Link header for pagination
        url = resp.links.get("next", {}).get("url")
    return results
```

---

### Authenticate All API Requests
**Detection**:
```bash
grep -rn 'github_get\|requests.get' scripts/ | grep -v 'Authorization\|token'
```

**Signal**:
```python
headers = {"Accept": "application/vnd.github.v3+json"}
# Missing: Authorization header — capped at 60 req/hr
```

**Why**: 60 req/hr exhausted by 2-3 repos. Analysis needs 50-200 minimum.

**Fix**: Accept `--token` flag; check `GITHUB_TOKEN` env var:
```python
import os
token = args.token or os.environ.get("GITHUB_TOKEN")
headers = {
    "Accept": "application/vnd.github.v3+json",
    **({"Authorization": f"token {token}"} if token else {})
}
```

---

## Error-Fix Mappings

| Error Message / HTTP Status | Root Cause | Fix |
|----------------------------|------------|-----|
| `403 API rate limit exceeded` | Rate limit hit (60/hr unauth, 5000/hr auth) | Provide `--token` or wait for reset (`X-RateLimit-Reset` header) |
| `404 Not Found` on `/users/{u}` | Invalid username | Verify spelling; user may have changed username |
| `404 Not Found` on `/repos/{o}/{r}/contents/{p}` | File doesn't exist on default branch | Check branch name; file may have been deleted |
| `422 Repository is empty` | New repo with no commits | Skip repo; no content to analyze |
| `binascii.Error: Invalid base64` | Not stripping `\n` from content field before decode | `base64.b64decode(content.replace("\n", ""))` |
| `403 Resource not accessible by integration` | Requesting private data without correct token scope | Only request public endpoints; verify token scopes |
| `451 Repository access blocked` | DMCA or legal takedown | Skip repo; log and continue |

---

## Detection Commands Reference

```bash
# Check current rate limit status
curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/rate_limit | jq '.rate'

# Verify a username exists
curl -s "https://api.github.com/users/{username}" | jq '.login,.public_repos'

# Get top 5 repos by stars
curl -s "https://api.github.com/users/{username}/repos?sort=stars&per_page=5&type=owner" \
  | jq '.[].name'

# Get file tree for a repo (requires auth for large repos)
curl -s -H "Authorization: token $GITHUB_TOKEN" \
  "https://api.github.com/repos/{owner}/{repo}/git/trees/HEAD?recursive=1" \
  | jq '.tree[].path' | grep -E '\.(go|py|ts|js)$' | head -20
```

---

## See Also

- `rule-categories.md` — taxonomy of extractable rule types with confidence scoring
- `confidence-scoring.md` — detailed scoring algorithm and edge cases
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: 470kUpdated 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