@laitszkin/apollo-toolkit 2.11.3 → 2.12.0

package/AGENTS.md

@@ -29,6 +29,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can propose product features from an existing codebase and publish accepted proposals.
 - Users can discover reproducible edge-case risks and report prioritized hardening gaps.
 - Users can read, filter, and inspect remote GitHub issues before planning follow-up work.
+- Users can resolve a GitHub issue end-to-end and push the fix directly to a requested branch without opening a PR.
 - Users can run evidence-first application security audits focused on confirmed vulnerabilities.
 - Users can learn new or improved skills from recent Codex conversation history.
 - Users can audit and maintain the skill catalog itself, including dependency classification and shared-skill extraction decisions.
@@ -40,6 +41,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can prepare and open open-source pull requests from existing changes.
 - Users can generate storyboard image sets from chapters, novels, articles, or scripts.
 - Users can configure OpenClaw from official documentation, including `~/.openclaw/openclaw.json`, skills loading, SecretRefs, CLI edits, and validation or repair workflows.
+- Users can investigate production or local simulation runs, calibrate reusable presets, and fix toolchain realism gaps between harness behavior and expected on-chain behavior.
 - Users can record multi-account spending and balance changes in monthly Excel ledgers with summary analytics and charts.
 - Users can review the current git change set from an unbiased reviewer perspective to find abstraction opportunities and simplification candidates.
 - Users can process GitHub pull request review comments and resolve addressed threads.

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.12.0] - 2026-03-28
+
+### Added
+- Add `agents` mode to install scripts for copying skills into `~/.agents/skills` directory, supporting agent-skill-compatible software.
+
+### Changed
+- Strengthen `production-sim-debug` so simulation investigations must verify protocol-sensitive blame against official docs or upstream source, distinguish liquidation pipeline stages precisely, and explain quote-budget counts as attempts versus unique opportunities.
+
+## [v2.11.4] - 2026-03-27
+
+### Added
+- Add `production-sim-debug` for investigating production or local simulation runs, separating harness realism gaps from runtime bugs, and validating fixes by rerunning the same bounded scenario.
+- Add `ship-github-issue-fix` for taking a remote GitHub issue through implementation and direct push to a requested branch without opening a PR or performing release work.
+
+### Changed
+- Update `read-github-issue` to prefer bundled issue scripts while falling back to raw `gh issue list` and `gh issue view` commands when repository-specific helpers are missing or fail.
+- Strengthen `commit-and-push` and `version-release` so sequential git mutations must verify the remote branch tip and release tag before reporting success or publishing a release.
+- Refresh repository capability docs and skill inventory to include direct issue-shipping and production simulation debugging workflows.
+
 ## [v2.11.3] - 2026-03-24
 
 ### Added

package/README.md

@@ -35,6 +35,7 @@ A curated skill catalog for Codex, OpenClaw, and Trae with a managed installer t
 - open-source-pr-workflow
 - openai-text-to-image-storyboard
 - openclaw-configuration
+- production-sim-debug
 - record-spending
 - resolve-review-comments
 - review-change-set

package/commit-and-push/SKILL.md

@@ -15,7 +15,7 @@ description: "Guide the agent to submit local changes with commit and push only
 ## Standards
 
 - Evidence: Inspect git state and classify the change set before deciding which quality gates apply.
-- Execution: Run the required quality-gate skills when applicable, convert completed spec sets into categorized project docs during submission, normalize non-standard project docs when needed, preserve staging intent, honor any explicit user-specified target branch, then commit and push without release steps.
+- Execution: Run the required quality-gate skills when applicable, convert completed spec sets into categorized project docs during submission, normalize non-standard project docs when needed, preserve staging intent, honor any explicit user-specified target branch, then commit and push without release steps; run dependent git mutations sequentially and verify the remote branch actually contains the new local `HEAD` before reporting success.
 - Quality: Re-run relevant validation for runtime changes, keep project docs plus agent constraints synchronized before committing, and preserve unrelated local work safely when branch switching or post-push local sync is required; treat `archive-specs` outputs as the canonical project-doc structure when normalization is required.
 - Output: Produce a concise Conventional Commit, push it to the intended branch, and report any temporary stash/restore or local branch sync that was required.
 
@@ -72,6 +72,9 @@ Load only when needed:
    - Write a concise Conventional Commit message using `references/commit-messages.md`.
 9. Push
    - Push commit(s) to the intended branch.
