ai-cli-helper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI CLI helper

AI CLI助手

Overview

概述

This skill manages configuration and skills for AI agent CLI tools (Claude Code, Opencode). It understands the full config stack — from user settings through project and local scopes — and can inspect, modify, debug, synchronize, and research configuration across both tools.

Use this skill when:

Installing, updating, or managing skills
Inspecting or modifying configs at any scope
Debugging config conflicts, scope issues, or skill activation failures
Comparing or syncing settings between Claude Code and Opencode
Researching latest upstream config options and applying them

该技能用于管理AI Agent CLI工具（Claude Code、Opencode）的配置与技能。它支持完整的配置栈识别——从用户设置到项目和本地作用域——可对两款工具的配置进行查看、修改、调试、同步及调研操作。

适用于以下场景：

安装、更新或管理技能
查看或修改任意作用域的配置
调试配置冲突、作用域问题或技能激活失败
对比或同步Claude Code与Opencode之间的设置
调研最新的上游配置选项并应用

Context

背景

The user runs both Claude Code and Opencode, managed declaratively (e.g. via Nix, dotfiles, etc.). Both tools share agent instructions (AGENTS.md) and skills via

.agents/skills/

. The detailed setup for each tool is documented in the references/ directory.

用户同时使用Claude Code和Opencode，采用声明式管理（例如通过Nix、dotfiles等）。两款工具通过

.agents/skills/

共享Agent指令（AGENTS.md）和技能。每款工具的详细设置说明记录在references/目录下。

Process

流程

IMPORTANT: for skill install/remove requests where the user gives specific paths or names, go directly to the manage-skills subskill and execute. Do NOT read references, explore the codebase, or assess state first. Run the right command directly:

npx skills

for remote sources and

local-skills.py

for local filesystem sources.

For everything else:

Inspection/debugging: read the relevant reference doc, then read config files
Config modifications: see manage-configs subskill
Skill operations (open-ended): see manage-skills subskill
Research: delegate to web-research skill
Verify results after changes

重要提示：若用户的技能安装/移除请求提供了明确的路径或名称，请直接调用manage-skills子技能执行。无需先查阅参考文档、浏览代码库或评估状态。直接运行对应命令：远程源使用

npx skills

，本地文件系统源使用

local-skills.py

。

其他场景处理规则：

查看/调试：先阅读相关参考文档，再读取配置文件
配置修改：参见manage-configs子技能
开放式技能操作：参见manage-skills子技能
调研：委托给web-research技能
变更后验证结果

Resources

资源

subskills/manage-skills.md: install, update, discover, and audit skills with a hybrid flow (
```
npx skills
```
for remote,
```
local-skills.py
```
for local)
subskills/manage-configs.md: inspect and modify config files, rebuild workflow, scope rules
references/opencode-config.md: Opencode config structure, config management, oh-my-opencode, agent modes
references/vercel-skills.md:
```
npx skills
```
CLI disk model, gotchas, recommended usage patterns
references/claude-code-plugins.md: legacy plugin system reference — for diagnosing plugin conflicts and cleaning up old installs only

subskills/manage-skills.md：通过混合流程安装、更新、发现和审计技能（远程源使用
```
npx skills
```
，本地源使用
```
local-skills.py
```
）
subskills/manage-configs.md：查看和修改配置文件、重构工作流、作用域规则
references/opencode-config.md：Opencode配置结构、配置管理、oh-my-opencode、Agent模式
references/vercel-skills.md：
```
npx skills
```
CLI磁盘模型、注意事项、推荐使用模式
references/claude-code-plugins.md：旧插件系统参考——仅用于诊断插件冲突和清理旧安装

Guidelines

指南

Skill management

技能管理

Use a hybrid model for skill activation:
- Remote skills (
```
owner/repo
```
  ) ->
```
npx skills
```
- Local monorepo skills (filesystem paths) ->
```
scripts/local-skills.py
```
  (
```
npx add
```
  bootstrap + symlink swap)
Never use
```
claude plugin install/remove/enable/disable
```
for managing skills — the plugin system is deprecated for this purpose

After skill changes, verify with both

npx skills list

and

scripts/local-skills.py list

For development iteration on monorepo skills, prefer
```
scripts/local-skills.py
```
because it symlinks instead of copying

技能激活采用混合模式：
- 远程技能（
```
owner/repo
```
  ）->
```
npx skills
```
- 本地 monorepo 技能（文件系统路径）->
```
scripts/local-skills.py
```
  （
```
npx add
```
  引导 + 符号链接切换）
