@moon791017/neo-skills 1.1.4 → 1.1.6

package/README.md

@@ -82,7 +82,11 @@
 
 * **AI 助手開發治理 (`skills/neo-agent-harness`)**：檢查專案規則、測試、CI、審查流程與安全防護，協助 AI 助手更穩定地參與開發。
 
-### 12. AI Tells / Slop 贅詞消除專家
+### 12. Sub-Agent 建立器
+
+* **跨 CLI Sub-Agent 建立器 (`skills/neo-sub-agent`)**：設計並生成 Antigravity CLI、Codex、Claude Code 與 Copilot CLI 的 sub-agent/custom agent 設定，包含角色拆分、工具權限、檔案格式與驗證流程。
+
+### 13. AI Tells / Slop 贅詞消除專家
 
 * **文字去 AI 腔調 (`skills/neo-stop-slop`)**：消除中英文 AI 腔、贅詞與公式化囉唆句式，還原為乾淨、生動且簡煉的自然語言，並包含工程師註解、Git Commit 及 PR 說明的特化優化。
 
@@ -162,7 +166,8 @@ npx skills add Benknightdark/neo-skills --all
 | **18. Code Review 專家** | `npx skills add Benknightdark/neo-skills --skill neo-code-review` |
 | **19. 需求分析與釐清助手** | `npx skills add Benknightdark/neo-skills --skill neo-clarification` |
 | **20. AI 開發流程治理專家** | `npx skills add Benknightdark/neo-skills --skill neo-agent-harness` |
-| **21. AI Tells/Slop 消除專家** | `npx skills add Benknightdark/neo-skills --skill neo-stop-slop` |
+| **21. Sub-Agent 建立器** | `npx skills add Benknightdark/neo-skills --skill neo-sub-agent` |
+| **22. AI Tells/Slop 消除專家** | `npx skills add Benknightdark/neo-skills --skill neo-stop-slop` |
 
 ---
 
@@ -233,6 +238,7 @@ npx -p @moon791017/neo-skills install-system-instructions --ai-agent claude --in
 | **TS 型別設計與 CJS/ESM 互通** | `neo-typescript` | `npx skills add Benknightdark/neo-skills --skill neo-typescript` | `解決 tsconfig 與 ESM/CJS 互通性問題` |
 | **複雜/模糊需求釐清與規格化** | `neo-clarification` | `npx skills add Benknightdark/neo-skills --skill neo-clarification` | `規劃一個電商網站` |
 | **AI 助手開發治理與流程健檢** | `neo-agent-harness` | `npx skills add Benknightdark/neo-skills --skill neo-agent-harness` | `評估 AI 開發治理流程` |
+| **建立跨 CLI Sub-Agent / Custom Agent** | `neo-sub-agent` | `npx skills add Benknightdark/neo-skills --skill neo-sub-agent` | `新增一個 Codex code-reviewer sub agent` |
 | **清除文案/註解/Commit 中的 AI 腔** | `neo-stop-slop` | `npx skills add Benknightdark/neo-skills --skill neo-stop-slop` | `消除這段話的 AI 腔贅詞` |
 
 ## 🛠 開發與測試指南

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "type": "module",
   "description": "Neo Skills: A Universal Expert Agent Extension",
   "homepage": "https://neo-blog-iota.vercel.app/",

package/skills/neo-clarification/SKILL.md

@@ -6,7 +6,7 @@ description: >
 
 # Requirement Clarification Specifications
 
-You are a Senior System Analyst and Requirement Translation Expert (Inversion & Generator Pattern). Follow this protocol strictly to translate raw, chaotic user complaints and screenshots into clean, structured system specifications.
+Apply the Inversion & Generator Pattern. Follow this protocol strictly to translate raw, chaotic user complaints and screenshots into clean, structured system specifications.
 
 ---
 

package/skills/neo-code-review/SKILL.md

@@ -6,7 +6,7 @@ description: >
 
 # Code Review Specifications
 
-You are a senior code review expert (Reviewer Pattern). Follow this protocol strictly to systematically, objectively, and constructively review the user's code changes.
+Apply the Reviewer Pattern. Follow this protocol strictly to systematically, objectively, and constructively review the user's code changes.
 
 ---
 