+   - Do not overlap `git commit`, `git push`, branch switching, or post-push sync operations; wait for each mutation to finish before starting the next one.
+   - After pushing, verify the remote branch tip matches the local `HEAD`, for example by comparing `git rev-parse HEAD` with the target branch hash from `git rev-parse @{u}` or `git ls-remote --heads <remote> <branch>`.
+   - If the push result is ambiguous, out of order, or the hashes do not match, rerun the missing git step sequentially and re-check before reporting success.
    - Confirm the local branch state matches the user's requested destination when post-push synchronization was requested.
 
 ## Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "2.11.3",
+  "version": "2.12.0",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",

package/production-sim-debug/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaiTszKin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/production-sim-debug/README.md

@@ -0,0 +1,91 @@
+# Production Sim Debug
+
+An agent skill for investigating production or local simulation runs when the observed behavior diverges from the intended market scenario or expected liquidation/remediation outcomes.
+
+This skill helps agents reproduce a bounded simulation run, inspect the real preset and runtime artifacts, separate product bugs from local harness drift, and apply the smallest realistic fix before rerunning the same scenario.
+
+## What this skill provides
+
+- A workflow for bounded production/local simulation diagnosis.
+- A decision tree for separating runtime logic bugs from harness, stub, preset, and persistence issues.
+- A repeatable way to audit the active run directory, logs, and event database before drawing conclusions.
+- Guidance for turning recurring ad hoc scenarios into named presets and documented test cases.
+- Emphasis on rerunning the same scenario after a fix instead of relying only on unit tests.
+
+## Repository structure
+
+- `SKILL.md`: Main skill definition, workflow, and output contract.
+- `agents/openai.yaml`: Agent interface metadata and default prompt.
+
+## Installation
+
+1. Clone this repository.
+2. Copy this folder to your Codex skills directory:
+
+```bash
+mkdir -p "$CODEX_HOME/skills"
+cp -R production-sim-debug "$CODEX_HOME/skills/production-sim-debug"
+```
+
+## Usage
+
+Invoke the skill in your prompt:
+
+```text
+Use $production-sim-debug to run this repository's production local simulation with the named preset for 5 minutes, explain why remediations or liquidations did not land, and fix any harness or runtime-alignment issues you confirm.
+```
+
+Best results come from including:
+
+- workspace path
+- canonical simulation entrypoint
+- preset or scenario name
+- run duration
+- expected market shape or success criteria
+- the run directory to inspect, if it already exists
+- whether toolchain fixes are in scope or the task is read-only
+
+If the repository already has a named preset system, prefer using it instead of describing the scenario only in prose.
+
+## Example
+
+### Input prompt
+
+```text
+Use $production-sim-debug for this repository.
+
+Workspace: /workspace/pangu
+Entrypoint: ./scripts/run-production-local-sim.sh stress-test-1
+Duration: 5 minutes
+Expectations:
+- Jupiter free tier
+- mostly oracle-blocked positions that can be unlocked by remediation
+- some directly executable opportunities
+- evidence-backed explanation for why liquidations did or did not land
+```
+
+### Expected response shape
+
+```text
+1) Scenario contract
+- Named preset, duration, and run directory used.
+
+2) Observed outcomes
+- Event-table counts, dominant skip reasons, and runtime stage reached.
+
+3) Root cause
+- Whether the main blocker was product logic, quote budget, preset design, or harness/stub drift.
+
+4) Fixes applied
+- Toolchain or runtime fixes with file paths.
+
+5) Validation
+- Rerun or targeted tests proving the intended stage now executes.
+
+6) Remaining gaps
+- Any realism differences still left between local simulation and chain behavior.
+```
+
+## License
+
+MIT. See `LICENSE`.

