Agent Skills › agent-sh/agentsys › maintain-cross-platform

maintain-cross-platform

GitHub

维护 AgentSys 跨平台兼容性，处理多环境安装、适配转换及发布流程。

meta/skills/maintain-cross-platform/SKILL.md agent-sh/agentsys

Trigger Scenarios

准备 AgentSys 版本发布检查跨平台兼容性修改安装程序或适配器

Install

npx skills add agent-sh/agentsys --skill maintain-cross-platform -g -y

More Options

Non-standard path

npx skills add https://github.com/agent-sh/agentsys/tree/main/meta/skills/maintain-cross-platform -g -y

Use without installing

npx skills use agent-sh/agentsys@maintain-cross-platform

指定 Agent (Claude Code)

npx skills add agent-sh/agentsys --skill maintain-cross-platform -a claude-code -g -y

安装 repo 全部 skill

npx skills add agent-sh/agentsys --all -g -y

预览 repo 内 skill

npx skills add agent-sh/agentsys --list

SKILL.md

Frontmatter

{
    "name": "maintain-cross-platform",
    "metadata": {
        "scope": "local",
        "audience": "repo-maintainers",
        "short-description": "Maintain AgentSys across its five platforms"
    },
    "description": "Use when preparing an AgentSys release, checking cross-platform compatibility, or changing the installer, transforms, adapters or marketplace pins. Maintainer skill for this repo only."
}

Maintain cross-platform AgentSys

AgentSys installs the agent-sh plugins on Claude Code, OpenCode, Codex CLI, Cursor and Kiro. The plugins live in their own repos; this repo owns the marketplace, the installer, the transforms and the docs. Use this skill to find where a cross-platform concern lives and what to run.

Platform details (config formats, frontmatter, env vars, label limits) are in checklists/cross-platform-compatibility.md and docs/CROSS_PLATFORM.md; release steps are in checklists/release.md and agent-docs/release.md. Read them for the current facts instead of relying on memory.

Where things live

Concern	Location
Marketplace, one entry per plugin pinned by tag and commit	`.claude-plugin/marketplace.json`; re-pin with `node scripts/pin-marketplace.js [--dry-run]` (needs `gh`)
Installer	`bin/cli.js`: `installForClaude`, `installForOpenCode`, `installForCodex`, `installForCursor`, `installForKiro`. Claude Code installs from the marketplace; the others fetch plugin sources into `~/.agentsys/plugins/<name>` and transform them.
Transforms (frontmatter, tools to permissions, plugin-root paths, namespaces)	`lib/adapter-transforms.js`. `lib/` is synced from agent-sh/agent-core, so make the change there; an edit here is overwritten by the next sync.
Platform adapters	`adapters/opencode-plugin/` (native OpenCode plugin), `adapters/opencode/`, `adapters/codex/`; `scripts/gen-adapters.js` keeps generated files fresh
Dev installs	`node bin/dev-cli.js dev-install [tool]` (`scripts/dev-install.js`)
Versions	`package.json` is the source; `npx agentsys-dev bump X.Y.Z` stamps `package-lock.json`, `.claude-plugin/plugin.json`, `marketplace.json` and `site/content.json`. Plugin repos version independently.
Generated doc sections	`<!-- GEN:START:... -->` blocks, rewritten by `npx agentsys-dev gen-docs`

Platform differences behind most bugs

Plugin root: ${CLAUDE_PLUGIN_ROOT} in Claude Code, ${PLUGIN_ROOT} in OpenCode and Codex; Cursor and Kiro get the install path inlined. Normalize backslashes in require() paths (.replace(/\\/g, '/')), because a Windows path such as C:\Users\... turns into escape sequences.
State directory: use AI_STATE_DIR (.opencode, .codex, .cursor, .kiro; unset means .claude) instead of a hardcoded .claude/. validate paths catches hardcoded ones.
OpenCode: model fields are stripped by default (--no-strip keeps them), tools become permission: entries, and AskUserQuestion labels longer than 30 characters fail.
Codex has no commands or agents: commands become skills invoked as $name, so every skill description needs trigger phrases ("Use when ...").
Kiro: commands become prompts in ~/.kiro/prompts/, agents become JSON in ~/.kiro/agents/, and two combined reviewer agents fit its 4-subagent limit. Each skill directory is copied whole to ~/.kiro/skills/<name>/, away from its plugin, so the installer and the Kiro transforms point plugin-root wording ("two directories up from this skill"), relative links that leave the skill directory, and versioned-cache globs (**/<plugin>/*/) at ~/.agentsys/plugins/<plugin>.

Checks

Command	Covers
`npm run validate`	plugins, cross-platform, consistency, paths, counts, platform-docs, agent-skill-compliance
`npm test`	Jest suite
`npm run gen-docs:check`, `node scripts/expand-templates.js --check`, `node scripts/gen-adapters.js --check`	Generated content is fresh (CI runs all three)
`npx agentsys-dev preflight [--all\|--release]`	Change-aware checklist checks. The pre-push hook runs it, asks for the `/enhance` confirmation, and runs `--release` when a `v*` tag is pushed.
`node bin/dev-cli.js validate opencode-install`	A real OpenCode install (not part of `validate`)
`npm pack --dry-run`	The package builds

Before a release, smoke-test the installer: npm pack, npm install -g ./agentsys-*.tgz, run agentsys, and check each platform's install directory as checklists/release.md lists.

If this skill or a checklist no longer matches the code, fix it in the same change.

Output

## Cross-Platform Compatibility Check

### Validations run
- [OK|ERROR] <validator>: <one line>

### Issues
- <file:line>: <problem> - <fix>

### Docs out of date
- <file>: <what no longer matches>

### Actions taken
- <files changed>

### Next steps
- <remaining work, or "none">

Version History

bf810e9 Current 2026-10-19 14:05
统一各平台技能目录安装方式，移除 Kiro 镜像，修复 Codex 技能安装问题。
abdccee 2026-09-28 06:04
将仓库指令整合至 AGENTS.md，统一维护清单与共享平台文档。
a0b2c8d 2026-08-20 05:53
删除废弃的install.sh脚本，移除相关文档，统一使用CLI作为唯一安装路径。
a92c0cb 2026-07-25 11:25

Metadata

Files: 0
Version: bf810e9
Hash: 0bc3c051
Indexed: 2026-07-25 11:25

maintain-cross-platform