@@ -37,9 +37,10 @@ You are a senior code review expert (Reviewer Pattern). Follow this protocol str
      [review-checklist.md](file:///Users/ben/Projects/neo-skills/skills/neo-code-review/references/review-checklist.md)
    
 2. **Systematically Evaluate Code**:
-   - Analyze the code logic deeply and compare it against the 5 dimensions in the checklist (Correctness, Security, Performance, Maintainability, Style).
-   - Filter out **🔴 Critical Issues (Must-fix)**, especially security vulnerabilities (e.g., SQL injections, hardcoded keys, unclosed resource connections).
-   - For architectural recommendations, code duplication, or high cyclomatic complexity, classify them under **🟡 Suggestions**.
+   - Analyze the code logic deeply and compare it against the checklist dimensions: Correctness, Regression Risk, Security, Performance, Data & Concurrency, Test Gaps, SOLID/Design Principles, Logging/Observability, Maintainability, and Style.
+   - Prioritize evidence-backed findings that create concrete behavioral, security, operational, compatibility, or maintainability risk.
+   - Filter out **🔴 Critical Issues (Must-fix)** for defects such as requirement breakage, security vulnerabilities, data corruption/loss, broken authorization, severe regressions, or production-impacting reliability failures.
+   - Classify lower-risk performance, design, logging, test coverage, readability, and maintainability issues under **🟡 Suggestions** when they have a clear reason and actionable remediation.
 
 ---
 

package/skills/neo-code-review/references/review-checklist.md

@@ -1,76 +1,136 @@
 # Code Review Checklist
 
-This checklist serves as a systematic guideline for AI reviewers. During the review process, compare the code changes against these criteria and categorize findings by severity: Critical Issues (🔴 Must-fix), Suggestions (🟡 Clean Code/Performance), and Praise (🟢 High Quality).
+This checklist is the review baseline for `neo-code-review`. During review, compare the code changes against these criteria and categorize findings by severity: Critical Issues (🔴 Must-fix), Suggestions (🟡 Clean Code/Performance), and Praise (🟢 High Quality).
+
+Only report a finding when the risk is supported by the diff, surrounding code, tests, runtime behavior, or a clearly stated requirement. Do not turn every checklist item into a finding.
 
 ---
 
 ## 1. Correctness & Logic
 
-- [ ] **Functional Completeness**: Does the code fully implement the intended requirements? Are there any missing business logic paths?
-- [ ] **Edge Cases**: Are extreme inputs handled properly (e.g., `null`, `undefined`, empty strings, empty arrays, maximum/minimum values, negative numbers, special characters)?
+- [ ] **Requirement Preservation**: Does the change break an existing or stated requirement? Does it miss a required business path?
+- [ ] **Logic Errors**: Are conditionals, loops, ordering, calculations, parsing, validation, or branching rules incorrect?
+- [ ] **Boundary Conditions**: Are edge cases handled properly, such as `null`, `undefined`, empty values, maximum/minimum values, negative numbers, special characters, duplicate input, timezone boundaries, or partial data?
+- [ ] **State Transitions**: Are status changes, lifecycle transitions, retries, rollbacks, or cleanup steps consistent and reversible where required?
 - [ ] **Exception Handling**:
-  - Are error-prone operations (e.g., I/O, network requests, parsing) wrapped in appropriate `try-catch` blocks?
-  - Are caught exceptions handled gracefully (e.g., recovering state, user-friendly notifications, or safe logging) instead of being swallowed silently?
-- [ ] **Concurrency & Thread Safety**: In multi-threaded or asynchronous environments, are there potential race conditions, deadlocks, or unawaited async operations?
-- [ ] **State Management**: Are variable lifecycles correct? Are there any unintended side effects or global namespace pollution?
+  - Are error-prone operations such as I/O, network requests, database calls, parsing, serialization, or background jobs handled safely?
+  - Are caught exceptions recovered, propagated, or logged appropriately instead of being swallowed silently?
 
 ---
 
-## 2. Security — 🔴 Critical
+## 2. Regression Risk & Compatibility
 
-- [ ] **Injection Defenses**:
-  - **SQL Injection**: Are parameterized queries or ORM used? Direct string concatenation for SQL queries is strictly prohibited.
-  - **XSS (Cross-Site Scripting)**: Is data rendered to the frontend properly escaped or sanitized?
-  - **Command Injection**: Are user inputs directly concatenated into system commands?
-- [ ] **Sensitive Data Protection**:
-  - Are there any hardcoded secrets, API tokens, passwords, database connection strings, or private keys?
-  - Does logging accidentally capture Personally Identifiable Information (PII, e.g., SSN, phone numbers, passwords, credit cards) or sensitive internal system structures?
+- [ ] **Existing APIs**: Does the change break public APIs, endpoint behavior, method signatures, event contracts, or SDK/client expectations?
+- [ ] **Data Formats**: Does it change request/response schemas, database shape, serialized fields, enum values, date formats, number precision, or default values in an incompatible way?
+- [ ] **Error Formats**: Does it break existing error codes, problem details, validation messages, HTTP status codes, or client-side error handling assumptions?
+- [ ] **Permission Flows**: Does it alter authentication, authorization, role checks, ownership checks, or approval flows in a way that blocks valid users or grants excessive access?
+- [ ] **User Workflows**: Does it break existing user journeys, backward compatibility, migrations, imports/exports, saved settings, deep links, or integrations?
+
+---
+
+## 3. Security — 🔴 Critical
+
+- [ ] **Injection**:
+  - SQL injection, NoSQL injection, command injection, LDAP injection, or template injection.
+  - Unsafe string concatenation in queries, shell commands, templates, filters, or dynamic expressions.
+- [ ] **Web Security**:
+  - XSS caused by missing output encoding, unsafe HTML rendering, unsafe markdown rendering, or scriptable user content.
+  - CSRF exposure on state-changing requests.
+  - CORS misconfiguration that allows unintended origins, credentials, or methods.
 - [ ] **Authentication & Authorization**:
-  - Are appropriate authorization and authentication checks performed for sensitive operations and APIs?
-  - Does it follow the "Principle of Least Privilege"?
-- [ ] **Insecure Practices & Dependencies**:
-  - Are known insecure functions used (e.g., `eval()` in JavaScript, `exec()` in Python)?
-  - Do dependency libraries have known major vulnerabilities?
+  - Broken authentication, broken access control, IDOR, missing ownership checks, weak session handling, or bypassable authorization logic.
+  - Missing rate limit or abuse protection on sensitive endpoints such as login, reset, invite, export, payment, or AI calls.
+- [ ] **Sensitive Data Protection**:
+  - Sensitive data exposure, secret/token leakage, hardcoded credentials, connection strings, private keys, or unsafe debug output.
+  - Insecure logging of tokens, passwords, PII, connection strings, full sensitive payloads, or reversible sensitive data.
+- [ ] **File, Network & Execution Risks**:
+  - SSRF, path traversal, arbitrary file read/write, unsafe upload handling, insecure deserialization, unsafe reflection, or dynamic execution.
+- [ ] **Validation & Encoding**:
+  - Missing input validation, output encoding, authorization checks, allowlists, size limits, content-type validation, or schema validation.
+- [ ] **Cryptography**:
+  - Insecure crypto, weak hashes, predictable random values, missing salt, hardcoded keys, custom crypto, or unsafe key management.
+
+---
+
+## 4. Performance & Resource Management
+
+- [ ] **Database Efficiency**:
+  - N+1 queries, repeated database roundtrips, missing batching, unnecessary joins, fetching unused columns, or repeated writes.
+  - Unpaginated large queries, unbounded result sets, missing limits, or missing necessary index guidance for hot queries.
+- [ ] **Async & External Calls**:
+  - Synchronous blocking inside async flows, sync-over-async, unawaited tasks, missing cancellation token propagation, or thread-pool starvation risk.
+  - External API calls without timeout, retry/backoff, idempotency strategy, or circuit-breaker consideration where failures could cascade.
+- [ ] **Memory & Resource Use**:
+  - Large allocations, loading entire large files or payloads into memory, unbounded buffers, unclosed streams, undisposed resources, or leaked handles.
+  - Unregistered event listeners, long-lived references, growing global caches, or background work that cannot be stopped.
+- [ ] **Algorithmic Efficiency**:
+  - Inefficient algorithms, repeated computation, unnecessary nested loops, repeated serialization/deserialization, or expensive work in hot paths.
+- [ ] **Logging Cost**:
+  - Excessive logging in hot paths, logging large payloads, or synchronous logging that can slow requests.
+- [ ] **Caching**:
+  - Incorrect cache keys, stale cache invalidation, cache stampede risk, missing TTLs, or caching data with user-specific authorization requirements.
 
 ---
 
-## 3. Performance & Resource Management
+## 5. Data & Concurrency
 
-- [ ] **Algorithms & Complexity**: Are time and space complexities reasonable? Are there unnecessary nested loops (e.g., $O(n^2)$ or worse)?
-- [ ] **Database Interaction Efficiency**:
-  - Are there N+1 query issues?
-  - Do database queries utilize indexes properly, or do they fetch unnecessary columns/rows?
-- [ ] **Resource Lifecycle Management**:
-  - Are file handles, database connections, network sockets, and streams explicitly closed/released after use?
-  - Are resources released in `finally` blocks or using structural patterns like `using` (.NET) or `with` (Python)?
-- [ ] **Memory Leaks**:
-  - Are there unregistered event listeners, infinitely growing global caches, or long-lived objects retaining references to short-lived objects?
-- [ ] **Caching & Lazy Loading**: Is an appropriate caching strategy used for high-frequency, low-variance expensive computations or I/O operations?
+- [ ] **Transaction Consistency**: Are related writes protected by transactions or compensating logic where partial failure would corrupt state?
+- [ ] **Duplicate Writes & Idempotency**: Can retries, double-clicks, queue redelivery, or webhook replay create duplicate records or repeated side effects?
+- [ ] **Race Conditions**: Are there check-then-act races, lost updates, optimistic concurrency gaps, locking mistakes, deadlocks, or shared mutable state issues?
+- [ ] **Cache Invalidation**: Does the change keep cache, database, search index, derived data, and client state consistent?
+- [ ] **Resource Release**: Are locks, transactions, database connections, file handles, timers, subscriptions, and background workers released on success and failure?
+- [ ] **Async Error Handling**: Are async failures observed, propagated, retried safely, or surfaced to monitoring instead of becoming unhandled background errors?
 
 ---
 
-## 4. Maintainability & Readability
+## 6. Test Gaps
 
-- [ ] **Clear Naming**: Are variables, functions, and classes named intuitively and descriptively? Are single-character or meaningless names avoided?
-- [ ] **Complexity Control**:
-  - Is the length of a single function/method reasonable (ideally under 50 lines)?
-  - Is the cyclomatic complexity too high (e.g., excessive nesting, too many branch conditions)?
-- [ ] **Modularity & Architecture**:
-  - Does the code follow the **DRY (Don't Repeat Yourself)** principle?
-  - Does the code follow **SOLID principles** (especially the Single Responsibility Principle - SRP)?
-- [ ] **Testability**:
-  - Is the code easy to unit test?
-  - Is there appropriate dependency injection or decoupling to facilitate mocking external dependencies?
-  - Are there corresponding test cases for new features or bug fixes?
+- [ ] **High-Risk Branches**: Are new critical branches, feature flags, migrations, fallbacks, retries, or failure branches covered?
+- [ ] **Error Paths**: Are validation errors, dependency failures, timeouts, malformed data, and partial failures tested?
+- [ ] **Permission Boundaries**: Are unauthorized, unauthenticated, wrong-owner, wrong-role, and cross-tenant cases tested?
+- [ ] **Data Conversion**: Are serialization, parsing, mapping, rounding, timezone handling, enum changes, and schema compatibility tested?
+- [ ] **Regression Scenarios**: Are tests present for the bug being fixed or the existing workflow that could be broken?
 
 ---
 
-## 5. Style & Standards
+## 7. SOLID / Design Principles
 
-- [ ] **Idiomatic Best Practices**: Does the code leverage modern features of the language/framework (e.g., TypeScript utility types, Python type hints, pattern matching)?
-- [ ] **Formatting & Style Consistency**:
-  - Do indentation, spacing, and quotes match the existing patterns in the codebase?
-  - Does the code pass local Linter checks (e.g., ESLint, Ruff)?
+- [ ] **SRP (Single Responsibility Principle)**: Does a class, method, component, or service take on too many responsibilities, making bugs or tests more likely?
+- [ ] **OCP (Open/Closed Principle)**: Will common new requirements require repeatedly editing fragile core logic instead of extending through stable seams?
+- [ ] **LSP (Liskov Substitution Principle)**: Do inheritance, interface, or polymorphic changes violate existing contracts or caller assumptions?
+- [ ] **ISP (Interface Segregation Principle)**: Are callers forced to depend on methods, fields, DTO members, or service operations they do not need?
+- [ ] **DIP (Dependency Inversion Principle)**: Do high-level modules directly depend on concrete implementations in a way that makes testing, replacement, or isolation difficult?
+
+Only list SOLID/design findings when the violation clearly increases defect risk, breaks extension, makes tests meaningfully harder, or creates concrete maintenance risk. Do not report abstract design preferences as findings.
+
+---
+
+## 8. Logging / Observability
+
+- [ ] **Coverage of Important Failure Points**: Do important error paths, external APIs, database operations, background jobs, scheduled jobs, payment flows, and AI calls have enough logging or telemetry to debug production failures?
+- [ ] **Diagnostic Context**: Do logs include useful correlation fields such as request id, entity id, user/tenant identifier when safe, operation, status, duration, and exception details?
+- [ ] **Log Levels**: Are expected business outcomes logged below `error`, and real failures not hidden as `debug` or omitted entirely?
+- [ ] **Sensitive Data Safety**: Logs must not include tokens, passwords, connection strings, personal data, full sensitive payloads, or content that can reconstruct sensitive data.
+- [ ] **Signal-to-Noise**: Do not require logging on every line. Report logging gaps only for failure points that would be difficult to investigate after deployment.
+
+---
+
+## 9. Maintainability & Style
+
+- [ ] **Clear Naming**: Are variables, functions, classes, files, and modules named clearly enough to reflect intent?
+- [ ] **Complexity Control**:
+  - Is a function, method, component, or query too long or deeply nested to review safely?
+  - Is cyclomatic complexity high enough to hide bugs or make tests brittle?
+- [ ] **Modularity & Duplication**:
+  - Does the code avoid meaningful duplication, copy-pasted business rules, and divergent validation logic?
+  - Is shared behavior placed at the right abstraction level without over-engineering?
+- [ ] **Testability**:
+  - Is the code easy to unit test or integration test?
+  - Are dependencies injectable or isolatable where tests need control over time, I/O, network calls, randomness, or external systems?
+- [ ] **Idiomatic Best Practices**: Does the code use language and framework conventions appropriately without fighting the platform?
+- [ ] **Formatting & Consistency**:
+  - Do indentation, spacing, imports, quotes, naming, and file organization match the codebase?
+  - Does the code pass the local formatter, linter, and type checker when applicable?
 - [ ] **Comment Quality**:
-  - Do comments explain "Why" the code is written this way, rather than restating "What" the code does?
-  - Has obsolete or commented-out dead code been cleaned up?
+  - Do comments explain non-obvious intent and tradeoffs instead of restating the code?
+  - Has obsolete, misleading, or commented-out dead code been removed?

package/skills/neo-dotnet-tag-helper/SKILL.md

@@ -18,7 +18,7 @@ metadata:
 
 ## Workflow (Generator Pattern)
 
-You are an expert C# Tag Helper generator. Follow these steps exactly to create robust, high-performance Tag Helpers.
+Follow these steps exactly to create robust, high-performance C# Tag Helpers.
 
 ### Step 1: Perceive & Gather Requirements (Inversion)
 Before writing any code, ask the user to clarify the following if not already provided:

package/skills/neo-rust/SKILL.md

@@ -11,7 +11,7 @@ metadata:
 
 # Neo Rust Expert
 
-You are an expert Rust developer. Your goal is to write safe, maintainable, and idiomatic Rust code by strictly following the official design patterns, leveraging Rust's powerful type system, and avoiding anti-patterns.
+Write safe, maintainable, and idiomatic Rust code by strictly following the official design patterns, leveraging Rust's powerful type system, and avoiding anti-patterns.
 
 ## Gotchas
 

package/skills/neo-sub-agent/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: neo-sub-agent
+description: >
+  設計、建立、審查或轉換跨 CLI sub-agent、custom agent、worker agent、reviewer agent、planner agent、explorer agent、background agent 與 multi-agent workflow。Use this skill when the user asks to add a sub agent, create a custom agent, design agent delegation, or generate agent files for Antigravity CLI, Codex, Claude Code, or GitHub Copilot CLI.
+---
+
+# Neo Sub-Agent
+
+Use this skill to design and generate focused sub-agent definitions for developer CLIs. Keep the user in control of scope, permissions, and target clients.
+
+## Core Rule
+Do not invent client-specific schema. If the requested CLI, field, or file location is not documented in `references/client-adapters.md` or discoverable in the project, state the missing fact and generate only a neutral blueprint.
+
+## Workflow
+
+### 1. Perceive
+1. Inspect the project before asking questions:
+   - Existing agent definitions: `.claude/agents/`, `.codex/agents/`, `.github/agents/`, `.agents/skills/`.
+   - Project guidance: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`.
+   - Related skills or conventions in `skills/`, `.agents/skills/`, `.github/skills/`, `.claude/skills/`, `.codex/skills/`.
+2. Identify the target clients from the user request or project evidence: `claude`, `codex`, `copilot`, `agy`, or multiple.
+3. If multiple clients are plausible and the request does not specify one, ask one concise question before writing files.
+
+### 2. Decide Whether a Sub-Agent Fits
+Read `references/sub-agent-design.md` when the request involves architecture, multiple agents, or tradeoffs.
+
+Use a sub-agent when at least one is true:
+- The work produces verbose logs, search results, or file reads that should not pollute the main context.
+- The work is a repeated specialist role such as code review, planning, test execution, research, migration analysis, or docs verification.
+- The work can run independently or in a clearly bounded sequence.
+- The role needs stricter tool access, sandboxing, model choice, or output contract than the main agent.
+
+Prefer a normal skill or main-conversation instruction when:
+- The task is a quick, targeted change.
+- The agent needs frequent back-and-forth with the user.
+- Multiple workers would edit the same files concurrently.
+- The workflow depends on undocumented client behavior.
+
+### 3. Define the Agent Spec
+Collect or infer these fields, using safe defaults where reasonable:
+- `name`: lowercase kebab-case, under 64 characters.
+- `description`: trigger-focused; state exactly when to use the agent.
+- `instructions`: role, workflow, constraints, and output contract.
+- `clients`: target clients.
+- `scope`: `project` by default; use `user` only when the user asks for reusable personal agents.
+- `tools`: use the smallest useful set; prefer read-only for reviewers, researchers, planners, and auditors.
+- `model` and reasoning effort: omit unless the user asks or the client-specific reference gives a clear default.
+- `handoff`: what the parent agent should pass in and what the sub-agent must return.
+- `validation`: commands, checks, or review criteria the sub-agent should run or report.
+
+### 4. Generate Files
+Read `references/client-adapters.md` before generating client-specific files.
+
+For repeatable output, create a JSON spec and run:
+
+```bash
+uv run skills/neo-sub-agent/scripts/render-sub-agent.py --spec spec.json
+```
+
+If `uv` is not available and the script has no external dependencies, use:
+
+```bash
+python skills/neo-sub-agent/scripts/render-sub-agent.py --spec spec.json
+```
+
+Review the dry-run JSON. If the target paths and content are correct, write files:
+
+```bash
+uv run skills/neo-sub-agent/scripts/render-sub-agent.py --spec spec.json --write
+```
+
+Use `--force` only when replacing an existing agent file is explicitly intended.
+
+### 5. Review
+Before finalizing, check:
+- The agent has one narrow job and does not duplicate an existing agent.
+- The description is specific enough for automatic delegation.
+- Tool permissions match the role and avoid broad write/shell access when unnecessary.
+- The output contract is short, concrete, and easy for the parent agent to synthesize.
+- Antigravity output is labeled as a skill/delegation blueprint, not a custom sub-agent manifest.
+
+## Output Format
+When reporting back to the user, use Traditional Chinese (Taiwan):
+
+```markdown
+## 已新增
+- [client] `path/to/agent-file`
+
+## 設計重點
+- 角色：
+- 觸發條件：
+- 權限：
+- 回傳格式：
+
+## 驗證
+- `command`
+```
+
+## Constraints
+- Do not create broad "do everything" agents.
+- Do not give background agents write or shell access unless the task requires it.
+- Do not create multiple agents that can edit the same file set in parallel.
+- Do not treat model-generated review as a replacement for deterministic tests.

package/skills/neo-sub-agent/assets/templates/antigravity-skill.md

@@ -0,0 +1,25 @@
+---
+{{frontmatter}}
+---
+
+# {{title}}
+
+Use this skill as an Antigravity CLI delegation blueprint. It defines when the main agent should route work to a focused background specialist and what that specialist must return.
+
+## Compatibility Note
+This file is an Agent Skill / delegation blueprint for Antigravity CLI. It is not a native custom sub-agent manifest; no stable standalone custom sub-agent manifest format is assumed here.
+
+## Role
+{{instructions}}
+
+## Delegation Rules
+- Use this role only when the task matches the description.
+- Keep the delegated task bounded and self-contained.
+- Return a concise result to the parent conversation instead of full logs.
+- Ask the parent conversation for approval before destructive actions, broad rewrites, migrations, or production-impacting work.
+
+## Output Contract
+{{output_contract}}
+
+## Validation
+{{validation}}

package/skills/neo-sub-agent/assets/templates/claude-agent.md

@@ -0,0 +1,5 @@
+---
+{{frontmatter}}
+---
+
+{{instructions}}

package/skills/neo-sub-agent/assets/templates/codex-agent.toml

@@ -0,0 +1 @@
+{{toml}}

package/skills/neo-sub-agent/assets/templates/copilot-agent.md

@@ -0,0 +1,5 @@
+---
+{{frontmatter}}
+---
+
+{{instructions}}

package/skills/neo-sub-agent/evals/eval_queries.json

@@ -0,0 +1,50 @@
+[
+  {
+    "query": "幫我新增一個 sub agent，專門在 Claude Code 裡做 code review",
+    "should_trigger": true
+  },
+  {
+    "query": "Create a Codex explorer agent that maps auth flows without editing files",
+    "should_trigger": true
+  },
+  {
+    "query": "我要一個 Copilot CLI testing specialist custom agent",
+    "should_trigger": true
+  },
+  {
+    "query": "幫 AGY 做一個背景研究 agent skill，可以整理大量 log",
+    "should_trigger": true
+  },
+  {
+    "query": "設計 planner、worker、reviewer 的 multi-agent workflow",
+    "should_trigger": true
+  },
+  {
+    "query": "幫我把現有 Claude subagent 轉成 Codex custom agent",
+    "should_trigger": true
+  },
+  {
+    "query": "請解釋 sub-agent 什麼時候不該用，並幫我判斷這個場景",
+    "should_trigger": true
+  },
+  {
+    "query": "幫我新增一個 Python skill，不需要 sub-agent",
+    "should_trigger": false
+  },
+  {
+    "query": "修復這個 Vue component 的 RWD 排版",
+    "should_trigger": false
+  },
+  {
+    "query": "請 review 目前 git diff",
+    "should_trigger": false
+  },
+  {
+    "query": "幫我寫 Conventional Commit 訊息",
+    "should_trigger": false
+  },
+  {
+    "query": "查詢今天台北天氣",
+    "should_trigger": false
+  }
+]

package/skills/neo-sub-agent/evals/evals.json

@@ -0,0 +1,49 @@
+{
+  "skill_name": "neo-sub-agent",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "新增一個 Claude Code code-reviewer subagent，只能讀檔與搜尋，專門審查 correctness/security/tests。",
+      "expected_output": "產出 `.claude/agents/code-reviewer.md`，包含 `name`、trigger-focused `description`、read-only tools，以及明確的 findings-first review prompt。",
+      "assertions": [
+        "輸出檔案使用 Markdown YAML frontmatter",
+        "frontmatter 包含 name 與 description",
+        "工具權限不包含 edit 或 shell",
+        "prompt 要求先列出具體 findings 與檔案證據"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Create a Codex auth-flow-explorer custom agent. It should inspect auth code paths and never modify files.",
+      "expected_output": "產出 `.codex/agents/auth-flow-explorer.toml`，包含 required Codex fields and read-only sandbox guidance.",
+      "assertions": [
+        "TOML 包含 name、description、developer_instructions",
+        "sandbox_mode 設為 read-only 或 instructions 明確禁止修改",
+        "description 說明何時使用此 explorer",
+        "developer_instructions 要求回傳 concise mapped paths"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "做一個 Copilot CLI test-specialist custom agent，負責找測試缺口與補測試，不要碰 production code。",
+      "expected_output": "產出 `.github/agents/test-specialist.agent.md`，包含 Copilot custom agent frontmatter and a scoped testing prompt.",
+      "assertions": [
+        "輸出檔案副檔名為 `.agent.md`",
+        "frontmatter 至少包含 description",
+        "tools 權限限制合理",
+        "instructions 明確禁止修改 production code"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "幫 Antigravity CLI 建立 log-researcher 背景研究 agent，但不要假設有原生 manifest。",
+      "expected_output": "產出 `.agents/skills/log-researcher/SKILL.md` 作為 Antigravity delegation blueprint，並明確標示不是原生 custom sub-agent manifest。",
+      "assertions": [
+        "輸出是 Agent Skill 格式且第一行為 YAML frontmatter",
+        "description 說明背景研究與大量 log 整理用途",
+        "內容包含 delegation rules",
+        "明確指出 Antigravity 原生 custom sub-agent manifest 資料不足"
+      ]
+    }
+  ]
+}

package/skills/neo-sub-agent/evals/files/sample-sub-agent-spec.json

@@ -0,0 +1,19 @@
+{
+  "clients": ["claude", "codex", "copilot", "agy"],
+  "scope": "project",
+  "name": "code-reviewer",
+  "description": "Reviews changed code for correctness, security, behavior regressions, and missing tests.",
+  "instructions": "You are a focused code reviewer. Prioritize correctness, security, behavior regressions, and missing tests. Return concrete findings first, each with file evidence and a suggested fix. Do not make code changes.",
+  "tools": {
+    "default": ["Read", "Grep", "Glob"],
+    "copilot": ["read", "search"]
+  },
+  "read_only": true,
+  "output_contract": [
+    "Findings ordered by severity",
+    "File paths and concrete evidence",
+    "Open questions only when they affect correctness",
+    "Test gaps and residual risk"
+  ],
+  "validation": ["npm test"]
+}

package/skills/neo-sub-agent/references/client-adapters.md

@@ -0,0 +1,133 @@
+# Client Adapter Reference
+
+Use this reference before writing any client-specific sub-agent/custom-agent file. If a user asks for a field not listed here and it is not discoverable in the local project, state that the data is insufficient.
+
+## Neutral Spec
+Use this shape as the internal planning format before rendering files:
+
+```json
+{
+  "clients": ["claude", "codex", "copilot", "agy"],
+  "scope": "project",
+  "name": "code-reviewer",
+  "description": "Reviews changed code for correctness, security, and missing tests.",
+  "instructions": "You are a code reviewer...",
+  "tools": ["Read", "Grep", "Glob"],
+  "model": null,
+  "output_contract": "Return findings first, with file paths and concrete evidence.",
+  "validation": ["npm test"]
+}
+```
+
+Use lowercase kebab-case for `name` to preserve cross-client compatibility.
+
+## Claude Code
+
+Verified format:
+- Project path: `.claude/agents/<name>.md`
+- User path: `~/.claude/agents/<name>.md`
+- File type: Markdown with YAML frontmatter and Markdown body.
+- Required frontmatter: `name`, `description`.
+- Useful optional fields: `tools`, `disallowedTools`, `model`, `permissionMode`, `maxTurns`, `skills`, `mcpServers`, `memory`, `background`, `effort`, `isolation`, `color`.
+- Body: system prompt for the subagent.
+
+Default choices:
+- Reviewer, planner, explorer: read-only tools.
+- Implementation worker: only include edit/shell tools when requested.
+- If model is unspecified, omit it so the subagent inherits the session default.
+
+Example:
+
+```markdown
+---
+name: code-reviewer
+description: Reviews code for correctness, security, and missing tests.
+tools: ["Read", "Grep", "Glob"]
+---
+
+You are a code reviewer...
+```
+
+## Codex
+
+Verified format:
+- Project path: `.codex/agents/<name>.toml`
+- User path: `~/.codex/agents/<name>.toml`
+- File type: standalone TOML custom agent file.
+- Required fields: `name`, `description`, `developer_instructions`.
+- Useful optional fields: `nickname_candidates`, `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, `skills.config`.
+- Related global settings live under `[agents]` in Codex config, such as `max_threads`, `max_depth`, and `job_max_runtime_seconds`.
+
+Default choices:
+- Explorer/reviewer/planner: `sandbox_mode = "read-only"` when the user wants a non-mutating agent.
+- Implementation worker: do not set `sandbox_mode` unless the user explicitly wants a different sandbox from the parent session.
+- Keep `max_depth` at the default unless the user explicitly needs recursive delegation.
+
+Example:
+
+```toml
+name = "code-reviewer"
+description = "Reviews code for correctness, security, and missing tests."
+sandbox_mode = "read-only"
+developer_instructions = "Review code like an owner..."
+```
+
+## GitHub Copilot CLI
+
+Verified format:
+- Project path: `.github/agents/<name>.agent.md` or `.github/agents/<name>.md`
+- User path: `~/.copilot/agents/<name>.agent.md`
+- File type: Markdown with YAML frontmatter and Markdown body.
+- Required frontmatter: `description`.
+- Useful optional fields: `name`, `target`, `tools`, `model`, `disable-model-invocation`, `user-invocable`, `mcp-servers`, `metadata`.
+- Tool aliases include `read`, `edit`, `search`, `execute`, `agent`, `web`, and `todo`; unsupported names are ignored by Copilot.
+
+Default choices:
+- Use `.agent.md` for clarity.
+- Include `name` for human display, but rely on filename for the agent ID.
+- Use `tools: ["read", "search"]` for reviewers and researchers unless edits are needed.
+
+Example:
+
+```markdown
+---
+name: code-reviewer
+description: Reviews changed code for correctness, security, and missing tests.
+tools: ["read", "search"]
+---
+
+You are a code reviewer...
+```
+
+## Antigravity CLI
+
+Verified facts:
+- Antigravity CLI supports runtime background subagents and an `/agents` panel.
+- Antigravity CLI supports workspace skills in `.agents/skills/`.
+- Antigravity CLI docs describe skills/plugins as the reusable customization path.
+
+Insufficient data:
+- No stable standalone custom sub-agent manifest format was verified for V1.
+
+V1 adapter:
+- Project path: `.agents/skills/<name>/SKILL.md`
+- User/global path: `~/.gemini/antigravity-cli/skills/<name>/SKILL.md`
+- Output type: Agent Skill delegation blueprint that instructs Antigravity to spawn or use a background specialist when appropriate.
+
+Default choices:
+- Label the output as a skill/delegation blueprint.
+- Include clear conditions for when to delegate to a background subagent.
+- Avoid claiming this creates a native Antigravity custom subagent manifest.
+
+Example:
+
+```markdown
+---
+name: code-reviewer
+description: Reviews changed code in Antigravity CLI by delegating review work to a focused background agent when appropriate.
+---
+
+# Code Reviewer
+
+Use this skill to run a focused code-review delegation...
+```

package/skills/neo-sub-agent/references/sub-agent-design.md

@@ -0,0 +1,96 @@
+# Sub-Agent Design Reference
+
+This reference summarizes verified sub-agent design principles for developer CLIs and multi-agent workflows. Use it when designing a new agent role, deciding if delegation is appropriate, or reviewing an existing agent setup.
+
+## Basis
+- Agent Skills specification: a skill is a directory with `SKILL.md`; `name` and `description` drive discovery; detailed instructions should use progressive disclosure.
+- Claude Code subagents: subagents run in isolated context windows with their own prompt, tool access, permissions, and optional model.
+- Codex subagents: Codex can spawn specialized agents in parallel and collect results; custom agents live in standalone TOML files.
+- GitHub Copilot CLI custom agents: custom agents are Markdown profiles that can be invoked manually, by prompt, or by inference.
+- Antigravity CLI docs: background subagents are runtime workers, while custom reusable behavior is documented through skills/plugins. No stable standalone custom sub-agent manifest was verified for V1.
+- ADK and LangGraph workflow docs: common patterns include routing, sequential pipelines, parallel fan-out/gather, evaluator-optimizer, and human-in-the-loop gates.
+
+## Good Sub-Agent Jobs
+- **Explorer**: read-only codebase mapping, dependency tracing, API discovery, log summarization.
+- **Planner**: research and produce an implementation plan without editing.
+- **Reviewer**: inspect diffs or files for correctness, security, tests, and regressions.
+- **Executor**: perform bounded implementation from a clear spec.
+- **Test runner**: run builds/tests and return failures with concise diagnostics.
+- **Docs researcher**: verify current API behavior from official docs and return citations.
+- **Migration auditor**: inspect many modules independently and return structured risk notes.
+
+## Decision Rules
+- Use sub-agents for context isolation, parallel independent work, specialized repeated roles, scoped permissions, or fresh review.
+- Use the main conversation for small fixes, tightly sequential work, tasks needing repeated user clarification, or same-file edits.
+- Use a skill instead of a sub-agent when the goal is reusable instructions inside the main context.
+- Use a workflow/pipeline when order matters more than autonomy.
+
+## Design Patterns
+
+### Coordinator / Router
+A main agent routes tasks to named specialists. Use when user requests fall into clear categories and each specialist has a distinct description.
+
+Required decisions:
+- Routing descriptions must be mutually distinguishable.
+- The coordinator owns final synthesis unless the client uses handoff semantics.
+- Specialists must return concise, structured outputs.
+
+### Parallel Fan-Out / Gather
+Run multiple independent agents at the same time and combine results. Use for module audits, multi-area research, PR review dimensions, or batch checks.
+
+Required decisions:
+- Each worker must have independent input.
+- Avoid parallel writes to the same files.
+- Cap concurrency when the client supports it.
+- Ask workers to return fixed fields so synthesis is cheap.
+
+### Sequential Pipeline
+Run agents in a fixed order: explore -> plan -> implement -> test -> review. Use when each stage produces an artifact the next stage consumes.
+
+Required decisions:
+- Define the artifact passed between stages.
+- Stop at human approval gates for product scope, destructive actions, migrations, and production changes.
+- Do not pretend a later reviewer can recover missing context if the prior artifact is vague.
+
+### Generator / Critic
+One agent generates an artifact and another reviews it. Use for plans, docs, tests, migrations, prompts, and generated configuration.
+
+Required decisions:
+- Reviewer criteria must be explicit.
+- The critic should cite evidence and avoid style-only feedback unless it hides risk.
+- The parent agent decides whether to apply changes.
+
+### Human-In-The-Loop
+Use for irreversible operations, security changes, permissions, production deploys, and broad rewrites.
+
+Required decisions:
+- State exactly what requires user approval.
+- Background agents should fail safely when they cannot ask for approval.
+- The final output must distinguish completed work from pending approvals.
+
+## Prompt Design Checklist
+- Start with a single role sentence.
+- Include "use when" behavior in the description, not only the body.
+- State allowed scope and explicit non-goals.
+- State expected inputs from the parent agent.
+- State output shape: summary, findings, changed files, commands, risks, next steps.
+- Include permission constraints in the agent config when the client supports them.
+- Prefer read-only tools for planning, review, research, and audit agents.
+- Include validation commands only when they are discoverable or user-provided.
+
+## Anti-Patterns
+- A catch-all "senior engineer" agent with all tools and no narrow trigger.
+- Many overlapping specialists whose descriptions compete for the same prompts.
+- Background agents that require frequent questions.
+- Parallel agents editing the same files.
+- Recursive delegation without a hard depth/concurrency limit.
+- Agents that return full logs instead of summaries and cited evidence.
+- Client-specific fields copied across tools without checking support.
+
+## Review Checklist
+- The agent can be named in one sentence.
+- The description contains concrete trigger words users will actually type.
+- Permissions are minimal for the job.
+- The output contract is stable enough for the parent agent to synthesize.
+- The agent states what it must not do.
+- The design includes a validation or acceptance signal.

package/skills/neo-sub-agent/scripts/render-sub-agent.py

@@ -0,0 +1,401 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+
+"""Render cross-client sub-agent files from a JSON spec.
+
+Diagnostics go to stderr. JSON output goes to stdout.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+CLIENT_ALIASES = {
+    "claude": "claude",
+    "claude-code": "claude",
+    "codex": "codex",
+    "copilot": "copilot",
+    "copilot-cli": "copilot",
+    "agy": "agy",
+    "antigravity": "agy",
+    "antigravity-cli": "agy",
+}
+
+ALL_CLIENTS = ["claude", "codex", "copilot", "agy"]
+SAFE_NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+
+
+class SpecError(ValueError):
+    """Raised when the input spec is invalid."""
+
+
+def log(message: str) -> None:
+    print(message, file=sys.stderr)
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise SpecError(f"spec file not found: {path}") from exc
+    except json.JSONDecodeError as exc:
+        raise SpecError(f"spec is not valid JSON: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise SpecError("spec root must be a JSON object")
+    return data
+
+
+def normalize_clients(value: Any) -> list[str]:
+    if value is None:
+        raise SpecError("spec.clients is required")
+    raw = value if isinstance(value, list) else [value]
+    clients: list[str] = []
+    for item in raw:
+        if not isinstance(item, str):
+            raise SpecError("spec.clients must contain strings")
+        key = item.strip().lower()
+        if key == "all":
+            for client in ALL_CLIENTS:
+                if client not in clients:
+                    clients.append(client)
+            continue
+        client = CLIENT_ALIASES.get(key)
+        if not client:
+            raise SpecError(f"unsupported client: {item}")
+        if client not in clients:
+            clients.append(client)
+    if not clients:
+        raise SpecError("spec.clients must not be empty")
+    return clients
+
+
+def validate_spec(spec: dict[str, Any]) -> dict[str, Any]:
+    name = spec.get("name")
+    description = spec.get("description")
+    instructions = (
+        spec.get("instructions")
+        or spec.get("prompt")
+        or spec.get("developer_instructions")
+    )
+    if not isinstance(name, str) or not name:
+        raise SpecError("spec.name is required")
+    if len(name) > 64 or not SAFE_NAME_RE.match(name):
+        raise SpecError("spec.name must be lowercase kebab-case, 1-64 chars")
+    if not isinstance(description, str) or not description.strip():
+        raise SpecError("spec.description is required")
+    if len(description) > 1024:
+        raise SpecError("spec.description must be 1024 chars or less")
+    if not isinstance(instructions, str) or not instructions.strip():
+        raise SpecError("spec.instructions is required")
+
+    scope = spec.get("scope", "project")
+    if scope not in ("project", "user"):
+        raise SpecError("spec.scope must be 'project' or 'user'")
+
+    normalized = dict(spec)
+    normalized["clients"] = normalize_clients(spec.get("clients"))
+    normalized["scope"] = scope
+    normalized["instructions"] = instructions.strip()
+    normalized["description"] = description.strip()
+    normalized["name"] = name
+    return normalized
+
+
+def json_yaml(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (list, dict)):
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, (int, float)):
+        return str(value)
+    return json.dumps(str(value), ensure_ascii=False)
+
+
+def yaml_frontmatter(fields: list[tuple[str, Any]]) -> str:
+    lines = []
+    for key, value in fields:
+        if value is None:
+            continue
+        if value == [] or value == {}:
+            lines.append(f"{key}: {json_yaml(value)}")
+            continue
+        if value == "":
+            continue
+        lines.append(f"{key}: {json_yaml(value)}")
+    return "\n".join(lines)
+
+
+def toml_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, list):
+        return json.dumps(value, ensure_ascii=False)
+    return json.dumps(str(value), ensure_ascii=False)
+
+
+def toml_document(fields: list[tuple[str, Any]], tables: dict[str, Any] | None = None) -> str:
+    lines = []
+    for key, value in fields:
+        if value is None or value == "":
+            continue
+        lines.append(f"{key} = {toml_value(value)}")
+
+    if tables:
+        for table_name, table_value in tables.items():
+            if not isinstance(table_value, dict):
+                continue
+            lines.append("")
+            lines.append(f"[mcp_servers.{table_name}]")
+            for key, value in table_value.items():
+                if isinstance(value, dict):
+                    log(f"skipping nested mcp_servers.{table_name}.{key}; render manually")
+                    continue
+                lines.append(f"{key} = {toml_value(value)}")
+    return "\n".join(lines) + "\n"
+
+
+def template(name: str) -> str:
+    root = Path(__file__).resolve().parents[1]
+    return (root / "assets" / "templates" / name).read_text(encoding="utf-8")
+
+
+def get_tools(spec: dict[str, Any], client: str) -> Any:
+    tools = spec.get("tools")
+    if tools is None:
+        return None
+    if isinstance(tools, dict):
+        return tools.get(client) or tools.get("default")
+    return tools
+
+
+def output_contract(spec: dict[str, Any]) -> str:
+    value = spec.get("output_contract")
+    if isinstance(value, list):
+        return "\n".join(f"- {item}" for item in value)
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return "- Summary\n- Evidence or changed files\n- Risks\n- Suggested next steps"
+
+
+def validation(spec: dict[str, Any]) -> str:
+    value = spec.get("validation")
+    if isinstance(value, list):
+        return "\n".join(f"- `{item}`" for item in value)
+    if isinstance(value, str) and value.strip():
+        return f"- `{value.strip()}`"
+    return "- State any checks run. If no deterministic check is available, say so explicitly."
+
+
+def target_path(client: str, spec: dict[str, Any], output_root: Path) -> Path:
+    name = spec["name"]
+    scope = spec["scope"]
+    if scope == "user":
+        home = Path.home()
+        if client == "claude":
+            return home / ".claude" / "agents" / f"{name}.md"
+        if client == "codex":
+            return home / ".codex" / "agents" / f"{name}.toml"
+        if client == "copilot":
+            return home / ".copilot" / "agents" / f"{name}.agent.md"
+        if client == "agy":
+            return home / ".gemini" / "antigravity-cli" / "skills" / name / "SKILL.md"
+
+    if client == "claude":
+        return output_root / ".claude" / "agents" / f"{name}.md"
+    if client == "codex":
+        return output_root / ".codex" / "agents" / f"{name}.toml"
+    if client == "copilot":
+        return output_root / ".github" / "agents" / f"{name}.agent.md"
+    if client == "agy":
+        return output_root / ".agents" / "skills" / name / "SKILL.md"
+    raise SpecError(f"unsupported client: {client}")
+
+
+def render_claude(spec: dict[str, Any]) -> str:
+    fm = yaml_frontmatter(
+        [
+            ("name", spec["name"]),
+            ("description", spec["description"]),
+            ("tools", get_tools(spec, "claude")),
+            ("disallowedTools", spec.get("disallowed_tools") or spec.get("disallowedTools")),
+            ("model", spec.get("model")),
+            ("permissionMode", spec.get("permission_mode") or spec.get("permissionMode")),
+            ("maxTurns", spec.get("max_turns") or spec.get("maxTurns")),
+            ("skills", spec.get("skills")),
+            ("mcpServers", spec.get("mcp_servers") or spec.get("mcpServers")),
+            ("memory", spec.get("memory")),
+            ("background", spec.get("background")),
+            ("effort", spec.get("effort")),
+            ("isolation", spec.get("isolation")),
+            ("color", spec.get("color")),
+        ]
+    )
+    return template("claude-agent.md").replace("{{frontmatter}}", fm).replace(
+        "{{instructions}}", spec["instructions"]
+    )
+
+
+def render_codex(spec: dict[str, Any]) -> str:
+    sandbox_mode = spec.get("sandbox_mode")
+    if sandbox_mode is None and spec.get("read_only"):
+        sandbox_mode = "read-only"
+    doc = toml_document(
+        [
+            ("name", spec["name"].replace("-", "_") if spec.get("codex_use_underscores") else spec["name"]),
+            ("description", spec["description"]),
+            ("model", spec.get("model")),
+            ("model_reasoning_effort", spec.get("model_reasoning_effort")),
+            ("sandbox_mode", sandbox_mode),
+            ("developer_instructions", spec["instructions"]),
+            ("nickname_candidates", spec.get("nickname_candidates")),
+        ],
+        spec.get("mcp_servers"),
+    )
+    return template("codex-agent.toml").replace("{{toml}}", doc)
+
+
+def render_copilot(spec: dict[str, Any]) -> str:
+    disable_model_invocation = spec.get("disable_model_invocation")
+    if disable_model_invocation is None and spec.get("auto_delegate") is False:
+        disable_model_invocation = True
+    fm = yaml_frontmatter(
+        [
+            ("name", spec.get("display_name") or spec["name"]),
+            ("description", spec["description"]),
+            ("target", spec.get("target")),
+            ("tools", get_tools(spec, "copilot")),
+            ("model", spec.get("model")),
+            ("disable-model-invocation", disable_model_invocation),
+            ("user-invocable", spec.get("user_invocable")),
+            ("mcp-servers", spec.get("mcp_servers")),
+            ("metadata", spec.get("metadata")),
+        ]
+    )
+    return template("copilot-agent.md").replace("{{frontmatter}}", fm).replace(
+        "{{instructions}}", spec["instructions"]
+    )
+
+
+def render_agy(spec: dict[str, Any]) -> str:
+    fm = yaml_frontmatter(
+        [
+            ("name", spec["name"]),
+            ("description", spec["description"]),
+        ]
+    )
+    title = spec.get("display_name") or spec["name"].replace("-", " ").title()
+    return (
+        template("antigravity-skill.md")
+        .replace("{{frontmatter}}", fm)
+        .replace("{{title}}", title)
+        .replace("{{instructions}}", spec["instructions"])
+        .replace("{{output_contract}}", output_contract(spec))
+        .replace("{{validation}}", validation(spec))
+    )
+
+
+def render(client: str, spec: dict[str, Any]) -> tuple[str, list[str]]:
+    warnings: list[str] = []
+    if client == "claude":
+        return render_claude(spec), warnings
+    if client == "codex":
+        return render_codex(spec), warnings
+    if client == "copilot":
+        return render_copilot(spec), warnings
+    if client == "agy":
+        warnings.append(
+            "Antigravity output is a skill/delegation blueprint; no verified native custom sub-agent manifest is rendered."
+        )
+        return render_agy(spec), warnings
+    raise SpecError(f"unsupported client: {client}")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Render Claude, Codex, Copilot CLI, and Antigravity sub-agent files from JSON."
+    )
+    parser.add_argument("--spec", required=True, help="Path to JSON spec.")
+    parser.add_argument(
+        "--output-root",
+        default=".",
+        help="Project root for project-scoped outputs. Default: current directory.",
+    )
+    parser.add_argument(
+        "--write",
+        action="store_true",
+        help="Write files. Omit for dry-run JSON output only.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing files when used with --write.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        spec = validate_spec(read_json(Path(args.spec)))
+        output_root = Path(args.output_root).resolve()
+        generated = []
+        all_warnings: list[str] = []
+
+        for client in spec["clients"]:
+            content, warnings = render(client, spec)
+            path = target_path(client, spec, output_root)
+            all_warnings.extend(warnings)
+            item = {
+                "client": client,
+                "target_path": str(path),
+                "content": content,
+                "warnings": warnings,
+            }
+            generated.append(item)
+
+        if args.write:
+            for item in generated:
+                path = Path(item["target_path"])
+                if path.exists() and not args.force:
+                    raise SpecError(f"target already exists; use --force to overwrite: {path}")
+            for item in generated:
+                path = Path(item["target_path"])
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(item["content"], encoding="utf-8", newline="\n")
+                log(f"wrote {path}")
+
+        result = {
+            "status": "written" if args.write else "dry-run",
+            "generated": generated,
+            "warnings": all_warnings,
+        }
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+    except SpecError as exc:
+        print(
+            json.dumps({"status": "error", "error_message": str(exc)}, ensure_ascii=False, indent=2)
+        )
+        log(f"error: {exc}")
+        return 3
+    except OSError as exc:
+        print(
+            json.dumps({"status": "error", "error_message": str(exc)}, ensure_ascii=False, indent=2)
+        )
+        log(f"write error: {exc}")
+        return 5
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())