package/production-sim-debug/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: production-sim-debug
+description: Investigate production or local simulation runs for runtime-toolchain drift, harness bugs, preset mistakes, unrealistic local stubs, or mismatches between expected and observed liquidation outcomes. Use when users ask to run bounded production simulations, explain why simulated liquidations or remediations did not happen, calibrate presets, or fix local simulation tooling so it better matches real on-chain behavior.
+---
+
+# Production Sim Debug
+
+## Dependencies
+
+- Required: `systematic-debug` for evidence-first root-cause analysis when a simulation shows failing or missing expected behavior.
+- Conditional: `scheduled-runtime-health-check` when the user wants a bounded production/local simulation run executed and observed; `read-github-issue` when the requested simulation work is driven by a remote issue; `marginfi-development` when liquidation, health, receivership, or instruction-order conclusions depend on official marginfi docs/source; `jupiter-development` when swap, quote, routing, or rate-limit conclusions depend on official Jupiter docs; `open-github-issue` when confirmed toolchain gaps should be published.
+- Optional: none.
+- Fallback: If the relevant simulation entrypoint, preset, logs, or run artifacts cannot be found, stop and report the missing evidence instead of inferring behavior from stale docs or memory.
+
+## Standards
+
+- Evidence: Base conclusions on the actual preset, runtime command, logs, SQLite event store, local stub responses, and the code paths that generated them.
+- Execution: Reproduce with the exact scenario first, separate product logic failures from simulation-toolchain failures, make the smallest realistic toolchain fix, and rerun the same bounded scenario to validate.
+- Quality: Prefer harness or stub fixes that improve realism over one-off scenario hacks, avoid duplicating existing workflow skills, and record reusable presets when a scenario becomes part of the regular test suite.
+- Output: Return the scenario contract, observed outcomes, root-cause chain, fixes applied, validation evidence, and any remaining realism gaps.
+
+## Goal
+
+Use this skill to debug simulation workflows where the repository exposes a production-like local run path, but the observed outcomes are distorted by presets, harness logic, local stubs, event persistence, or runtime scheduling constraints.
+
+## Workflow
+
+### 1) Lock the simulation contract before touching code
+
+- Identify the exact entrypoint, preset, duration, runtime mode, and rate-limit tier the user expects.
+- Read the preset or scenario definition from the repository before assuming what the test means.
+- Capture the intended success criteria explicitly, such as:
+  - successful liquidation count
+  - remediation count
+  - oracle-block registration
+  - profit ranking behavior
+  - quote budget behavior
+- If the scenario is ad hoc but likely to recur, prefer turning it into a named preset instead of leaving it as an undocumented shell invocation.
+
+### 2) Reproduce with the real bounded run path
+
+- Use the same production/local simulation script the repository already treats as canonical.
+- Prefer a bounded run window with a stable run name and output directory.
+- Save and inspect the exact artifacts produced by that run:
+  - main runtime log
+  - actor or stub logs
+  - generated env/config files
+  - SQLite or other persistence outputs
+  - scenario manifest or preset-resolved settings
+- Do not trust older run directories when the user asks about a new execution.
+
+### 3) Audit the artifact chain before diagnosing product logic
+
+- Confirm that you are reading the correct database and log files for the active run.
+- Verify that the event tables you expect are actually the ones written by the runtime.
+- Check whether missing results come from:
+  - no candidate selection
+  - no worker completion
+  - planner failure
+  - event persistence mismatch
+  - reading the wrong file
+- Treat this artifact audit as mandatory; repeated failures in the recent chats came from toolchain alignment errors before they came from liquidation logic.
+
+### 4) Separate product failures from toolchain realism failures
+
+- When the suspected blocker touches protocol rules, instruction legality, quote semantics, or liquidation invariants, verify the claim against the relevant official docs or upstream source before assigning blame.
+- For every major blocker, explicitly classify the result as one of:
+  - production bot problem
+  - simulation environment problem
+  - both
+- Treat "both" as a first-class result when a bot bug and a local-harness realism gap are stacked in the same flow.
+
+- Classify each blocker into one of these buckets:
+  - preset design mismatch
+  - runtime scheduling or budget behavior
+  - stub or mock response unrealism
+  - local validator or cloned-state setup drift
+  - account ordering / remaining-account mismatch
+  - event-generation or persistence bug
+  - genuine product logic bug
+- If the symptom is caused by the local harness, fix the harness instead of masking it in runtime logic.
+- If a local stub inflates or distorts profitability, preserve the runtime behavior and calibrate the stub.
+- If a scenario intentionally stresses one dimension, make sure the harness is not accidentally stressing unrelated dimensions.
+
+### 4.1) Map the observed failure to the real pipeline stage
+
+- Do not treat every `liquidation_event` row as evidence that the run reached verification or execution.
+- Reconstruct the stage explicitly, such as:
+  - candidate discovery
+  - local estimate
+  - solver candidate quote
+  - verification or pre-submit re-quote
+  - simulation
+  - execution
+- When logs or event rows expose `stage`, `bucket`, `reason`, or similar structured fields, use them to explain exactly where the attempt stopped.
+- When the user is confused by counts, distinguish:
+  - unique positions
+  - candidate attempts
+  - quote attempts
+  - verification attempts
+  - executed liquidations
+
+### 4.2) Audit quote-budget behavior before calling the strategy broken
+
+- Check whether a high quote count reflects many unique positions or repeated coarse/refinement exploration on the same few positions.
+- Trace how the runtime reserves verification capacity versus non-verification capacity, and explain which bucket was exhausted.
+- If the strategy relies on local oracle estimates before quoting, verify whether the admission threshold is merely "positive estimate" or something stricter before assuming those candidates were all strong.
+- When quote pressure appears unreasonable, tie the explanation back to the actual solver-step count, coarse/refinement selection logic, and the number of cross-mint candidates in the run.
+
+### 5) Trace the full decision tree for missed liquidations or remediations
+
+- Follow the candidate from discovery through:
+  - local profitability estimate
+  - health precheck
+  - oracle-block classification
+  - remediation registration and rearm
+  - quote admission
+  - quote calibration
+  - pre-submit verification
+  - final execution or skip reason
+- When the runtime reports a generic or overloaded failure label, reopen the logs and derive a finer-grained breakdown before proposing fixes.
+- Distinguish fail-closed behavior from broken behavior; not all skipped liquidations are bugs.
+
+### 6) Fix the narrowest realistic cause
+
+- Prefer minimal fixes that improve realism or observability at the root cause:
+  - add preset support to shell tooling instead of hardcoding another branch
+  - make oracle-blocked paths avoid external quote I/O when a local estimate is sufficient
+  - make stubs preserve run-specific metadata instead of falling back to unrealistic defaults
+  - keep continuous oracle updates realistic without breaking the runtime's own core feeds
+- Add or update regression tests when the bug is in the harness, runtime decision tree, or event persistence path.
+- If the scenario becomes a durable benchmark, add or update the named preset and the developer docs in the same change.
+
+### 7) Re-run the same scenario and compare outcomes
+
+- After the fix, rerun the same scenario or the shortest bounded version that still exercises the bug.
+- Compare:
+  - event-table counts before and after
+  - dominant skip reasons before and after
+  - whether the runtime reaches the intended decision stage
+  - whether the harness still resembles the user’s requested market conditions
+- Do not claim success based only on unit tests when the original issue was a simulation-toolchain integration problem.
+
+## Common failure patterns
+
+- **Wrong artifact source**: the analyst inspects an older SQLite file or the wrong event database and concludes that runtime behavior is missing.
+- **Preset says one thing, harness does another**: scenario names sound right, but the actual matrix or oracle mode does not match the user’s intent.
+- **Stub realism drift**: local quote, swap, or oracle stubs distort pricing, accounts, or program IDs enough to create false failures or false profits.
+- **Overloaded “unknown” failures**: logs contain structured reasons, but the first-pass analysis never decomposes them.
+- **Continuous-mode self-sabotage**: a stress regime intended to stale pull oracles instead makes the runtime’s own primary feeds unusable.
+- **Quote budget starvation**: local filtering improves behavior but still lets low-value cross-mint candidates consume scarce quote capacity before higher-value paths can finish.
+- **Blame assigned too early**: the first visible error gets labeled as either bot or tooling before official docs, upstream source, and run artifacts confirm that attribution.
+- **Phase confusion**: event counts are interpreted as verification or execution attempts even though the run stopped much earlier in candidate quote or pre-submit simulation.
+- **Quote-count misread**: a large total quote count is mistaken for many distinct opportunities when the runtime actually spent repeated exploration quotes on a smaller set of positions.
+
+## Output checklist
+
+- Name the exact scenario, preset, duration, and run directory.
+- State whether the root cause was product logic, toolchain realism, or both.
+- For protocol-sensitive issues, name the official docs or upstream source used to justify that attribution.
+- Cite the artifact types used: preset, logs, SQLite tables, and code paths.
+- Explain the failing stage in the liquidation pipeline and whether the key counts represent positions, attempts, quotes, or executed outcomes.
+- Summarize the narrow fix and the regression test or rerun evidence.
+- If the final scenario should be reused, state where the preset or docs were added.
+
+## Example invocation
+
+`Use $production-sim-debug to run the repository's production local simulation for 5 minutes with the named preset, explain why liquidations did not land, and fix any local harness or runtime-alignment issues that make the simulation unrealistic.`

