Install full agent-tools guidance globally

Author: xiaojiecode

README.md

@@ -53,7 +53,7 @@ Set-Location .\agent-tools
 pwsh -NoProfile -File .\scripts\install.ps1
 ```
 
-安装脚本会构建七个可执行文件，设置当前用户的 `AGENT_TOOLS_HOME` 和 `PATH`，将 Skill 安装到 `%CODEX_HOME%\skills\agent-tools`，并在全局 `AGENTS.md` 中写入 `agent-tools` 标记块。
+安装脚本会构建七个可执行文件，设置当前用户的 `AGENT_TOOLS_HOME` 和 `PATH`，将 Skill 安装到 `%CODEX_HOME%\skills\agent-tools`，并将 `assets/global-agents.md` 中完整、自包含的日常命令说明写入全局 `AGENTS.md`。普通仓库操作可直接依据全局说明执行，不需要先加载 Skill；Skill 仅用于显式调用、维护、重装和疑难排查。
 
 测试安装而不修改用户环境变量或真实全局 Agent 文件：
 
@@ -85,6 +85,7 @@ Write-Output "Text=$Text"
 
 ```powershell
 go test .\scripts
+pwsh -NoProfile -File .\scripts\install_test.ps1
 go build -o .\dist\agent-tools.exe .\scripts\agent-tools.go
 pwsh -NoProfile -File .\scripts\install.ps1 -CodexHome (Join-Path $env:TEMP "agent-tools-test") -SkipUserEnvironment
 ```

SKILL.md

@@ -1,99 +1,33 @@
 ---
 name: agent-tools
-description: Use Windows-native agent helper commands for bounded UTF-8 file reads with glob expansion and batch boundaries, noise-excluded ripgrep searches, direct apply_patch delivery, Git checks, kill-on-close child processes, and profile-free PowerShell 7 execution. Use for routine repository work on Windows when quoting, encoding, oversized files or lines, profile noise, shell metacharacters, or orphaned child processes make raw PowerShell commands fragile.
+description: Maintain, install, or troubleshoot the Windows-native agent helper commands and their global AGENTS.md integration. Use when Codex needs to change this tool package, reinstall it, diagnose behavior not covered by the installed global reference, or when the user explicitly invokes $agent-tools. Routine command usage is documented in global AGENTS.md and should not implicitly trigger this skill.
 ---
 
 # Agent Tools
 
-Invoke the installed `agent-*` executable names directly. The installer places `%AGENT_TOOLS_HOME%` on `PATH`; use a computed path only with PowerShell's `&` call operator.
+The installer writes the complete routine command reference from `assets/global-agents.md` into the global `AGENTS.md`. Do not load this skill merely to look up normal `agent-*` syntax; use the already-loaded global reference.
 
-## Read Files
+## Maintenance Workflow
 
-Use `agent-read` for bounded UTF-8 reads:
-
-```powershell
-agent-read <path-or-pattern>...
-agent-read <paths...> --lines START:END
-agent-read <paths...> --from N --count N
-agent-read <paths...> --head N
-agent-read <paths...> --tail N
-agent-read <paths...> --number
-agent-read <paths...> --all
-agent-read <paths...> --max-lines N
-```
-
-Pass multiple concrete paths or patterns using `*`, `?`, `[]`, or recursive `**`. Results are sorted and deduplicated. Prefix a path beginning with `-` by `--`.
-
-The default output is the first 2,000 lines. Follow the stderr continuation hint when more content exists. Explicit ranges and `--tail` are complete unless `--max-lines` is supplied.
-
-For multiple files, recognize these boundaries and use the JSON metadata to associate content with its source:
-
-```text
-<<<AGENT_READ_FILE_START {"index":1,"total":2,"path":"C:\\code\\a.txt"}>>>
-...
-<<<AGENT_READ_FILE_END {"index":1,"total":2,"path":"C:\\code\\a.txt","status":"ok"}>>>
-```
-
-Treat invalid UTF-8 and safety-limit errors as failed reads. Limits are 1,000 matched files, 512 MiB per file, 8 MiB per line, 128 MiB retained tail content, and 1,000,000 tail lines. `~`, `~/...`, and `~\...` expand to the current user profile.
-
-## Search Repositories
-
-Use `agent-rg <pattern> [roots...]`. It invokes Windows `rg.exe` with line numbers, smart case, safe pattern separation, and exclusions for `node_modules`, `dist`, `logs`, `.git`, `.idea`, `tmp`, `.cache`, and `coverage`.
-
-## Apply Patches
-
-Use `agent-ap <patch-file>`. Supply a valid UTF-8 patch beginning with `*** Begin Patch` at byte zero. The helper passes it directly to `codex.exe --codex-run-as-apply-patch` without an intermediate shell.
-
-Codex CLI discovery order is `CODEX_EXE`, `%LOCALAPPDATA%\Programs\OpenAI\Codex\bin\codex.exe`, then `codex.exe` in `PATH`.
-
-## Check Git State
-
-Use `agent-status [repo]` for `git -C <repo> status --short`.
-
-Use `agent-diff [repo] [paths...]`. With no paths it prints `git diff --stat`; with paths it adds an argument-array `--` separator.
-
-## Run PowerShell
-
-Pipe Agent-authored scripts as literal here-strings to keep source out of command-line parsing:
-
-```powershell
-@'
-param([string]$Text)
-$payload = '{"enabled":true}'
-Write-Output "$Text $payload"
-'@ | agent-ps -- -Text 'a|b & 中文 "quote"'
-```
-
-Use `agent-ps --file <script.ps1> [-- args...]` for existing files. Use direct `agent-ps '<script>'` only for trivial one-line scripts already represented by one caller argument.
-
-`agent-ps` requires `pwsh.exe` and always supplies `-NoProfile -ExecutionPolicy Bypass`. It validates piped UTF-8, uses a temporary `.ps1`, and removes matching temporary files older than one hour. It does not fall back to Windows PowerShell 5.1.
-
-## Safety And Dependencies
-
-- External processes receive argument arrays rather than `.cmd` forwarding.
-- External processes join a `KILL_ON_JOB_CLOSE` Windows Job Object when available.
-- Missing dependencies return 127; usage errors return 2; file and parse failures normally return 1.
-- `agent-read` is self-contained. `agent-rg` requires `rg.exe`; Git commands require Git; `agent-ps` requires PowerShell 7; `agent-ap` requires Codex CLI.
+1. Edit `assets/global-agents.md` when changing the Agent-facing routine usage contract.
+2. Edit `scripts/agent-tools.go` and its tests when changing executable behavior.
+3. Keep `scripts/install.ps1` responsible for validating and installing the template, binaries, and skill files.
+4. Run the Go tests and the installation integration test.
+5. Reinstall from the repository root to deploy the updated binaries, skill metadata, and global reference.
 
 ## Install
 
-Run `pwsh -NoProfile -File scripts/install.ps1` from the repository root. The installer builds seven executable names, sets `AGENT_TOOLS_HOME`, installs the Skill under `%CODEX_HOME%\skills\agent-tools`, and updates the global `AGENTS.md` marker block.
+Run `pwsh -NoProfile -File scripts/install.ps1` from the repository root. The installer builds seven executable names, sets `AGENT_TOOLS_HOME`, installs the skill under `%CODEX_HOME%\skills\agent-tools`, and replaces the global `AGENTS.md` marker block from the validated template.
 
-Standard layout:
+The installed skill contains:
 
 ```text
