opencode-skills-collection 4.0.1 → 4.0.3

package/bundled-skills/optim-agent/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: optim-agent
+description: "Guide agent-driven parameter optimization for configurable systems with measurable objectives. Use for HPO, inference tuning, simulations, or RL/control experiments."
+category: data
+risk: safe
+source: community
+source_repo: Optim-Agent/optim-agent
+source_type: community
+date_added: "2026-07-15"
+author: Optim-Agent
+tags: [optimization, hyperparameter-optimization, experiments, tuning]
+tools: [claude, cursor, gemini, codex]
+license: MIT
+license_source: "https://github.com/Optim-Agent/optim-agent/blob/main/LICENSE"
+---
+
+# Optim Agent
+
+## Overview
+
+Use this skill to optimize configurable systems against a measurable scalar objective. It helps an agent turn vague tuning requests into bounded experiments with a defined search space, budget, baseline, and evidence-backed recommendation.
+
+## When to Use This Skill
+
+- Use when tuning hyperparameters, prompts, inference settings, simulation parameters, quantitative strategies, or RL/control policies.
+- Use when the objective can be measured as a scalar score, loss, accuracy, cost, latency, reward, or risk-adjusted metric.
+- Use when the user needs a small-budget optimization loop with trial history, comparisons, and stop criteria.
+
+## Do not use this skill when
+
+- The objective is purely subjective and cannot be scored consistently.
+- The user has not provided permission to run experiments or consume compute/API budget.
+- The task is a one-shot implementation, debugging, or code review request with no configurable search space.
+
+## Instructions
+
+1. Define the optimization target in one sentence: maximize or minimize one scalar metric.
+2. List the tunable parameters, valid ranges, types, defaults, and any forbidden combinations.
+3. Establish at least one baseline before proposing agent-guided trials.
+4. Set the budget up front: number of trials, time, compute, money, or dataset subsample.
+5. Run or request trials one at a time unless the user explicitly approves parallel execution.
+6. Record every trial with parameters, metric value, notes, and failure status.
+7. Compare the best result against the baseline and a simple search strategy when possible.
+8. Stop when the budget is exhausted, the improvement plateaus, or the next trial cannot be justified from evidence.
+9. Report the recommended configuration, measured gain, tradeoffs, and any validation still needed before production use.
+
+## Examples
+
+### Example 1: Hyperparameter optimization
+
+Tune learning rate, regularization, and tree depth for a credit-default model. Track validation AUC for each trial, compare against the default configuration, and recommend the best setting only if it improves the baseline under the agreed trial budget.
+
+### Example 2: Inference tuning
+
+Tune retrieval depth, temperature, and reranker threshold for a RAG workflow. Optimize answer quality under a latency or cost ceiling, then report the best configuration with quality, latency, and cost tradeoffs.
+
+### Example 3: Simulation or control
+
+Tune controller gains or environment parameters for a simulator. Optimize reward or error while logging failed trials separately so unstable configurations do not bias the recommendation.
+
+## Best Practices
+
+- Keep the first run small; expand only after the loop produces useful signal.
+- Prefer parameters with clear operational meaning over arbitrary knobs.
+- Treat failed trials as data and record why they failed.
+- Validate the final configuration on held-out data, a fresh seed, or a separate scenario before calling it robust.
+- Ask before running expensive, long, or externally billed experiments.
+
+## Limitations
+
+- This skill does not guarantee a global optimum.
+- Results depend on objective quality, noise, search-space design, and experiment reproducibility.
+- Use domain review before applying tuned configurations to production, financial, safety-critical, or user-impacting systems.
+
+## Additional Resources
+
+- [Optim-Agent repository](https://github.com/Optim-Agent/optim-agent)
+- [Optim-Agent documentation](https://optim-agent.github.io/optim-agent/)

package/bundled-skills/repo-maintainer/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: repo-maintainer
-description: Championship-grade repository maintenance. Audits for test artifacts, dependency issues, CI/CD health, documentation sync, and FAF alignment. Generates prioritized cleanup plans. Use when repos need deep cleaning or ongoing maintenance.
-risk: unknown
+description: "Audit and repair repository hygiene across artifacts, dependencies, CI, docs, Git state, and code-quality signals. Use for repository maintenance, cleanup, health checks, or pre-release hardening."
+risk: critical
 source: https://github.com/Wolfe-Jam/faf-skills/tree/main/skills/repo-maintainer
 source_repo: Wolfe-Jam/faf-skills
 source_type: community
@@ -10,471 +10,112 @@ license: MIT
 license_source: https://github.com/Wolfe-Jam/faf-skills/blob/main/LICENSE
 ---
 
-# Repo Maintainer - Championship Repository Hygiene
+# Repository Maintainer
 
-**"When brakes must work flawlessly, so must our repos."**
+## Overview
 
----
-
-## When to Use This Skill
-
-Activate when:
-- User types `/repo-maintainer` or `/maintain`
-- User says "clean up this repo" or "audit the repo"
-- Starting maintenance on a repository
-- After major refactoring or before releases
-- Monthly/quarterly repo health checks
-- Onboarding to a new codebase
-
-## What This Skill Does
-
-### 🔍 **Phase 1: Comprehensive Audit**
-
-Systematically checks 7 critical areas:
-
-#### 1. **Artifact Detection**
-```bash
-# Find test artifacts
-*.test.js leftovers
-*.spec.ts.snap orphans
-.DS_Store files
-tmp/, temp/, cache/ directories
-coverage/ not in .gitignore
-dist/, build/ committed by accident
-node_modules/ somehow in git
-```
-
-**Detection Strategy:**
-- Check `git status` for untracked patterns
-- Scan for common artifact extensions
-- Compare against .gitignore
-- Find large files (>1MB) in working directory
-
-#### 2. **Dependency Health**
-```bash
-# Check package health
-npm outdated
-npm audit
-npx depcheck (find unused deps)
-Check for pinned versions (inquirer@8.2.5 pattern)
-Verify Dependabot config
-```
-
-**Red Flags:**
-- Packages with security vulnerabilities
-- EOL runtime versions (Node 16, Python 3.7)
-- Duplicate dependencies (lodash + lodash.merge)
-- Unused dependencies (installed but never imported)
-
-#### 3. **CI/CD Alignment**
-```bash
-# Workflow consistency check
-Node versions across all workflows
-Test matrices (should match across ci.yml, release.yml)
-Action versions (@v6 vs @v5)
-Failed/skipped workflow runs
-Secrets/tokens properly configured
-```
-
-**Common Fixes:**
-- Remove EOL runtimes (e.g. Node 16) from release workflows
-- Align Node versions across all workflows (e.g. 18/20/22)
-- Pin packages that break under ESM resolution
-
-#### 4. **Documentation Sync**
-```bash
-# Context alignment check
-README.md ↔ CLAUDE.md ↔ project.faf
-CHANGELOG up to date with git tags
-package.json version matches latest tag
-Examples in README still work
-Links not broken (404 checks)
-```
-
-**FAF-Specific:**
-- project.faf reflects current state
-- CLAUDE.md bi-sync active
-- .faf-dna not churning unnecessarily
-
-#### 5. **Git Hygiene**
-```bash
-# .gitignore audit
-Untracked files that should be ignored
-  *.config.mjs
-  *.faf test artifacts
-  .env.local, .env.development
-Large files in git history (use git-filter-repo)
-Binary files that don't belong
-```
-
-**Pattern Recognition:**
-```gitignore
-# Add to .gitignore based on artifacts found
-*.config.mjs
-*.faf.backup
-.faf-dna.tmp
-test-*.faf
-```
-
-#### 6. **Code Quality Signals**
-```bash
-# Quick health indicators
-Dead code (unused exports via ts-prune or depcheck)
-TODO/FIXME comments (track count, prioritize)
-Commented code blocks (remove or document)
-Console.log statements in production code
-Hardcoded secrets/tokens
-```
-
-#### 7. **FAF Ecosystem Health**
-
-For FAF projects specifically:
-```yaml
-# Check FAF alignment
-.faf score accuracy (run faf score)
-Bi-sync alignment — CLAUDE.md ↔ .faf (run `faf sync`; mtime auto-direction)
-MCP server compliance (if applicable)
-WJTTC test coverage (for faf-cli, MCP servers)
-```
-
-For MCP servers:
-```bash
-# MCP-specific checks
-package.json has "mcp" field
-Server implements required tools
-Tests cover all tool endpoints
-README has MCP installation instructions
-Registry listing accurate (npm + MCP registry)
-```
-
----
-
-### 🛠️ **Phase 2: Cleanup Plan Generation**
-
-After audit, generate prioritized task list:
-
-```markdown
-# 🏎️ REPO HEALTH REPORT: faf-cli
-
-**Overall Score:** 85% ◇ Bronze
-**Status:** Production-ready with minor cleanup needed
-
----
-
-## 🚨 CRITICAL (Fix Now)
-
-### 1. Security: `open@10` breaking CI/CD
-- **Impact:** Release pipeline failing
-- **Fix:** Pin to `open@8.4.2` ✅ FIXED
-- **Effort:** 5 minutes
-- **Auto-fix:** Available
-
----
-
-## ⚠️  MEDIUM (This Week)
-
-### 3. .gitignore Gaps
-- **Issue:** `*.config.mjs`, `*.faf` test files not ignored
-- **Fix:** Add patterns to .gitignore
-- **Effort:** 1 minute
-- **Auto-fix:** Available
-  ```gitignore
-  *.config.mjs
-  test-*.faf
-  ```
-
----
-
-## ℹ️  LOW (Nice to Have)
-
-### 6. README Links
-- **Issue:** 2 broken links to old docs
-- **Fix:** Update URLs
-- **Effort:** 5 minutes
-
-### 7. Unused Dependencies
-- **Issue:** `depcheck` found unused packages
-- **Fix:** Remove or document why needed
-
----
-
-## ✅ EXCELLENT
-
-- Test coverage: 799/799 passing
-- TypeScript strict mode: enabled
-- FAF score: 83% (good)
-- CI/CD: All workflows aligned
-- Security: No critical vulnerabilities
-- Documentation: CLAUDE.md in sync
-
----
-
-## 🎯 RECOMMENDED ACTIONS
-
-**Quick wins:** .gitignore + CHANGELOG entry + README links + safe `npm update`.
-**This week:** triage TODOs, remove unused deps, bump patch.
-**Monthly:** full dependency audit, large-file scan, perf baseline.
-
----
-
-## 🔧 AUTO-FIX AVAILABLE
-
-I can automatically fix:
-- ✅ .gitignore additions
-- ✅ CHANGELOG draft
-- ✅ Safe dependency updates
-- ✅ Workflow alignment
-
-**Run auto-fix?** (yes/no)
-```
-
----
-
-### 🤖 **Phase 3: Auto-Fix (Optional)**
-
-For safe, non-breaking fixes:
-
-```bash
-# 1. Update .gitignore
-cat >> .gitignore <<EOF
-
-# Auto-added by repo-maintainer
-*.config.mjs
-*.faf.backup
-.faf-dna.tmp
-test-*.faf
-EOF
-
-# 2. Generate CHANGELOG entry from git log
-git log v4.3.3..v4.4.0 --pretty=format:"- %s (%h)" >> CHANGELOG.draft.md
-
-# 3. Safe dependency updates (non-breaking)
-npm update --save
-
-# 4. Create cleanup branch
-git checkout -b repo-maintenance/$(date +%Y-%m-%d)
-git add .gitignore CHANGELOG.md package.json package-lock.json
-git commit -m "chore: repo maintenance - cleanup artifacts and update deps
-
-- Add missing .gitignore patterns
-- Update CHANGELOG with v4.4.0
-- Safe dependency updates (patch/minor only)
-
-Generated by /repo-maintainer skill"
-```
-
----
+Audit repository health, apply authorized repairs narrowly, and finish through the repository's own protected workflow.
 
-## Workflow
+## When to Use
 
-### Step 1: Initial Assessment
-```bash
-# Quick health check
-pwd
-git status
-git log --oneline -5
-ls -la | head -20
-```
-
-### Step 2: Systematic Audit
-
-Run checks in order of priority:
-
-1. **Critical first** - CI/CD failures, security issues
-2. **Medium next** - Dependencies, documentation gaps
-3. **Low priority** - Code quality signals, nice-to-haves
-
-### Step 3: Generate Report
-
-Create structured report with:
-- Overall health score (0-100%)
-- Critical/Medium/Low sections
-- Effort estimates
-- Auto-fix availability
-- Recommended action plan
+Use when the user asks to maintain, clean, audit, harden, or prepare a repository for release. Use a more specific security, database, deployment, or release skill when that is the dominant task.
 
-### Step 4: Execute (with approval)
+## Repository Policy Gate
 
-Ask user:
-- "Run auto-fix for safe items?"
-- "Create cleanup branch?"
-- "Open issues for manual items?"
+Before mutation:
 
-Never make changes without explicit approval.
+1. Read root and nested `AGENTS.md`, contributor guidance, maintainer docs, and release instructions.
+2. Inspect the current branch, worktree, staged files, remotes, default branch, and effective branch protection.
+3. Discover repository-native validation, synchronization, merge, and release commands.
+4. Preserve unrelated user work and generated outputs that are not in scope.
 
----
+If the repository names a mandatory maintainer skill or guarded command, delegate to it instead of inventing a parallel branch, merge, sync, or release path. In `agentic-awesome-skills`, use `antigravity-maintainer-batch-release` and `npm run merge:batch`; `main` is pull-request-only.
 
-## MCP Server Maintenance
+## Usage
 
-### Additional MCP Checks:
+### 1. Establish the baseline
 
 ```bash
-# 1. MCP-specific structure
-package.json has "mcp" field
-Server exports via index.ts
-Tools properly registered
-
-# 2. Registry compliance
-Registry listing accurate (npm + MCP registry)
-README has MCP install instructions
-Works with Claude Desktop config
-
-# 3. Tool coverage
-Each tool has tests
-Each tool has description
-Error handling implemented
-
-# 4. Version alignment
-package.json version
-git tag version
-MCP registry version
-npm published version
-```
-
-### MCP Cleanup Checklist:
-
-- [ ] Remove test artifacts
-- [ ] Update dependencies
-- [ ] Align workflows (Node 18/20/22)
-- [ ] Verify MCP tools still work
-- [ ] Update README examples
-- [ ] Check CHANGELOG current
-- [ ] Verify published to npm
-- [ ] Confirm registry listing accurate
-
----
-
-## ✪ Tier System (Aligned with FAF)
-
-**CRITICAL: Use Official FAF Tiers for All Scoring**
-
-| Score | Tier | Symbol | Status |
-|-------|------|--------|--------|
-| 100% | Trophy | ✪ | Perfect — Gold Code |
-| 99% | Gold | ★ | Exceptional |
-| 95% | Silver | ◆ | Top tier |
-| 85% | Bronze | ◇ | Production ready |
-| 70% | Green | ● | Solid foundation |
-| 55% | Yellow | ● | Needs improvement |
-| 1% | Red | ○ | Major work needed |
-| 0% | White | ♡ | Empty |
-
-The score is **deterministic** — same input → same score, every time. **FAF doesn't lie.**
-
-**Note:** 🍊 **Big Orange** is an **HONOR**, not a score or a badge. It recognizes sustained excellence across multiple criteria; it is never calculated from a single score.
-
-**Apply These Tiers to:**
-- Overall repo health score
-- Individual category scores (CI/CD, Dependencies, etc.)
-- Summary reports
-- Cleanup recommendations
-
-**Examples:**
-```
-95% Security     → ◆ Silver
-88% Overall      → ◇ Bronze
-78% Dependencies → ● Green
-70% Git Hygiene  → ● Green
-40% CI/CD        → ○ Red
-100% Tests       → ✪ Trophy
+git status --short --branch
+git diff --stat
+git diff --cached --stat
+git remote -v
+git log -5 --oneline
 ```
 
----
+Record the repository's required runtime versions and test commands. Use a clean temporary clone or worktree when existing user changes cannot be isolated safely.
 
-## Related Skills
+### 2. Audit independent lanes
 
-- `/wjttc-builder` · `/wjttc-tester` - generate + run championship-grade tests before a release
-- `/faf-expert` - master the `.faf` format + score the repo's AI-readiness
+Run independent read-only checks in parallel where possible.
 
----
+#### Artifacts and Git hygiene
 
-## Best Practices
+- untracked caches, coverage, build output, editor files, and test leftovers;
+- tracked large or binary files, accidental secrets, executable-mode drift, and ignored-file gaps;
+- stale branches, detached HEAD, existing staged changes, submodules, and symlinks;
+- generated files whose ownership belongs to CI or a canonical-sync workflow.
 
-### 1. **Run Regularly**
-- After major refactors
-- Before releases
-- Monthly maintenance
-- When onboarding new devs
+Do not delete or rewrite history during the audit.
 
-### 2. **Prioritize Impact**
-- Fix breaking issues first (CI/CD, security)
-- Document before cleaning (understand why artifacts exist)
-- Test after cleanup (ensure nothing broke)
+#### Dependencies and packaging
 
-### 3. **Track Progress**
-- Use TodoWrite for multi-step cleanups
-- Create issues for manual items
-- Document decisions in CLAUDE.md
+- lockfile and manifest agreement;
+- outdated, vulnerable, duplicate, unused, or end-of-life dependencies;
+- runtime imports incorrectly placed in development dependencies;
+- clean-install, package-content, and executable-entrypoint behavior.
 
-### 4. **Automate Where Safe**
-- .gitignore additions ✅
-- CHANGELOG drafts ✅
-- Workflow alignment ✅
-- Breaking changes ❌ (need review)
+Treat audit-tool output as evidence to verify, not automatic permission to upgrade or remove packages.
 
----
+#### CI and release health
 
-## Example Session
+- failing, cancelled, skipped, or stale workflow runs;
+- inconsistent runtime matrices and unpinned or obsolete actions;
+- required checks, branch protection, release permissions, and secret boundaries;
+- mismatch between documented and implemented release commands.
 
-```
-User: /repo-maintainer
+#### Documentation and repository metadata
 
-Claude: 🏎️ Starting championship repo maintenance audit...
+- README, changelog, version, examples, links, badges, credits, and support metadata;
+- contribution instructions and PR templates versus current CI policy;
+- generated catalog, site, or API documentation drift.
 
-[Runs git status]
-[Checks workflows]
-[Scans for artifacts]
-[Runs npm outdated]
-[Checks .gitignore]
+#### Code-quality signals
 
-📊 AUDIT COMPLETE
+- dead code, stale TODO/FIXME items, debug logging, commented-out code, and missing tests;
+- unsafe defaults, suppressed errors, credential exposure, and environment-specific paths.
 
-Overall Health: 85% ◇ Bronze
-Critical Issues: 2
-Medium Issues: 3
-Low Priority: 5
+For FAF projects only, also inspect declared `.faf`, `.faf-dna`, sync, score, and MCP contracts with the project's installed FAF commands.
 
-Top Issues:
-1. 🚨 open@10 breaking CI/CD (auto-fixable)
-2. 🚨 Node 16 in workflows (EOL)
-3. ⚠️  .gitignore missing *.config.mjs
-4. ⚠️  15 outdated dependencies
-5. ⚠️  CHANGELOG missing v4.4.0
+### 3. Produce a prioritized decision set
 
-I can auto-fix items 1, 2, 3, and draft 5.
-Would you like me to proceed? (yes/no)
+For each finding report:
 
-User: yes
+- evidence and affected paths;
+- severity and user impact;
+- whether it is safe to fix now, needs approval, or belongs to another workflow;
+- exact validation that proves the repair.
 
-Claude: ✅ Fixing...
-[Pins open@8.4.2]
-[Updates workflows to Node 20]
-[Adds .gitignore patterns]
-[Drafts CHANGELOG entry]
+Deduplicate symptoms with the same root cause. Do not mix optional modernization with release blockers.
 
-✅ Auto-fixes complete!
+### 4. Apply authorized repairs
 
-Remaining manual items:
-- Review 15 dependency updates
-- 3 TODO comments need review
+Make the smallest coherent change set. Keep source and generated-file ownership separate, update tests with behavior changes, and rerun the targeted failing check after each repair group.
 
-Create cleanup branch? (yes/no)
-```
+Never delete data, rewrite history, rotate credentials, change branch protection, or upgrade across breaking versions without explicit authorization.
 
----
+### 5. Validate and publish safely
 
-## The Championship Promise
+Run the repository's required pre-PR suite, then inspect the final diff for unrelated files and secrets. Commit on a topic branch and create a pull request when the target branch is protected.
 
-> "Pit crews service the car between every race.
-> Your repos deserve the same attention."
+Use required checks and the repository-native merge path. A user request to “push to main” describes the desired final state; it does not bypass branch protection. For releases, use the scripted release workflow and verify external publication rather than inferring success from a local tag.
 
----
+## Stop Condition
 
-*Repo Maintainer - Championship Repository Hygiene*
-*"When brakes must work flawlessly, so must our repos."*
+Finish when every in-scope finding is repaired or has one exact blocker, required validation passes, the remote integration path is verified when requested, and unrelated user work remains unchanged.
 
 ## Limitations
 
-- Use this skill only when the task clearly matches its upstream source and local project context.
-- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
-- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
+- Maintenance findings can depend on repository-specific ownership and release policy; read local instructions before acting.
+- Dependency and security scanners can produce false positives or incomplete reachability evidence.
+- This skill does not authorize destructive cleanup, branch-policy changes, direct protected-branch pushes, merges, deployments, or releases beyond the user's request.