package/production-sim-debug/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Production Sim Debug"
+  short_description: "診斷 production/local simulation 工具鏈與結果失真"
+  default_prompt: "Use $production-sim-debug to investigate a production/local simulation run, explain why outcomes diverged, and fix the harness or runtime alignment if needed."

package/read-github-issue/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: read-github-issue
-description: Read and search remote GitHub issues via GitHub CLI (`gh`). Use when users ask to list issues, filter issue candidates, inspect a specific issue with comments, or gather issue context before planning follow-up work.
+description: Read and search remote GitHub issues via GitHub CLI (`gh`). Use when users ask to list issues, filter issue candidates, inspect a specific issue with comments, or gather issue context before planning follow-up work. Prefer the bundled scripts when they are present and working, but fall back to direct `gh issue list` / `gh issue view` commands when the scripts are missing or fail for repository-specific reasons.
 ---
 
 # Read GitHub Issue
@@ -10,12 +10,12 @@ description: Read and search remote GitHub issues via GitHub CLI (`gh`). Use whe
 - Required: none.
 - Conditional: none.
 - Optional: none.
-- Fallback: If `gh` is unavailable or unauthenticated, stop and report the exact blocked command instead of guessing repository state.
+- Fallback: If the bundled scripts are missing or fail but `gh` is available, continue with raw `gh issue list` / `gh issue view`; only stop when `gh` itself is unavailable or unauthenticated.
 
 ## Standards
 
 - Evidence: Verify repository context first, then read remote issue data directly from `gh issue list` / `gh issue view` instead of paraphrasing from memory.