-%USERPROFILE%\.codex\bin\
-  agent-tools.exe
-  agent-read.exe
-  agent-rg.exe
-  agent-ap.exe
-  agent-status.exe
-  agent-diff.exe
-  agent-ps.exe
-
 %USERPROFILE%\.codex\skills\agent-tools\
   SKILL.md
   agents\openai.yaml
+  assets\global-agents.md
   scripts\agent-tools.go
   scripts\agent-tools_test.go
 ```
+
+Routine command syntax, read limits, output boundaries, PowerShell transport, and dependency behavior belong in the global reference, not duplicated here.

agents/openai.yaml

@@ -1,4 +1,6 @@
 interface:
   display_name: "Agent Tools"
-  short_description: "Safe Windows repository commands for agents"
-  default_prompt: "Use $agent-tools to read files safely, search repositories, apply patches, inspect Git state, and run profile-free PowerShell 7 commands on Windows."
+  short_description: "Maintain Windows agent helper commands and setup"
+  default_prompt: "Use $agent-tools to maintain, install, or troubleshoot the Windows agent helper commands and their global AGENTS.md integration."
+policy:
+  allow_implicit_invocation: false

assets/global-agents.md

@@ -0,0 +1,78 @@
+<!-- agent-tools:start -->
+## Agent Tools
+
+This section is the self-contained operating reference for routine Windows repository work. Use it directly; do not open the `agent-tools` `SKILL.md` merely to learn normal command usage. Read that skill only when maintaining or reinstalling the tools, diagnosing behavior not covered here, or when a higher-priority instruction explicitly requires it.
+
+- Prefer the installed `%AGENT_TOOLS_HOME%` executables over fragile raw PowerShell pipelines.
+- Invoke installed `agent-*` short names directly. Invoke a computed executable path with PowerShell's `&` call operator.
+- Keep reusable Windows and PowerShell workarounds in the global `AGENTS.md` or the tool implementation instead of duplicating them in project-level instructions.
+
+### Command Map
+
+| Command | Purpose |
+| --- | --- |
+| `agent-read` | Bounded UTF-8 reads with ranges, globs, batch boundaries, tails, and line numbers |
+| `agent-rg` | Ripgrep searches with line numbers, smart case, safe argument passing, and noise exclusions |
+| `agent-ap` | Direct delivery of an existing UTF-8 patch file to the Codex apply-patch implementation |
+| `agent-status` | Concise Git worktree status |
+| `agent-diff` | Repository or path-scoped Git diffs |
+| `agent-ps` | Profile-free PowerShell 7 execution with safe script and argument transport |
+
+### Read Files
+
+Use `agent-read` for bounded UTF-8 reads:
+
+```powershell
+agent-read <path-or-pattern>...
+agent-read <paths...> --lines START:END
+agent-read <paths...> --from N --count N
+agent-read <paths...> --head N
+agent-read <paths...> --tail N
+agent-read <paths...> --number
+agent-read <paths...> --all
+agent-read <paths...> --max-lines N
+```
+
+- Pass multiple concrete paths or patterns using `*`, `?`, `[]`, or recursive `**`. Results are sorted and deduplicated. Prefix a path beginning with `-` by `--`.
+- The default output is the first 2,000 lines. Follow the stderr continuation hint when more content exists. Explicit ranges and `--tail` are complete unless `--max-lines` is supplied.
+- Multiple-file output uses `<<<AGENT_READ_FILE_START {...}>>>` and `<<<AGENT_READ_FILE_END {...}>>>` boundaries. Associate content with its source through the JSON `path` field.
+- Treat invalid UTF-8 and safety-limit errors as failed reads. Limits are 1,000 matched files, 512 MiB per file, 8 MiB per line, 128 MiB retained tail content, and 1,000,000 tail lines.
+- `~`, `~/...`, and `~\...` expand to the current user profile.
+
+### Search Repositories
+
+- Use `agent-rg <pattern> [roots...]`. It invokes `rg.exe` with line numbers, smart case, safe pattern separation, and exclusions for `node_modules`, `dist`, `logs`, `.git`, `.idea`, `tmp`, `.cache`, and `coverage`.
+
+### Apply Patches
+
+- Use `agent-ap <patch-file>` for an existing UTF-8 patch file. The patch must begin with `*** Begin Patch` at byte zero and is delivered directly to Codex without an intermediate shell.
+- Codex CLI discovery order is `CODEX_EXE`, `%LOCALAPPDATA%\Programs\OpenAI\Codex\bin\codex.exe`, then `codex.exe` on `PATH`.
+- For ordinary manual edits made through the current tool API, continue to use the available `apply_patch` tool directly; do not create a temporary patch file unless needed.
+
+### Check Git State
+
+- Use `agent-status [repo]` for `git -C <repo> status --short`.
+- Use `agent-diff [repo] [paths...]`. With no paths it prints a diff summary; supplied paths are passed after Git's `--` separator.
+
+### Run PowerShell
+
+- Use `agent-ps` for Agent-authored PowerShell. It requires `pwsh.exe` and runs with `-NoProfile -ExecutionPolicy Bypass`; never fall back to Windows PowerShell 5.1.
+- Pipe non-trivial scripts as a literal here-string directly to `agent-ps`, then pass script arguments after `--`:
+
+```powershell
+@'
+param([string]$Text)
+$payload = '{"enabled":true}'
+Write-Output "$Text $payload"
+'@ | agent-ps -- -Text 'a|b & 中文 "quote"'
+```
+
+- Use `agent-ps --file <script.ps1> [-- args...]` for an existing script. Reserve direct `agent-ps '<script>'` for trivial one-line commands represented by one caller argument.
+- Piped input must be valid UTF-8. Temporary scripts are removed after execution, along with matching stale temporary files older than one hour.
+
+### Safety And Dependencies
+
+- External processes receive argument arrays rather than `.cmd` forwarding and join a `KILL_ON_JOB_CLOSE` Windows Job Object when available.
+- Missing dependencies return exit code 127; usage errors return 2; file and parse failures normally return 1.
+- `agent-read` is self-contained. `agent-rg` requires `rg.exe`, Git commands require Git, `agent-ps` requires PowerShell 7, and `agent-ap` requires the Codex CLI.
+<!-- agent-tools:end -->

scripts/install.ps1

@@ -31,6 +31,7 @@ $GlobalAgentsPath = [IO.Path]::GetFullPath($GlobalAgentsPath)
 
 $repositoryRoot = Split-Path -Parent $PSScriptRoot
 $goSource = Join-Path $PSScriptRoot "agent-tools.go"
+$globalAgentsTemplate = Join-Path $repositoryRoot "assets\global-agents.md"
 $binDirectory = Join-Path $CodexHome "bin"
 $skillDirectory = Join-Path $CodexHome "skills\agent-tools"
 $executableNames = @(
@@ -71,22 +72,23 @@ function Add-PathEntryOnce {
 }
 
 function Update-GlobalAgents {
-    param([string]$Path)
+    param(
+        [string]$Path,
+        [string]$TemplatePath
+    )
 
     $beginMarker = "<!-- agent-tools:start -->"
     $endMarker = "<!-- agent-tools:end -->"
-    $block = @'
-<!-- agent-tools:start -->
-## Agent Tools
-
-- For routine Windows repository work, prefer the executables in `%AGENT_TOOLS_HOME%` over raw PowerShell pipelines.
-- Invoke installed `agent-*` short names directly. A computed executable path must be invoked with PowerShell's `&` call operator.
-- `agent-ps` requires PowerShell 7 (`pwsh.exe`) and runs with `-NoProfile -ExecutionPolicy Bypass`; never use Windows PowerShell 5.1 as a fallback.
-- Use `agent-read` for bounded UTF-8 reads with glob support, `agent-rg` for excluded searches, and `agent-ap` for UTF-8 patch files.
-- Use `agent-status` and `agent-diff` for Git checks. For Agent-authored PowerShell, pipe a literal here-string directly to `agent-ps`; keep direct `agent-ps '<script>'` only for trivial one-argument commands.
-- Keep reusable Windows/PowerShell workarounds in the global `AGENTS.md` or the `agent-tools` skill instead of duplicating them in project-level instructions.
-<!-- agent-tools:end -->
-'@
+    if (-not (Test-Path -LiteralPath $TemplatePath -PathType Leaf)) {
+        throw "Global AGENTS template not found: $TemplatePath"
+    }
+
+    $block = (Get-Content -LiteralPath $TemplatePath -Raw -Encoding utf8).Trim()
+    $beginCount = [Regex]::Matches($block, [Regex]::Escape($beginMarker)).Count
+    $endCount = [Regex]::Matches($block, [Regex]::Escape($endMarker)).Count
+    if ($beginCount -ne 1 -or $endCount -ne 1 -or -not $block.StartsWith($beginMarker) -or -not $block.EndsWith($endMarker)) {
+        throw "Global AGENTS template must contain exactly one complete agent-tools marker block."
+    }
 
     $parent = Split-Path -Parent $Path
     New-Item -ItemType Directory -Path $parent -Force | Out-Null
@@ -126,7 +128,7 @@ try {
 
     if (-not [string]::Equals([IO.Path]::GetFullPath($repositoryRoot), [IO.Path]::GetFullPath($skillDirectory), [StringComparison]::OrdinalIgnoreCase)) {
         New-Item -ItemType Directory -Path $skillDirectory -Force | Out-Null
-        foreach ($item in @("SKILL.md", "agents", "scripts")) {
+        foreach ($item in @("SKILL.md", "agents", "assets", "scripts")) {
             Copy-Item -LiteralPath (Join-Path $repositoryRoot $item) -Destination $skillDirectory -Recurse -Force
         }
     }
@@ -140,7 +142,7 @@ try {
     }
 
     if (-not $SkipGlobalAgents) {
-        Update-GlobalAgents $GlobalAgentsPath
+        Update-GlobalAgents $GlobalAgentsPath $globalAgentsTemplate
     }
 } finally {
     if (Test-Path -LiteralPath $temporaryDirectory) {

scripts/install_test.ps1

@@ -0,0 +1,64 @@
+#requires -Version 7.0
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function Assert-True {
+    param(
+        [bool]$Condition,
+        [string]$Message
+    )
+
+    if (-not $Condition) {
+        throw $Message
+    }
+}
+
+$installer = Join-Path $PSScriptRoot "install.ps1"
+$temporaryRoot = Join-Path ([IO.Path]::GetTempPath()) ("agent-tools-install-test-" + [Guid]::NewGuid().ToString("N"))
+$codexHome = Join-Path $temporaryRoot ".codex"
+$globalAgents = Join-Path $temporaryRoot "AGENTS.md"
+
+try {
+    New-Item -ItemType Directory -Path $temporaryRoot -Force | Out-Null
+    @'
+# Existing Rules
+
+Keep this content.
+
+<!-- agent-tools:start -->
+legacy block
+<!-- agent-tools:end -->
+'@ | Set-Content -LiteralPath $globalAgents -Encoding utf8 -NoNewline
+
+    & pwsh.exe -NoProfile -File $installer -CodexHome $codexHome -GlobalAgentsPath $globalAgents -SkipUserEnvironment | Out-Null
+    if ($LASTEXITCODE -ne 0) {
+        throw "First installer run failed with exit code $LASTEXITCODE"
+    }
+
+    $firstInstall = Get-Content -LiteralPath $globalAgents -Raw -Encoding utf8
+    Assert-True ($firstInstall.Contains("Keep this content.")) "Installer removed unrelated global AGENTS content."
+    Assert-True (-not $firstInstall.Contains("legacy block")) "Installer did not replace the previous marker block."
+    Assert-True ($firstInstall.Contains("This section is the self-contained operating reference")) "Installed block is missing its self-contained usage rule."
+    Assert-True ($firstInstall.Contains("### Command Map")) "Installed block is missing the command map."
+    Assert-True ($firstInstall.Contains("### Safety And Dependencies")) "Installed block is missing safety and dependency guidance."
+    Assert-True (([Regex]::Matches($firstInstall, [Regex]::Escape("<!-- agent-tools:start -->"))).Count -eq 1) "Installed file contains multiple start markers."
+    Assert-True (([Regex]::Matches($firstInstall, [Regex]::Escape("<!-- agent-tools:end -->"))).Count -eq 1) "Installed file contains multiple end markers."
+
+    $installedTemplate = Join-Path $codexHome "skills\agent-tools\assets\global-agents.md"
+    Assert-True (Test-Path -LiteralPath $installedTemplate -PathType Leaf) "Installer did not copy the global AGENTS template into the installed skill."
+
+    & pwsh.exe -NoProfile -File $installer -CodexHome $codexHome -GlobalAgentsPath $globalAgents -SkipUserEnvironment | Out-Null
+    if ($LASTEXITCODE -ne 0) {
+        throw "Second installer run failed with exit code $LASTEXITCODE"
+    }
+
+    $secondInstall = Get-Content -LiteralPath $globalAgents -Raw -Encoding utf8
+    Assert-True ($secondInstall -eq $firstInstall) "Installer is not idempotent."
+
+    Write-Output "install integration test passed"
+} finally {
+    if (Test-Path -LiteralPath $temporaryRoot) {
+        Remove-Item -LiteralPath $temporaryRoot -Recurse -Force
+    }
+}