禁止使用
```
claude plugin install/remove/enable/disable
```
管理技能——该插件系统已不再支持此用途

技能变更后，需同时通过

npx skills list

和

scripts/local-skills.py list

验证

针对monorepo技能的开发迭代，优先使用
```
scripts/local-skills.py
```
，因为它采用符号链接而非文件拷贝

Scope and editability

作用域与可编辑性

User-level settings may be declaratively managed (e.g. via Nix). See the manage-configs subskill before editing directly.
Project-level settings are checked into git and can be edited directly
Local settings (
```
.claude/settings.local.json
```
) are gitignored and can be edited directly
When unsure which scope to modify, prefer project scope

用户级设置可能采用声明式管理（例如通过Nix）。直接编辑前请查阅manage-configs子技能说明
项目级设置已提交到git，可直接编辑
本地设置（
```
.claude/settings.local.json
```
）被git忽略，可直接编辑
不确定修改哪个作用域时，优先选择项目作用域

Cross-tool awareness

跨工具注意事项

Claude Code and Opencode share skills via
```
.agents/skills/
```
(canonical store, managed by
```
npx skills
```
for remote skills and symlinks for local skills)
Both tools reference the same AGENTS.md
Config concepts overlap but syntax differs — always check both reference docs when comparing
Claude Code uses
```
settings.json
```
with hooks/permissions; Opencode uses
```
opencode.json
```
with agent modes and permission blocks

Claude Code和Opencode通过
```
.agents/skills/
```
共享技能（规范存储，远程技能由
```
npx skills
```
管理，本地技能通过符号链接管理）
两款工具引用同一个AGENTS.md
配置概念重叠但语法不同——对比时请务必同时查阅两份参考文档
Claude Code使用带钩子/权限配置的
```
settings.json
```
；Opencode使用带Agent模式和权限块的
```
opencode.json
```

Legacy plugin conflicts

旧插件冲突

Old plugins may still be installed from before the migration to
```
npx skills
```
If a skill isn't loading correctly or behavior is unexpected, check for stale
```
enabledPlugins
```
in settings.json and legacy entries in
```
~/.claude/plugins/installed_plugins.json
```
Use
```
references/claude-code-plugins.md
```
for the commands needed to inspect and uninstall legacy plugins
Run
```
claude plugin list
```
to check for stale plugin installs that may conflict

迁移到
```
npx skills
```
之前安装的旧插件可能仍存在
如果技能无法正常加载或行为异常，请检查settings.json中过时的
```
enabledPlugins
```
配置，以及
```
~/.claude/plugins/installed_plugins.json
```
中的旧条目
查阅
```
references/claude-code-plugins.md
```
获取查看和卸载旧插件所需的命令
运行
```
claude plugin list
```
检查可能导致冲突的过时插件安装

Research

调研

For upstream research, delegate to the web-research skill
Always tie findings back to "here's what this means for your setup" with specific file paths and scope recommendations
Check both https://docs.anthropic.com/en/docs/claude-code and https://opencode.ai/docs for official docs

上游调研请委托给web-research技能
输出结论时请结合用户的实际配置，给出具体的文件路径和作用域建议
请同时查阅官方文档https://docs.anthropic.com/en/docs/claude-code 和 https://opencode.ai/docs

General

通用规则

Only read reference docs when the task requires understanding config structure or debugging — not for straightforward install/remove operations
When presenting config state, show all three layers (user -> project -> local) to make precedence clear

仅当任务需要理解配置结构或调试时才查阅参考文档——简单的安装/移除操作无需查阅
展示配置状态时，请同时展示三层配置（用户 -> 项目 -> 本地），明确优先级

Appendix

附录

Quick reference: CLI commands

快速参考：CLI命令

bash

undefined

bash

undefined

Skill operations (remote/GitHub via npx skills)

npx skills list # show installed skills npx skills list -g # show global skills npx skills add owner/repo --skill name -a claude-code -y # install from GitHub npx skills remove --skill name -y # remove from all agents

Skill operations (local filesystem via local-skills.py)

./scripts/local-skills.py add ./path/to/my-skill -a claude-code opencode ./scripts/local-skills.py remove --skill my-skill -a claude-code opencode ./scripts/local-skills.py list

Discovery

./scripts/discover-skills.py /path/to/monorepo # writes unified discovery+activation manifest

Legacy plugin inspection (for debugging conflicts only)

claude plugin list # check for stale installs claude plugin uninstall name@marketplace --scope project # clean up legacy plugin

Opencode

opencode --version

Opencode plugins managed via oh-my-opencode.json and bun dependencies

undefined

undefined