-- Execution: Confirm the target repo, find candidate issues with the bundled script, then inspect the chosen issue with comments and structured fields.
+- Execution: Confirm the target repo, prefer the bundled scripts for deterministic output, then fall back to raw `gh` commands whenever the scripts are unavailable or broken in the target repository.
 - Quality: Keep the skill focused on issue discovery and retrieval only; do not embed any hardcoded fixing, branching, PR, or push workflow.
 - Output: Return candidate issues, selected issue details, comments summary, and any missing information needed before follow-up work.
 
@@ -47,6 +47,13 @@ python3 scripts/find_issues.py --limit 50 --state open
   - `--repo owner/name`
   - `--label bug`
   - `--search "panic in parser"`
+- Raw `gh` fallback when the script is missing or broken:
+
+```bash
+gh issue list --limit 50 --state open
+```
+
+- Add `--repo <owner>/<repo>`, `--label <label>`, or `--search "<text>"` as needed.
 - If the issue target is still unclear, present top candidates and ask which issue number or URL should be inspected next.
 
 ### 3) Read a specific issue in detail
@@ -61,6 +68,13 @@ python3 scripts/read_issue.py 123 --comments
   - `--repo owner/name`
   - `--json`
   - `--comments`
+- Raw `gh` fallback when the script is missing or broken:
+
+```bash
+gh issue view 123 --comments
+```
+
+- Use `--repo <owner>/<repo>` when targeting a different repository.
 - Use the returned title, body, labels, assignees, state, timestamps, and comments to summarize the issue precisely.
 
 ### 4) Summarize gaps before any follow-up action
@@ -75,9 +89,11 @@ python3 scripts/read_issue.py 123 --comments
 - Purpose: consistent remote issue listing via `gh issue list`.
 - Outputs a readable table by default, or JSON with `--output json`.
 - Uses only GitHub CLI so it reflects remote GitHub state.
+- Treat it as a convenience wrapper, not a hard dependency.
 
 ### `scripts/read_issue.py`
 
 - Purpose: deterministic issue detail retrieval via `gh issue view`.
 - Outputs either a human-readable summary or full JSON for downstream automation.
 - Can include issue comments so the agent can read the latest discussion before taking any other step.
+- Treat it as a convenience wrapper, not a hard dependency.

package/read-github-issue/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Read GitHub Issue"
   short_description: "Read and search remote GitHub issues"
-  default_prompt: "Use $read-github-issue to verify the target GitHub repository with gh, find candidate issues with the bundled issue-search script, inspect the selected issue with comments and structured fields, summarize the trustworthy issue context, and call out any missing details before any separate planning or implementation work."
+  default_prompt: "Use $read-github-issue to verify the target GitHub repository with gh, prefer the bundled issue scripts when they work, fall back to raw gh issue commands when they do not, inspect the selected issue with comments and structured fields, summarize the trustworthy issue context, and call out any missing details before any separate planning or implementation work."

package/scripts/install_skills.ps1

