Merge remote-tracking branch 'origin/main' into feat/20260604-issue-26-sim-screenshot-orientation

# Conflicts:
#	docs-linhay/memory/2026-06-04.md

Author: linhay

README.md

@@ -15,6 +15,35 @@ Before filing a public issue, redact private project and personal information. D
 | Build, test, run, and diagnose an unknown Apple repo | [CLI Integration Guide](#cli-integration-guide) | Use `triton xcode`, `triton xcresult`, and artifact commands before raw `xcodebuild`. |
 | Prepare a HarmonyOS / DevEco Emulator | [Harmony App Integration Guide](#harmony-app-integration-guide) | Host-side HDC adapter works without embedded runtime. |
 | Validate a Harmony embedded runtime | [Harmony App Integration Guide](#harmony-app-integration-guide) | Use package id / import path `tritonkit` and `--runtime-base-url` direct checks while the SDK is standalone. |
+| Add optional Codex / agent workflows | [Optional Agent Skills](#optional-agent-skills) | Install only the public skills; internal skills are for TritonKit repository maintenance. |
+
+## Optional Agent Skills
+
+TritonKit ships optional Codex / agent skills for AI-assisted adoption, feedback, and local emulator regression work. They are not required to use the iOS runtime, Harmony runtime notes, or macOS `triton` CLI.
+
+External users and adopting projects should install only the public skills from `.agents/tritonkit-skills/public/` or from the release asset `tritonkit-skills.tar.gz`. Current public skills are:
+
+- `tritonkit-dev-feedback`: collect adoption feedback, missing capabilities, confusing behavior, and documentation gaps as actionable TritonKit issues.
+- `tritonkit-emulator-cli-takeover`: guide local CLI takeover of iOS Simulator, Android Emulator, and HarmonyOS / DevEco Emulator workflows.
+- `tritonkit-real-project-regression`: validate TritonKit against real app projects while isolating external repo changes and preserving machine-readable evidence.
+
+Do not install `.agents/tritonkit-skills/internal/` into adopting projects by default. Internal skills are repo-maintenance, governance, planning, supervision, and implementation workflows for TritonKit maintainers, and release packaging excludes them.
+
+If you install from a source checkout, copy only the public skill directories into your Codex / agent skills directory:
+
+```sh
+# Replace AGENT_SKILLS_DIR with your Codex / agent's configured skills directory.
+mkdir -p "$AGENT_SKILLS_DIR"
+cp -R .agents/tritonkit-skills/public/* "$AGENT_SKILLS_DIR"/
+```
+
+If you install from a release asset, extract the public skill bundle into that same configured skills directory:
+
+```sh
+tar -xzf tritonkit-skills.tar.gz -C "$AGENT_SKILLS_DIR"
+```
+
+Restart the Codex / agent session after installation so the new skills are discovered.
 
 ## iOS Embedded Runtime Integration Guide
 

docs-linhay/memory/2026-06-04.md

@@ -1,3 +1,9 @@
+# 2026-06-04
+
+## Issue #27 Optional Agent Skills README
+
+- 为 `docs-linhay/spaces/20260604-issue-27-agent-skills-readme/` 建立执行计划，验收聚焦根 README 是否明确可选 Codex / agent skills 的 public/internal 边界。
+- 根 README 新增 `Optional Agent Skills` 章节：外部用户只安装 `.agents/tritonkit-skills/public/` 或 release asset `tritonkit-skills.tar.gz` 中的 public skills；当前 public skills 为 `tritonkit-dev-feedback`、`tritonkit-emulator-cli-takeover`、`tritonkit-real-project-regression`；`.agents/tritonkit-skills/internal/` 仅用于 TritonKit repo maintenance，不默认安装到 adopting projects；安装后需重启 Codex / agent session。
 
 ## Issue 26 simulator screenshot orientation metadata
 

docs-linhay/spaces/20260604-issue-27-agent-skills-readme/README.md

@@ -0,0 +1,33 @@
+# Issue 27 - Clarify optional Codex/agent skills installation in README
+
+## 背景
+
+GitHub Issue #27 指出：根 README 已覆盖 iOS embedded runtime、macOS CLI 与 Harmony / DevEco 集成路径，但没有明显说明 TritonKit 随附的可选 Codex/agent skills 安装路径，外部采用项目容易遗漏自动化指导。
+
+## 目标
+
+- 在根 README 的集成/安装说明中增加简短的 Optional Agent Skills 说明。
+- 明确外部用户只安装 `.agents/tritonkit-skills/public/` 下的 public skills。
+- 明确 `.agents/tritonkit-skills/internal/` 仅用于 TritonKit 仓库维护，不应作为外部项目默认安装内容。
+- 提醒安装后重启 Codex / agent session 以重新发现 skills。
+
+## 非目标
+
+- 不改动 skill 打包逻辑。
+- 不新增 Web/Wails UI。
+- 不改动 CLI/HTTP 业务契约。
+
+## BDD 场景与验收
+
+### 场景：外部采用者从根 README 发现可选 agent skills
+
+Given 外部采用者阅读根 README
+When 查找 TritonKit 可选自动化/agent 指南
+Then README 应展示 Optional Agent Skills 章节
+And 列出 public skill 路径
+And 说明 internal skills 不面向外部默认安装
+And 提醒安装后重启 Codex / agent session
+
+## 相关链接
+
+- GitHub Issue: https://github.com/NeptuneKit/TritonKit/issues/27

docs-linhay/spaces/20260604-issue-27-agent-skills-readme/plans/implementation.md

@@ -0,0 +1,18 @@
+# Issue 27 实施计划
+
+## BDD 验收
+
+- Given 外部采用者阅读根 README
+- When 查找 TritonKit 可选 Codex / agent skills 安装说明
+- Then README 展示 `Optional Agent Skills` 章节
+- And 明确 public skill 源路径 `.agents/tritonkit-skills/public/` 与 release asset `tritonkit-skills.tar.gz`
+- And 列出当前 public skills：`tritonkit-dev-feedback`、`tritonkit-emulator-cli-takeover`、`tritonkit-real-project-regression`
+- And 说明 `.agents/tritonkit-skills/internal/` 仅用于 TritonKit repo maintenance，不默认安装到 adopting projects
+- And 提醒安装后重启 Codex / agent session
+
+## 执行步骤
+
+1. 阅读 space README、根 README、`.agents/tritonkit-skills/README.md` 与 public skill front matter，确认 packaging 只包含 public skills。
+2. 在根 README 集成路径表后补充 `Optional Agent Skills` 章节。
+3. 运行 `docs-linhay/scripts/check-docs.sh` 做纯文档结构校验。
+4. 写回 memory 并提交本地 commit。