已合并
docs: 新增 Skill 复用指南（面向无 cannbot 的外部开发者）(#195) #1371
高煜博创建于 7月20日
docs: 新增 Skill 复用指南（面向无 cannbot 的外部开发者）(#195) #1371
已合并
共 2 个文件变更+544-0
| @@ -0,0 +1,272 @@ | |||
| 1 | +# Graph-autofusion Skill Reuse Guide (for External Developers Without cannbot) | ||
| 2 | + | ||
| 3 | +## Overview | ||
| 4 | + | ||
| 5 | +This document is for **external developers without cannbot**, explaining how to reuse the Skills built into the graph-autofusion project: either integrate them into other AI tools (Claude Code / Cursor / GitHub Copilot, etc.) for automatic loading, or read them as a manual development guide. | ||
| 6 | + | ||
| 7 | +The project ships 17 built-in Skills in three categories: 6 general development Skills, 7 SuperKernel operator pipeline Skills, and 4 remote GitCode collaboration Skills. | ||
| 8 | + | ||
| 9 | +### Relationship with Other Documents | ||
| 10 | + | ||
| 11 | +| Document | Purpose | Audience | | ||
| 12 | +|----------|---------|----------| | ||
| 13 | +| [opencode-skill-management.md](../zh/opencode-skill-management.md) | Three-layer Skill architecture, management, contribution | Skill maintainers, contributors | | ||
| 14 | +| **This document** | **How to reuse built-in Skills without cannbot** | **External developers (integrating with other AI tools or manual reading)** | | ||
| 15 | + | ||
| 16 | +## Skill Overview | ||
| 17 | + | ||
| 18 | +### General Development Skills (6, git-tracked) | ||
| 19 | + | ||
| 20 | +| Skill | Purpose | Script Dependency | SKILL.md | | ||
| 21 | +|-------|---------|-------------------|----------| | ||
| 22 | +| `af-build-runner` | Build assistant (`build.sh` args, CMake errors, dependency matching) | None | [Link](../../.claude/skills/af-build-runner/SKILL.md) | | ||
| 23 | +| `af-test-developer` | UT/ST test development (gtest/mockcpp, pytest, coverage) | None | [Link](../../.claude/skills/af-test-developer/SKILL.md) | | ||
| 24 | +| `af-code-reviewer` | Code review and contribution standards (redlines, format, PR template) | None | [Link](../../.claude/skills/af-code-reviewer/SKILL.md) | | ||
| 25 | +| `af-reg-ascir` | ASCIR registration assistant (add/modify ops, dtype, tmp buffer, UT/ST gen) | None | [Link](../../.claude/skills/af-reg-ascir/SKILL.md) | | ||
 | |||
| 26 | +| `cann-toolkit-installer` | Auto-download and install CANN Toolkit (parsing, verify, silent install) | Embedded bash logic | [Link](../../.claude/skills/cann-toolkit-installer/SKILL.md) | | ||
| 27 | +| `default-skills` | Default remote Skill installation entry | `scripts/install-default-skills.sh` | [Link](../../.claude/skills/default-skills/SKILL.md) | | ||
| 28 | + | ||
| 29 | +### SuperKernel Operator Pipeline Skills (7, master branch only) | ||
| 30 | + | ||
| 31 | +> These 7 Skills are currently available only on the `master` branch; the `develop` branch does not include them yet. The `SKILL.md` column below has no link; switch to the `master` branch or view via the GitCode web interface. | ||
| 32 | + | ||
| 33 | +| Skill | Purpose | Script Dependency | SKILL.md | | ||
| 34 | +|-------|---------|-------------------|----------| | ||
| 35 | +| `sk-operator-pipeline` | SK operator delivery pipeline entry (routing, index) | `scripts/` | master branch | | ||
| 36 | +| `sk-operator-asset-adapter` | Operator asset adaptation (user dir → JSON contract) | `scripts/*.py` | master branch | | ||
| 37 | +| `sk-operator-validate` | Asset contract validation (contract, source, compatibility) | `scripts/` | master branch | | ||
| 38 | +| `sk-operator-codegen` | SK binding code generation (Args struct + `__sk__` + SK_BIND) | `scripts/` | master branch | | ||
| 39 | +| `sk-operator-sample-gen` | Sample generation and validation contract (input, oracle, runner) | `scripts/` | master branch | | ||
| 40 | +| `sk-operator-build-package` | SK/ACLGraph build and package (bisheng compile → wheel) | `scripts/*.py` | master branch | | ||
| 41 | +| `sk-model-analysis` | Full-network diagnosis (hang/coredump, perf analysis, visualization) | `scripts/*.py` | master branch | | ||
| 42 | + | ||
| 43 | +### Remote GitCode Collaboration Skills (4, auto-installed) | ||
| 44 | + | ||
| 45 | +> These 4 Skills are NOT in git; install first (see "Reuse Notes - Remote Skill Installation"). | ||
| 46 | + | ||
| 47 | +| Skill | Purpose | Trigger Scenarios | | ||
| 48 | +|-------|---------|-------------------| | ||
| 49 | +| `gitcode-pr` | Create PR, fetch comments, view discussions | Create PR, view PR changes, get PR comments | | ||
| 50 | +| `gitcode-issue` | Read issue details and comments | View issue, read issue comments | | ||
| 51 | +| `gitcode-pipeline` | Trigger pipeline and monitor status | Trigger pipeline, watch CI, view pipeline status | | ||
| 52 | +| `api-doc-generator` | Generate API documentation | Generate API docs, add API descriptions | | ||
| 53 | + | ||
| 54 | +## Reuse Method 1: Integrate with Other AI Tools | ||
| 55 | + | ||
| 56 | +### General Principle | ||
| 57 | + | ||
| 58 | +Each Skill centers on a `SKILL.md` file with two parts: | ||
| 59 | + | ||
| 60 | +1. **Frontmatter (YAML metadata)**: declares `name` and `description`; AI tools use this to decide when to load the Skill. | ||
| 61 | +2. **Body (Markdown instructions)**: describes functionality, steps, constraints; serves as execution instructions for the AI assistant. | ||
| 62 | + | ||
| 63 | +```markdown | ||
| 64 | +--- | ||
| 65 | +name: skill-name | ||
| 66 | +description: | | ||
| 67 | + Brief description of functionality. | ||
| 68 | + **Required trigger scenarios**: list keywords and trigger scenarios. | ||
| 69 | +--- | ||
| 70 | + | ||
| 71 | +## Functionality | ||
| 72 | +... (body, AI tools execute accordingly) | ||
| 73 | +``` | ||
| 74 | + | ||
| 75 | +The core idea for integration: **convert `SKILL.md` to the target tool's instruction file format**, or use it directly as a system prompt fragment. | ||
| 76 | + | ||
| 77 | +### Claude Code | ||
| 78 | + | ||
| 79 | +Claude Code natively supports the `.claude/skills/` path convention; **no conversion needed**. | ||
| 80 | + | ||
| 81 | +```bash | ||
| 82 | +git clone https://gitcode.com/cann/graph-autofusion.git | ||
| 83 | +cd graph-autofusion | ||
| 84 | +# Open this directory with Claude Code; it auto-loads .claude/skills/*/SKILL.md | ||
| 85 | +claude | ||
| 86 | +``` | ||
| 87 | + | ||
| 88 | +Applicable scenario: developers using Claude Code. Note that the 4 remote Skills require running `default-skills` installation first (see Notes). | ||
| 89 | + | ||
| 90 | +### Cursor | ||
| 91 | + | ||
| 92 | +Cursor uses `.cursor/rules/*.mdc` files as instructions. Conversion notes: | ||
| 93 | + | ||
| 94 | +- SKILL.md `description` → Cursor rule frontmatter (`description` + `globs`) | ||
| 95 | +- SKILL.md body → Cursor rule body, reused directly | ||
| 96 | +- One SKILL.md maps to one `.mdc` file | ||
| 97 | + | ||
| 98 | +```cursor-rule | ||
| 99 | +--- | ||
| 100 | +description: graph-autofusion build assistant (build.sh, CMake, dependency matching) | ||
| 101 | +globs: ["build.sh", "CMakeLists.txt", "cmake/**"] | ||
| 102 | +alwaysApply: false | ||
| 103 | +--- | ||
| 104 | +(paste af-build-runner/SKILL.md body here) | ||
| 105 | +``` | ||
| 106 | + | ||
| 107 | +Applicable scenario: developers using Cursor. Set `globs` to the file types each Skill targets, enabling on-demand triggering. | ||
| 108 | + | ||
| 109 | +### GitHub Copilot | ||
| 110 | + | ||
| 111 | +GitHub Copilot supports two approaches: | ||
| 112 | + | ||
| 113 | +**Approach 1: Single aggregated file** (`.github/copilot-instructions.md`) | ||
| 114 | + | ||
| 115 | +Aggregate key content from multiple SKILL.md files into one file; suitable when few Skills are used. | ||
| 116 | + | ||
| 117 | +**Approach 2: Multi-file split** (`.github/instructions/*.instructions.md`, requires VS Code 1.100+) | ||
| 118 | + | ||
| 119 | +Each SKILL.md maps to one `.instructions.md` file with `applyTo` frontmatter: | ||
| 120 | + | ||
| 121 | +```github-instruction | ||
| 122 | +--- | ||
| 123 | +applyTo: "build.sh,CMakeLists.txt,cmake/**" | ||
| 124 | +--- | ||
| 125 | +(paste af-build-runner/SKILL.md body here) | ||
| 126 | +``` | ||
| 127 | + | ||
| 128 | +Applicable scenario: developers using GitHub Copilot. Approach 2 is recommended for one-to-one mapping with Skills, easing maintenance. | ||
| 129 | + | ||
| 130 | +### General Method (AI tools without instruction file support) | ||
| 131 | + | ||
| 132 | +For AI tools that do not support instruction file loading (e.g., web-based ChatGPT, Qwen), **paste the required SKILL.md content as a system prompt fragment**: | ||
| 133 | + | ||
| 134 | +1. Identify the relevant Skill for your current task (see "Skill Overview"). | ||
| 135 | +2. Read the full `.claude/skills/<name>/SKILL.md`. | ||
| 136 | +3. Paste at the start of your AI tool's system prompt or conversation: "Please assist me with graph-autofusion development per the following instructions:\n\n{SKILL.md body}". | ||
| 137 | +4. Select on demand; avoid pasting all 17 Skills at once (may exceed context window). | ||
| 138 | + | ||
| 139 | +## Reuse Method 2: Read as a Manual Development Guide | ||
| 140 | + | ||
| 141 | +Without AI tools, SKILL.md files still contain manually readable development value (command references, checklists, process descriptions). | ||
| 142 | + | ||
| 143 | +### General Skill Quick Reference | ||
| 144 | + | ||
| 145 | +| Skill | Manually Readable Value | Key Points | | ||
| 146 | +|-------|------------------------|------------| | ||
| 147 | +| `af-build-runner` | Build command reference, incremental build strategy, common errors | All build commands must use `-j 8` to limit parallelism, avoiding OOM | | ||
| 148 | +| `af-test-developer` | Test module table, run commands, coverage generation | `autofuse_e2e` supports only ST (`-s`), not UT (`-u`) | | ||
| 149 | +| `af-code-reviewer` | PR self-check checklist, commit message format, high-risk issues | C++ 4-space indent, line width 120; commit format `<type>: <short description>` | | ||
| 150 | +| `cann-toolkit-installer` | Toolkit install args, process, dependencies | Default version 9.1.0, auto-detected architecture, ~10 min install | | ||
| 151 | +| `default-skills` | Remote Skill installation entry | Triggers `install-default-skills.sh` to pull from gitcode | | ||
| 152 | + | ||
| 153 | +For details, read the corresponding [SKILL.md](../../.claude/skills/af-build-runner/SKILL.md) directly. | ||
| 154 | + | ||
| 155 | +### SK Operator Pipeline Stage Quick Reference | ||
| 156 | + | ||
| 157 | +The SK operator delivery pipeline executes in the following stage order; each stage maps to a Skill: | ||
| 158 | + | ||
| 159 | +| Stage | Skill | Purpose | | ||
| 160 | +|-------|-------|---------| | ||
| 161 | +| Entry | `sk-operator-pipeline` | Run customizable asset adapter, validate contracts, dispatch stage Skills | | ||
| 162 | +| 1. Asset adaptation | `sk-operator-asset-adapter` | Convert user operator repo/source tree/build assets to stable JSON contract | | ||
| 163 | +| 2. Validation | `sk-operator-validate` | Validate contract, source structure, compatibility; output findings | | ||
| 164 | +| 3. Code generation | `sk-operator-codegen` | Generate SK binding (Args struct + `__sk__` template + SK_BIND) | | ||
| 165 | +| 4. Sample generation | `sk-operator-sample-gen` | Build run inputs, oracle, runner, differential contract | | ||
| 166 | +| 5. Build and package | `sk-operator-build-package` | Invoke bisheng to compile SK/ACLGraph extension, package as wheel | | ||
| 167 | +| Diagnosis | `sk-model-analysis` | Full-network diagnosis: hang/coredump location, perf analysis, scope/task visualization | | ||
| 168 | + | ||
| 169 | +When reading manually, start from `sk-operator-pipeline`'s SKILL.md (master branch) for the overall flow. | ||
| 170 | + | ||
| 171 | +### Remote Skill Trigger Scenario Quick Reference | ||
| 172 | + | ||
| 173 | +| Skill | Trigger Scenarios | | ||
| 174 | +|-------|-------------------| | ||
| 175 | +| `gitcode-pr` | Create PR, push to remote, view PR changes, get PR comments | | ||
| 176 | +| `gitcode-issue` | View issue details, read issue comments | | ||
| 177 | +| `gitcode-pipeline` | Trigger pipeline, view pipeline status, wait for pipeline result | | ||
| 178 | +| `api-doc-generator` | Generate API docs, add API descriptions | | ||
| 179 | + | ||
| 180 | +## Reuse Notes | ||
| 181 | + | ||
| 182 | +### Script Dependencies | ||
| 183 | + | ||
| 184 | +- **7 `sk-*` Skills** contain Python scripts (`scripts/*.py`); AI tool-triggered execution requires **Python 3.9+**. Manual reading does not require executing scripts; only understanding the workflow described in SKILL.md. | ||
| 185 | +- **`cann-toolkit-installer`** embeds bash logic (download, verify, install); execution requires **bash >= 5.1.16**. | ||
| 186 | +- **`default-skills`**'s `scripts/install-default-skills.sh` installs remote Skills; requires network access to gitcode.com. | ||
| 187 | + | ||
| 188 | +In manual reading scenarios, scripts are for reference only and are not required to run. | ||
| 189 | + | ||
| 190 | +### Remote Skill Installation | ||
| 191 | + | ||
| 192 | +The 4 remote Skills (`gitcode-pr`, `gitcode-issue`, `gitcode-pipeline`, `api-doc-generator`) are not in git; install via: | ||
| 193 | + | ||
| 194 | +**Method 1: Trigger `default-skills` via cannbot** (with cannbot environment) | ||
| 195 | + | ||
| 196 | +Enter "install default skills" in opencode; it auto-runs `install-default-skills.sh`. | ||
| 197 | + | ||
| 198 | +**Method 2: Manual installation** (without cannbot environment) | ||
| 199 | + | ||
| 200 | +```bash | ||
| 201 | +# Clone the remote skill repo | ||
| 202 | +git clone --depth 1 https://gitcode.com/cann-agent/skills.git /tmp/cann-skills | ||
| 203 | + | ||
| 204 | +# Copy to the project's _remote directory | ||
| 205 | +mkdir -p .claude/skills/_remote | ||
| 206 | +cp -r /tmp/cann-skills/gitcode-pr .claude/skills/_remote/ | ||
| 207 | +cp -r /tmp/cann-skills/gitcode-issue .claude/skills/_remote/ | ||
| 208 | +cp -r /tmp/cann-skills/gitcode-pipeline .claude/skills/_remote/ | ||
| 209 | +cp -r /tmp/cann-skills/api-doc-generator .claude/skills/_remote/ | ||
| 210 | + | ||
| 211 | +# Create symlinks to the top-level directory | ||
| 212 | +ln -sf _remote/gitcode-pr .claude/skills/gitcode-pr | ||
| 213 | +ln -sf _remote/gitcode-issue .claude/skills/gitcode-issue | ||
| 214 | +ln -sf _remote/gitcode-pipeline .claude/skills/gitcode-pipeline | ||
| 215 | +ln -sf _remote/api-doc-generator .claude/skills/api-doc-generator | ||
| 216 | + | ||
| 217 | +# Clean up temp directory | ||
| 218 | +rm -rf /tmp/cann-skills | ||
| 219 | +``` | ||
| 220 | + | ||
| 221 | +After installation, 4 symlinks appear in `.claude/skills/` top level, discoverable by AI tools. | ||
| 222 | + | ||
| 223 | +### `.gitignore` Whitelist Rule | ||
| 224 | + | ||
| 225 | +`.claude/skills/.gitignore` uses an "**ignore by default + whitelist**" strategy: | ||
| 226 | + | ||
| 227 | +```gitignore | ||
| 228 | +* | ||
| 229 | +!af-build-runner/ | ||
| 230 | +!af-build-runner/** | ||
| 231 | +... (12 local Skill whitelist entries) | ||
| 232 | +!.gitignore | ||
| 233 | +``` | ||
| 234 | + | ||
| 235 | +Reusing existing Skills is unaffected. **To add a new custom Skill**, add a whitelist entry to `.gitignore`: | ||
| 236 | + | ||
| 237 | +```gitignore | ||
| 238 | +!my-skill/ | ||
| 239 | +!my-skill/** | ||
| 240 | +``` | ||
| 241 | + | ||
| 242 | +See [opencode-skill-management.md](../zh/opencode-skill-management.md) "`.gitignore` Configuration" section for details. | ||
| 243 | + | ||
| 244 | +### Third-Party Plugin Skills Out of Scope | ||
| 245 | + | ||
| 246 | +Third-party plugin Skills like `superpowers` are configured by `.opencode/opencode.json`, located in `~/.cache/opencode/`, and are not project-built-in. This document does not provide reuse guidance for them. See [opencode-skill-management.md](../zh/opencode-skill-management.md) "Third Layer: Third-Party Plugin Skills" section. | ||
| 247 | + | ||
| 248 | +## FAQ | ||
| 249 | + | ||
| 250 | +**Q: What is a SKILL.md?** | ||
| 251 | + | ||
| 252 | +A: A built-in AI assistant instruction file at `.claude/skills/<name>/SKILL.md`, consisting of frontmatter (`name`/`description`) and body (functionality, steps, constraints). cannbot auto-loads and triggers by keyword on startup; without cannbot, it can be integrated into other AI tools or read manually. | ||
| 253 | + | ||
| 254 | +**Q: Can I use these Skills without cannbot?** | ||
| 255 | + | ||
| 256 | +A: Yes. Two methods: 1) Integrate SKILL.md into Claude Code / Cursor / GitHub Copilot and other AI tools (see "Reuse Method 1"); 2) Read as a manual development guide (see "Reuse Method 2"). | ||
| 257 | + | ||
| 258 | +**Q: What if a Skill doesn't trigger after integrating with Cursor?** | ||
| 259 | + | ||
| 260 | +A: Check the `.cursor/rules/*.mdc` frontmatter: whether `description` includes relevant keywords, whether `globs` matches the files being edited, whether `alwaysApply` should be `true`. Refer to Cursor's official documentation. | ||
| 261 | + | ||
| 262 | +**Q: Do I need to manually run the `sk-*` Skill scripts?** | ||
| 263 | + | ||
| 264 | +A: No. In manual reading scenarios, scripts are for reference only; understanding the workflow in SKILL.md is sufficient. AI tools execute them on demand, requiring Python 3.9+. | ||
| 265 | + | ||
| 266 | +**Q: What's the difference between remote and local Skills?** | ||
| 267 | + | ||
| 268 | +A: Local Skills (12) are git-tracked; `git clone` gets them. Remote Skills (4) are not in git; install via `default-skills` or manual clone to `.claude/skills/_remote/`. See [opencode-skill-management.md](../zh/opencode-skill-management.md). | ||
| 269 | + | ||
| 270 | +**Q: How do I contribute a new Skill?** | ||
| 271 | + | ||
| 272 | +A: See the "Add a Local Skill" section of [opencode-skill-management.md](../zh/opencode-skill-management.md): create a modular Skill package → write `SKILL.md` + `README.md` → add whitelist entry to `.gitignore` → submit a PR. | ||
| @@ -0,0 +1,272 @@ | |||
| 1 | +# Graph-autofusion Skill 复用指南（面向无 cannbot 的外部开发者） | ||
| 2 | + | ||
| 3 | +## 概述 | ||
| 4 | + | ||
| 5 | +本文档面向**没有 cannbot** 的外部开发者，说明如何复用 graph-autofusion 工程内置的 Skills：既可接入其他 AI 工具（Claude Code / Cursor / GitHub Copilot 等）自动加载，也可作为人工开发指南阅读。 | ||
| 6 | + | ||
| 7 | +工程内置 Skills 共 17 个，分为三类：6 个通用开发 Skill、7 个 SuperKernel 算子流水线 Skill、4 个远程 GitCode 协作 Skill。 | ||
| 8 | + | ||
| 9 | +### 与其他文档的关系 | ||
| 10 | + | ||
| 11 | +| 文档 | 定位 | 受众 | | ||
| 12 | +|------|------|------| | ||
| 13 | +| [opencode-skill-management.md](./opencode-skill-management.md) | 三层 Skill 架构、管理机制、贡献流程 | Skill 维护者、贡献者 | | ||
| 14 | +| **本文档** | **无 cannbot 时如何复用内置 Skill** | **外部开发者（接入其他 AI 工具或人工阅读）** | | ||
| 15 | + | ||
| 16 | +## Skill 总览 | ||
| 17 | + | ||
| 18 | +### 通用开发 Skill（6 个，git 跟踪） | ||
| 19 | + | ||
| 20 | +| Skill | 定位 | 脚本依赖 | SKILL.md | | ||
| 21 | +|-------|------|----------|----------| | ||
| 22 | +| `af-build-runner` | 编译构建辅助（`build.sh` 参数、CMake 错误、依赖匹配） | 无 | [链接](../../.claude/skills/af-build-runner/SKILL.md) | | ||
| 23 | +| `af-test-developer` | UT/ST 测试开发辅助（gtest/mockcpp、pytest、覆盖率） | 无 | [链接](../../.claude/skills/af-test-developer/SKILL.md) | | ||
| 24 | +| `af-code-reviewer` | 代码审查与贡献规范（红线、格式、PR 模板） | 无 | [链接](../../.claude/skills/af-code-reviewer/SKILL.md) | | ||
| 25 | +| `af-reg-ascir` | ASCIR 注册辅助（新增/修改算子、dtype、tmp buffer、UT/ST 生成） | 无 | [链接](../../.claude/skills/af-reg-ascir/SKILL.md) | | ||
🟡 Medium Priority 两份文档均将 同时，文档在描述 触发条件：维护者按文档指南新增 Skill 时，参照现有
建议：在 .claude/skills/.gitignore 的白名单中追加 af-reg-ascir 的两条条目，并修正文档第 231 行对白名单条目的描述。   | |||
| 26 | +| `cann-toolkit-installer` | CANN Toolkit 自动下载安装（参数解析、校验、静默安装） | 内嵌 bash 逻辑 | [链接](../../.claude/skills/cann-toolkit-installer/SKILL.md) | | ||
| 27 | +| `default-skills` | 默认远程 Skill 安装入口 | `scripts/install-default-skills.sh` | [链接](../../.claude/skills/default-skills/SKILL.md) | | ||
| 28 | + | ||
| 29 | +### SuperKernel 算子流水线 Skill（7 个，master 分支可用） | ||
| 30 | + | ||
| 31 | +> 这 7 个 Skill 目前仅在 `master` 分支可用，`develop` 分支暂未合入。下表 `SKILL.md` 列不提供链接，请切换到 `master` 分支或通过 GitCode 网页查看。 | ||
| 32 | + | ||
| 33 | +| Skill | 定位 | 脚本依赖 | SKILL.md | | ||
| 34 | +|-------|------|----------|----------| | ||
| 35 | +| `sk-operator-pipeline` | SK 算子交付流水线总入口（路由、索引） | `scripts/` | master 分支 | | ||
| 36 | +| `sk-operator-asset-adapter` | 算子资产适配（用户目录 → JSON contract） | `scripts/*.py` | master 分支 | | ||
| 37 | +| `sk-operator-validate` | 适配产物规范校验（contract、源码、兼容性） | `scripts/` | master 分支 | | ||
| 38 | +| `sk-operator-codegen` | SK binding 代码生成（Args struct + `__sk__` + SK_BIND） | `scripts/` | master 分支 | | ||
| 39 | +| `sk-operator-sample-gen` | 样例生成与验证 contract（输入、oracle、runner） | `scripts/` | master 分支 | | ||
| 40 | +| `sk-operator-build-package` | SK/ACLGraph 编译打包（bisheng 编译 → wheel） | `scripts/*.py` | master 分支 | | ||
| 41 | +| `sk-model-analysis` | 整网诊断（hang/coredump 定位、性能分析、可视化） | `scripts/*.py` | master 分支 | | ||
| 42 | + | ||
| 43 | +### 远程 GitCode 协作 Skill（4 个，自动安装） | ||
| 44 | + | ||
| 45 | +> 这 4 个 Skill 不在 git 中，需先安装（见"复用注意事项 - 远程 Skill 安装"）。 | ||
| 46 | + | ||
| 47 | +| Skill | 定位 | 触发场景 | | ||
| 48 | +|-------|------|----------| | ||
| 49 | +| `gitcode-pr` | 创建 PR、获取评论、查看讨论 | 创建 PR、查看 PR 改动、获取 PR 评论 | | ||
| 50 | +| `gitcode-issue` | 读取 Issue 详情和评论 | 查看 issue、读取 issue 评论 | | ||
| 51 | +| `gitcode-pipeline` | 触发流水线并监控状态 | 触发流水线、盯 CI、查看流水线状态 | | ||
| 52 | +| `api-doc-generator` | 生成 API 接口文档 | 生成接口文档、接口说明 | | ||
| 53 | + | ||
| 54 | +## 复用方式一：接入其他 AI 工具 | ||
| 55 | + | ||
| 56 | +### 通用原理 | ||
| 57 | + | ||
| 58 | +每个 Skill 的核心是 `SKILL.md` 文件，由两部分组成： | ||
| 59 | + | ||
| 60 | +1. **Frontmatter（YAML 元数据）**：声明 `name` 和 `description`，AI 工具据此判断何时加载该 Skill。 | ||
| 61 | +2. **正文（Markdown 指令）**：描述功能、使用步骤、约束，作为 AI 助手的执行指令。 | ||
| 62 | + | ||
| 63 | +```markdown | ||
| 64 | +--- | ||
| 65 | +name: skill-name | ||
| 66 | +description: | | ||
| 67 | + 简短描述功能。 | ||
| 68 | + **必须触发的场景**：列出关键词和触发场景。 | ||
| 69 | +--- | ||
| 70 | + | ||
| 71 | +## 功能说明 | ||
| 72 | +...（正文，AI 工具按此执行） | ||
| 73 | +``` | ||
| 74 | + | ||
| 75 | +接入 AI 工具的核心思路：**将 `SKILL.md` 转换为目标工具的指令文件格式**，或直接作为系统提示词片段。 | ||
| 76 | + | ||
| 77 | +### Claude Code | ||
| 78 | + | ||
| 79 | +Claude Code 原生支持 `.claude/skills/` 路径约定，**无需转换**。 | ||
| 80 | + | ||
| 81 | +```bash | ||
| 82 | +git clone https://gitcode.com/cann/graph-autofusion.git | ||
| 83 | +cd graph-autofusion | ||
| 84 | +# 用 Claude Code 打开本目录，自动加载 .claude/skills/*/SKILL.md | ||
| 85 | +claude | ||
| 86 | +``` | ||
| 87 | + | ||
| 88 | +适用场景：使用 Claude Code 的开发者。注意远程 4 个 Skill 需先运行 `default-skills` 安装（见注意事项）。 | ||
| 89 | + | ||
| 90 | +### Cursor | ||
| 91 | + | ||
| 92 | +Cursor 使用 `.cursor/rules/*.mdc` 文件作为指令。转换要点： | ||
| 93 | + | ||
| 94 | +- SKILL.md 的 `description` → Cursor rule 的 frontmatter（`description` + `globs`） | ||
| 95 | +- SKILL.md 正文 → Cursor rule 正文，直接复用 | ||
| 96 | +- 一个 SKILL.md 对应一个 `.mdc` 文件 | ||
| 97 | + | ||
| 98 | +```cursor-rule | ||
| 99 | +--- | ||
| 100 | +description: graph-autofusion 编译构建辅助（build.sh、CMake、依赖匹配） | ||
| 101 | +globs: ["build.sh", "CMakeLists.txt", "cmake/**"] | ||
| 102 | +alwaysApply: false | ||
| 103 | +--- | ||
| 104 | +（粘贴 af-build-runner/SKILL.md 正文） | ||
| 105 | +``` | ||
| 106 | + | ||
| 107 | +适用场景：使用 Cursor 的开发者。建议 `globs` 按 Skill 关注的文件类型设置，实现按需触发。 | ||
| 108 | + | ||
| 109 | +### GitHub Copilot | ||
| 110 | + | ||
| 111 | +GitHub Copilot 支持两种方式： | ||
| 112 | + | ||
| 113 | +**方式一：单文件聚合**（`.github/copilot-instructions.md`） | ||
| 114 | + | ||
| 115 | +将多个 SKILL.md 的关键内容聚合到一个文件，适合 Skill 数量少的场景。 | ||
| 116 | + | ||
| 117 | +**方式二：多文件拆分**（`.github/instructions/*.instructions.md`，需 VS Code 1.100+） | ||
| 118 | + | ||
| 119 | +每个 SKILL.md 对应一个 `.instructions.md` 文件，frontmatter 声明 `applyTo`： | ||
| 120 | + | ||
| 121 | +```github-instruction | ||
| 122 | +--- | ||
| 123 | +applyTo: "build.sh,CMakeLists.txt,cmake/**" | ||
| 124 | +--- | ||
| 125 | +（粘贴 af-build-runner/SKILL.md 正文） | ||
| 126 | +``` | ||
| 127 | + | ||
| 128 | +适用场景：使用 GitHub Copilot 的开发者。推荐方式二，与 Skill 一一对应，便于维护。 | ||
| 129 | + | ||
| 130 | +### 通用方法（不支持指令文件加载的 AI 工具） | ||
| 131 | + | ||
| 132 | +对不支持指令文件加载的 AI 工具（如网页版 ChatGPT、通义千问等），将所需 SKILL.md 内容**作为系统提示词片段粘贴**： | ||
| 133 | + | ||
| 134 | +1. 按当前任务定位相关 Skill（参考"Skill 总览"清单）。 | ||
| 135 | +2. 读取对应 `.claude/skills/<name>/SKILL.md` 全文。 | ||
| 136 | +3. 在 AI 工具的系统提示词或对话开头粘贴："请按以下指令辅助我完成 graph-autofusion 开发：\n\n{SKILL.md 正文}"。 | ||
| 137 | +4. 按需选用，避免一次性粘贴全部 17 个 Skill（超出上下文窗口）。 | ||
| 138 | + | ||
| 139 | +## 复用方式二：作为人工开发指南阅读 | ||
| 140 | + | ||
| 141 | +不使用 AI 工具时，SKILL.md 同样包含人工可读的开发价值（命令速查、检查清单、流程说明）。 | ||
| 142 | + | ||
| 143 | +### 通用 Skill 关键速查 | ||
| 144 | + | ||
| 145 | +| Skill | 人工可读价值 | 关键要点 | | ||
| 146 | +|-------|-------------|----------| | ||
| 147 | +| `af-build-runner` | 编译命令速查、增量编译策略、常见错误表 | 所有编译命令必须加 `-j 8` 限制并行度，避免 OOM | | ||
| 148 | +| `af-test-developer` | 测试模块表、运行命令、覆盖率生成 | `autofuse_e2e` 仅支持 ST（`-s`），不支持 UT（`-u`） | | ||
| 149 | +| `af-code-reviewer` | PR 自查清单、commit message 格式、高风险问题速查 | C++ 4 空格缩进、行宽 120；commit 格式 `<类型>: <简短描述>` | | ||
| 150 | +| `cann-toolkit-installer` | Toolkit 安装参数、流程、依赖 | 默认版本 9.1.0，架构自动检测，安装约 10 分钟 | | ||
| 151 | +| `default-skills` | 远程 Skill 安装入口 | 触发 `install-default-skills.sh` 从 gitcode 拉取 | | ||
| 152 | + | ||
| 153 | +详细内容请直接阅读对应 [SKILL.md](../../.claude/skills/af-build-runner/SKILL.md)。 | ||
| 154 | + | ||
| 155 | +### SK 算子流水线阶段速查 | ||
| 156 | + | ||
| 157 | +SK 算子交付流水线按以下阶段顺序执行，每阶段对应一个 Skill： | ||
| 158 | + | ||
| 159 | +| 阶段 | Skill | 作用 | | ||
| 160 | +|------|-------|------| | ||
| 161 | +| 总入口 | `sk-operator-pipeline` | 运行可定制资产适配器、校验契约、调度各阶段 Skill | | ||
| 162 | +| 1. 资产适配 | `sk-operator-asset-adapter` | 将用户算子仓/源码树/构建资产转换为稳定 JSON contract | | ||
| 163 | +| 2. 规范校验 | `sk-operator-validate` | 校验 contract、源码结构、兼容性，输出 findings | | ||
| 164 | +| 3. 代码生成 | `sk-operator-codegen` | 生成 SK binding（Args struct + `__sk__` template + SK_BIND） | | ||
| 165 | +| 4. 样例生成 | `sk-operator-sample-gen` | 构造运行输入、oracle、runner、differential contract | | ||
| 166 | +| 5. 编译打包 | `sk-operator-build-package` | 调用 bisheng 编译 SK/ACLGraph 扩展，打包为 wheel | | ||
| 167 | +| 诊断 | `sk-model-analysis` | 整网诊断：hang/coredump 定位、性能分析、scope/task 可视化 | | ||
| 168 | + | ||
| 169 | +人工阅读时，建议从 `sk-operator-pipeline` 的 SKILL.md（master 分支）入口了解整体流程。 | ||
| 170 | + | ||
| 171 | +### 远程 Skill 触发场景速查 | ||
| 172 | + | ||
| 173 | +| Skill | 触发场景 | | ||
| 174 | +|-------|----------| | ||
| 175 | +| `gitcode-pr` | 创建 PR、推送代码到远程、查看 PR 改动、获取 PR 评论 | | ||
| 176 | +| `gitcode-issue` | 查看 issue 详情、读取 issue 评论 | | ||
| 177 | +| `gitcode-pipeline` | 触发流水线、查看流水线状态、等待流水线结果 | | ||
| 178 | +| `api-doc-generator` | 生成接口文档、增加接口说明 | | ||
| 179 | + | ||
| 180 | +## 复用注意事项 | ||
| 181 | + | ||
| 182 | +### 脚本依赖 | ||
| 183 | + | ||
| 184 | +- **7 个 `sk-*` Skill** 含 Python 脚本（`scripts/*.py`），AI 工具触发执行时需 **Python 3.9+**。人工阅读无需执行脚本，只需理解 SKILL.md 描述的工作流。 | ||
| 185 | +- **`cann-toolkit-installer`** 内嵌 bash 逻辑（下载、校验、安装），执行时需 **bash >= 5.1.16**。 | ||
| 186 | +- **`default-skills`** 的 `scripts/install-default-skills.sh` 用于安装远程 Skill，需网络可访问 gitcode.com。 | ||
| 187 | + | ||
| 188 | +人工阅读场景下，脚本仅作参考，不强制执行。 | ||
| 189 | + | ||
| 190 | +### 远程 Skill 安装 | ||
| 191 | + | ||
| 192 | +4 个远程 Skill（`gitcode-pr`、`gitcode-issue`、`gitcode-pipeline`、`api-doc-generator`）不在 git 中，需通过以下方式安装： | ||
| 193 | + | ||
| 194 | +**方式一：通过 cannbot 触发 `default-skills`**（有 cannbot 环境） | ||
| 195 | + | ||
| 196 | +在 opencode 中输入"安装默认 skills"，自动执行 `install-default-skills.sh`。 | ||
| 197 | + | ||
| 198 | +**方式二：手动安装**（无 cannbot 环境） | ||
| 199 | + | ||
| 200 | +```bash | ||
| 201 | +# 克隆远程 skill 仓库 | ||
| 202 | +git clone --depth 1 https://gitcode.com/cann-agent/skills.git /tmp/cann-skills | ||
| 203 | + | ||
| 204 | +# 拷贝到工程的 _remote 目录 | ||
| 205 | +mkdir -p .claude/skills/_remote | ||
| 206 | +cp -r /tmp/cann-skills/gitcode-pr .claude/skills/_remote/ | ||
| 207 | +cp -r /tmp/cann-skills/gitcode-issue .claude/skills/_remote/ | ||
| 208 | +cp -r /tmp/cann-skills/gitcode-pipeline .claude/skills/_remote/ | ||
| 209 | +cp -r /tmp/cann-skills/api-doc-generator .claude/skills/_remote/ | ||
| 210 | + | ||
| 211 | +# 创建符号链接到一级目录 | ||
| 212 | +ln -sf _remote/gitcode-pr .claude/skills/gitcode-pr | ||
| 213 | +ln -sf _remote/gitcode-issue .claude/skills/gitcode-issue | ||
| 214 | +ln -sf _remote/gitcode-pipeline .claude/skills/gitcode-pipeline | ||
| 215 | +ln -sf _remote/api-doc-generator .claude/skills/api-doc-generator | ||
| 216 | + | ||
| 217 | +# 清理临时目录 | ||
| 218 | +rm -rf /tmp/cann-skills | ||
| 219 | +``` | ||
| 220 | + | ||
| 221 | +安装后，`.claude/skills/` 一级目录出现 4 个符号链接，AI 工具可自动发现。 | ||
| 222 | + | ||
| 223 | +### `.gitignore` 白名单规则 | ||
| 224 | + | ||
| 225 | +`.claude/skills/.gitignore` 采用"**默认忽略 + 白名单放行**"策略： | ||
| 226 | + | ||
| 227 | +```gitignore | ||
| 228 | +* | ||
| 229 | +!af-build-runner/ | ||
| 230 | +!af-build-runner/** | ||
| 231 | +...（12 个本地 Skill 白名单条目） | ||
| 232 | +!.gitignore | ||
| 233 | +``` | ||
| 234 | + | ||
| 235 | +复用现有 Skill 不受影响。**如新增自建 Skill**，需在 `.gitignore` 中添加白名单条目： | ||
| 236 | + | ||
| 237 | +```gitignore | ||
| 238 | +!my-skill/ | ||
| 239 | +!my-skill/** | ||
| 240 | +``` | ||
| 241 | + | ||
| 242 | +详见 [opencode-skill-management.md](./opencode-skill-management.md) 的"`.gitignore` 配置"章节。 | ||
| 243 | + | ||
| 244 | +### 第三方插件 Skill 不在范围 | ||
| 245 | + | ||
| 246 | +`superpowers` 等第三方插件 Skill 由 `.opencode/opencode.json` 配置，位于 `~/.cache/opencode/`，非工程内置，本文档不提供复用指引。如需了解，参考 [opencode-skill-management.md](./opencode-skill-management.md) 的"第三层：第三方插件 Skills"章节。 | ||
| 247 | + | ||
| 248 | +## FAQ | ||
| 249 | + | ||
| 250 | +**Q：SKILL.md 是什么？** | ||
| 251 | + | ||
| 252 | +A：工程内置的 AI 助手指令文件，位于 `.claude/skills/<name>/SKILL.md`，由 frontmatter（`name`/`description`）和正文（功能、步骤、约束）组成。cannbot 启动时自动加载并按关键词触发；无 cannbot 时可接入其他 AI 工具或人工阅读。 | ||
| 253 | + | ||
| 254 | +**Q：没有 cannbot 能用这些 Skill 吗？** | ||
| 255 | + | ||
| 256 | +A：能。两种方式：① 将 SKILL.md 接入 Claude Code / Cursor / GitHub Copilot 等 AI 工具（见"复用方式一"）；② 作为人工开发指南阅读（见"复用方式二"）。 | ||
| 257 | + | ||
| 258 | +**Q：接入 Cursor 后 Skill 不触发怎么办？** | ||
| 259 | + | ||
| 260 | +A：检查 `.cursor/rules/*.mdc` 的 frontmatter：`description` 是否包含相关关键词、`globs` 是否匹配当前编辑的文件、`alwaysApply` 是否需要设为 `true`。以 Cursor 官方文档为准。 | ||
| 261 | + | ||
| 262 | +**Q：`sk-*` Skill 的脚本需要手动跑吗？** | ||
| 263 | + | ||
| 264 | +A：不需要。人工阅读场景下，脚本仅作参考，理解 SKILL.md 描述的工作流即可。AI 工具触发时按需执行，需 Python 3.9+。 | ||
| 265 | + | ||
| 266 | +**Q：远程 Skill 和本地 Skill 有什么区别？** | ||
| 267 | + | ||
| 268 | +A：本地 Skill（12 个）在 git 中跟踪，`git clone` 即得；远程 Skill（4 个）不在 git 中，需通过 `default-skills` 或手动克隆安装到 `.claude/skills/_remote/`。详见 [opencode-skill-management.md](./opencode-skill-management.md)。 | ||
| 269 | + | ||
| 270 | +**Q：如何贡献新 Skill？** | ||
| 271 | + | ||
| 272 | +A：参考 [opencode-skill-management.md](./opencode-skill-management.md) 的"新增本地 Skill"章节：创建模块化 Skill 包 → 编写 `SKILL.md` + `README.md` → 在 `.gitignore` 添加白名单 → 提交 PR。 | ||
🟡 Medium Priority
与中文版相同的问题：英文文档将
af-reg-ascir列为 6 个本地 Skill 之一（第 25 行），并提供 SKILL.md 链接，但.claude/skills/.gitignore的白名单中缺少af-reg-ascir条目。同时文档声称 "12 local Skill whitelist entries"（第 231 行），实际仅有 10 条（5 个 Skill × 每 Skill 2 条）。
建议：与 docs/zh/skill-reuse-guide.md 同步修复：更新 .gitignore 白名单并修正文档第 231 行条目数描述。