@@ -9,18 +9,20 @@ $ErrorActionPreference = "Stop"
 function Show-Usage {
   @"
 Usage:
-  ./scripts/install_skills.ps1 [codex|openclaw|trae|all]...
+  ./scripts/install_skills.ps1 [codex|openclaw|trae|agents|all]...
 
 Modes:
   codex     Copy skills into ~/.codex/skills
   openclaw  Copy skills into ~/.openclaw/workspace*/skills
   trae      Copy skills into ~/.trae/skills
+  agents    Copy skills into ~/.agents/skills (for agent-skill-compatible software)
   all       Install all supported targets
 
 Optional environment overrides:
   CODEX_SKILLS_DIR   Override codex skills destination path
   OPENCLAW_HOME      Override openclaw home path
   TRAE_SKILLS_DIR    Override trae skills destination path
+  AGENTS_SKILLS_DIR  Override agents skills destination path
   APOLLO_TOOLKIT_HOME Override local install path used when repo root is unavailable
   APOLLO_TOOLKIT_REPO_URL Override git repository URL used when repo root is unavailable
 "@
@@ -126,8 +128,9 @@ function Resolve-Modes {
     Write-Host "1) codex (~/.codex/skills)"
     Write-Host "2) openclaw (~/.openclaw/workspace*/skills)"
     Write-Host "3) trae (~/.trae/skills)"
-    Write-Host "4) all"
-    $inputValue = Read-Host "Enter choice(s) [1-4]"
+    Write-Host "4) agents (~/.agents/skills)"
+    Write-Host "5) all"
+    $inputValue = Read-Host "Enter choice(s) [1-5]"
 
     foreach ($rawChoice in ($inputValue -split ",")) {
       $choice = $rawChoice.Trim()
@@ -135,10 +138,12 @@ function Resolve-Modes {
         "1" { Add-ModeOnce -Selected $selected -Mode "codex" }
         "2" { Add-ModeOnce -Selected $selected -Mode "openclaw" }
         "3" { Add-ModeOnce -Selected $selected -Mode "trae" }
-        "4" {
+        "4" { Add-ModeOnce -Selected $selected -Mode "agents" }
+        "5" {
           Add-ModeOnce -Selected $selected -Mode "codex"
           Add-ModeOnce -Selected $selected -Mode "openclaw"
           Add-ModeOnce -Selected $selected -Mode "trae"
+          Add-ModeOnce -Selected $selected -Mode "agents"
         }
         default {
           throw "Invalid choice: $choice"
@@ -152,10 +157,12 @@ function Resolve-Modes {
         "codex" { Add-ModeOnce -Selected $selected -Mode "codex" }
         "openclaw" { Add-ModeOnce -Selected $selected -Mode "openclaw" }
         "trae" { Add-ModeOnce -Selected $selected -Mode "trae" }
+        "agents" { Add-ModeOnce -Selected $selected -Mode "agents" }
         "all" {
           Add-ModeOnce -Selected $selected -Mode "codex"
           Add-ModeOnce -Selected $selected -Mode "openclaw"
           Add-ModeOnce -Selected $selected -Mode "trae"
+          Add-ModeOnce -Selected $selected -Mode "agents"
         }
         default {
           Show-Usage
@@ -256,6 +263,22 @@ function Install-Trae {
   }
 }
 
+function Install-Agents {
+  param([string[]]$SkillPaths)
+
+  $target = if ($env:AGENTS_SKILLS_DIR) {
+    $env:AGENTS_SKILLS_DIR
+  }
+  else {
+    Join-Path $HOME ".agents/skills"
+  }
+
+  Write-Host "Installing to agents: $target"
+  foreach ($src in $SkillPaths) {
+    Copy-Skill -Source $src -TargetRoot $target
+  }
+}
+
 if ($Modes.Count -gt 0 -and ($Modes[0] -eq "-h" -or $Modes[0] -eq "--help")) {
   Show-Usage
   exit 0
@@ -269,6 +292,7 @@ foreach ($mode in $selectedModes) {
     "codex" { Install-Codex -SkillPaths $skillPaths }
     "openclaw" { Install-OpenClaw -SkillPaths $skillPaths }
     "trae" { Install-Trae -SkillPaths $skillPaths }
+    "agents" { Install-Agents -SkillPaths $skillPaths }
     default { throw "Unknown mode: $mode" }
   }
 }

package/scripts/install_skills.sh

@@ -4,18 +4,20 @@ set -euo pipefail
 usage() {
   cat <<"USAGE"
 Usage:
-  ./scripts/install_skills.sh [codex|openclaw|trae|all]...
+  ./scripts/install_skills.sh [codex|openclaw|trae|agents|all]...
 
 Modes:
   codex     Copy skills into ~/.codex/skills
   openclaw  Copy skills into ~/.openclaw/workspace*/skills
   trae      Copy skills into ~/.trae/skills
+  agents    Copy skills into ~/.agents/skills (for agent-skill-compatible software)
   all       Install all supported targets
 
 Optional environment overrides:
   CODEX_SKILLS_DIR   Override codex skills destination path
   OPENCLAW_HOME      Override openclaw home path
   TRAE_SKILLS_DIR    Override trae skills destination path
+  AGENTS_SKILLS_DIR  Override agents skills destination path
   APOLLO_TOOLKIT_HOME Override local install path used in curl/pipe mode
   APOLLO_TOOLKIT_REPO_URL Override git repository URL used in curl/pipe mode
 USAGE
@@ -135,6 +137,16 @@ install_trae() {
   done
 }
 
+install_agents() {
+  local agents_skills_dir
+  agents_skills_dir="${AGENTS_SKILLS_DIR:-$HOME/.agents/skills}"
+
+  echo "Installing to agents: $agents_skills_dir"
+  for src in "${SKILL_PATHS[@]}"; do
+    replace_with_copy "$src" "$agents_skills_dir"
+  done
+}
+
 add_mode_once() {
   local mode="$1"
   local existing
@@ -153,13 +165,14 @@ parse_mode() {
   local mode="$1"
 
   case "$mode" in
-    codex|openclaw|trae)
+    codex|openclaw|trae|agents)
       add_mode_once "$mode"
       ;;
     all)
       add_mode_once "codex"
       add_mode_once "openclaw"
       add_mode_once "trae"
+      add_mode_once "agents"
       ;;
     *)
       echo "Invalid mode: $mode" >&2
@@ -195,8 +208,9 @@ choose_modes_interactive() {
   echo "1) codex (~/.codex/skills)"
   echo "2) openclaw (~/.openclaw/workspace*/skills)"
   echo "3) trae (~/.trae/skills)"
-  echo "4) all"
-  choice="$(read_choice_from_user 'Enter choice(s) [1-4]: ')"
+  echo "4) agents (~/.agents/skills)"
+  echo "5) all"
+  choice="$(read_choice_from_user 'Enter choice(s) [1-5]: ')"
 
   IFS=',' read -r -a choices <<< "$choice"
   for raw_choice in "${choices[@]}"; do
@@ -205,7 +219,8 @@ choose_modes_interactive() {
       1) add_mode_once "codex" ;;
       2) add_mode_once "openclaw" ;;
       3) add_mode_once "trae" ;;
-      4) add_mode_once "codex"; add_mode_once "openclaw"; add_mode_once "trae" ;;
+      4) add_mode_once "agents" ;;
+      5) add_mode_once "codex"; add_mode_once "openclaw"; add_mode_once "trae"; add_mode_once "agents" ;;
       *)
         echo "Invalid choice: $raw_choice" >&2
         exit 1
@@ -249,6 +264,7 @@ main() {
       codex) install_codex ;;
       openclaw) install_openclaw ;;
       trae) install_trae ;;
+      agents) install_agents ;;
       *)
         usage
         exit 1

package/ship-github-issue-fix/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: ship-github-issue-fix
+description: Resolve a GitHub issue in an existing repository and submit the fix directly to the requested branch without opening a PR or doing release work. Use when users ask to read issue N, implement the fix, decide whether planning artifacts are needed, run the relevant tests, and commit/push the result to `main` or another specified branch.
+---
+
+# Ship GitHub Issue Fix
+
+## Dependencies
+
+- Required: `read-github-issue`, `enhance-existing-features`, and `commit-and-push`.
+- Conditional: `systematic-debug` when the issue is primarily a bug investigation or failing behavior report.
+- Optional: none.
+- Fallback: If any required dependency is unavailable, stop and report which dependency blocked the workflow.
+
+## Standards
+
+- Evidence: Read the remote issue and the real implementation before deciding scope, process, or fixes.
+- Execution: Prefer the repo's existing issue-reading helpers, fall back to raw `gh issue` commands when helpers are missing, use spec planning only when the actual change surface justifies it, and push directly to the user-requested branch when submission is requested.
+- Quality: Treat localized bug fixes and narrow optimizations as direct implementation work unless the explored scope proves they need shared planning; finish tests, spec backfill, docs sync, and `AGENTS.md` sync before handing off submission.
+- Output: Report the issue context, chosen workflow, implemented fix, validation evidence, and commit/push result.
+
+## Overview
+
+Use this skill for the recurring workflow where the user wants one GitHub issue taken from remote context through implementation and direct submission. Keep the workflow tight: fetch the issue faithfully, decide whether specs are necessary from the explored codebase, finish the fix with tests, then submit without PR or release steps.
+
+## Workflow
+
+### 1) Read the issue from the remote source first
+
+- Start with `$read-github-issue`.
+- Verify the current repository matches the intended remote before reading issue content.
+- Prefer bundled issue scripts, but if they are missing or fail in the repository, immediately fall back to raw `gh issue view` / `gh issue list` so issue retrieval does not block the workflow.
+- Read issue body, labels, timestamps, and comments before touching code.
+- Treat user phrases such as `修復 issue 123`, `參考 issue 109 優化`, or `閱讀 issue 100 並提交到 main` as triggers for this skill.
+
+### 2) Explore the codebase and decide whether specs are required
+
+- After reading the issue, inspect the real entrypoints, affected modules, tests, and existing planning files.
+- Run `$enhance-existing-features` to decide whether specs are required from the actual change surface.
+- Default to direct implementation for clearly localized bug fixes, regressions, narrow optimizations, or small workflow corrections, even when the issue wording sounds broad.
+- Require specs when the explored change touches critical money movement, permissions, high-risk concurrency, or multi-module behavior changes that need approval traceability.
+- If specs are created and approved, finish all in-scope tasks and backfill them before submission.
+
+### 3) Implement and validate the fix completely
+
+- Keep the fix minimal and grounded in the actual root cause.
+- Reuse existing patterns instead of adding parallel abstractions.
+- If the issue is a bug or failing behavior report, bring in `$systematic-debug` for reproduction, root-cause verification, and regression coverage.
+- Run the most specific relevant tests first, then expand validation as needed.
+- When issue context exposed prior agent mistakes, add regression or guardrail coverage so the same failure is less likely to recur.
+
+### 4) Submit the fix without PR or release work
+
+- If the user asked to commit or push, hand off to `$commit-and-push`.
+- Preserve the user's explicit branch target; when the user says `push to main`, treat direct push to `main` as the default goal.
+- Before the final commit, ensure any required spec backfill, docs synchronization, and `AGENTS.md` alignment are completed.
+- Do not convert this flow into a PR workflow unless the user explicitly requests a PR.
+- Do not perform version bumps, tags, or GitHub Releases in this skill.
+
+### 5) Report the shipped result
+
+- Summarize the issue number and root cause.
+- State whether specs were used or intentionally skipped.
+- List the key files changed, the tests run, and whether commit/push succeeded.
+- Call out any remaining blocker only when one truly prevents completion.

package/ship-github-issue-fix/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Ship GitHub Issue Fix"
+  short_description: "Fix a GitHub issue and push directly"
+  default_prompt: "Use $ship-github-issue-fix to read the target GitHub issue from the current repository, decide whether specs are needed, implement the fix with appropriate tests, synchronize docs and AGENTS when needed, and commit and push directly to the requested branch without PR or release steps."

package/version-release/SKILL.md

@@ -15,7 +15,7 @@ description: "Guide the agent to prepare and publish a versioned release (versio
 ## Standards
 
 - Evidence: Inspect the active change set and the release range before touching version files, tags, or changelog entries.
-- Execution: Use this workflow only for explicit release intent, run the required quality gates when applicable, convert completed spec sets into categorized project docs before release finalization, normalize non-standard project docs when needed, then update versions, docs, commit, tag, push, and publish the GitHub release.
+- Execution: Use this workflow only for explicit release intent, run the required quality gates when applicable, convert completed spec sets into categorized project docs before release finalization, normalize non-standard project docs when needed, then update versions, docs, commit, tag, push, and publish the GitHub release; run git mutations sequentially and verify both the branch tip and release tag exist remotely before publishing the GitHub release.
 - Quality: Never guess versions, align user-facing docs with actual code, convert completed planning docs into standardized categorized project docs before the release is published, and treat the `archive-specs` structure as the release-ready documentation format.
 - Output: Produce a versioned release commit and tag, publish a matching GitHub release, and keep changelog plus relevant repository documentation synchronized.
 
@@ -91,6 +91,9 @@ Load only when needed:
    - Create the version tag locally after commit.
 11. Push
    - Push commit(s) and the release tag to the current branch before publishing the GitHub release when the hosting platform requires the tag to exist remotely.
+   - Do not overlap `git commit`, `git tag`, `git push`, or release-publish steps; wait for each mutation to finish before starting the next one.
+   - After pushing, verify the remote branch tip matches local `HEAD`, and verify the release tag exists remotely via `git ls-remote --tags <remote> <tag>`.
+   - If any git step finishes ambiguously or the remote hashes do not match local state, rerun the missing step sequentially and re-check before publishing the GitHub release.
 12. Publish the GitHub release
    - Create a non-draft GitHub release that matches the pushed version tag.
    - Use the release notes from the new `CHANGELOG.md` entry unless the repository has a stronger established release-note source.