AI Coding Assistant Lingma：技能

1. 建立 Skill 目錄

在使用者級 Skills 檔案夾中建立目錄。使用者級 Skills 適用於所有專案，也可在 .qodercn/skills/ 中建立專案級 Skills 與團隊共用。

# 建立使用者級 Skills 目錄
mkdir -p ~/.qoder-cn/skills/api-doc-generator

2. 編寫 SKILL.md

每個 Skill 需要一個 SKILL.md 檔案，以 --- 標記之間的 YAML 中繼資料開頭，必須包含 name 和 description，後跟 Markdown 指令。建立 ~/.qoder-cn/skills/api-doc-generator/SKILL.md：

---
name: api-doc-generator
description: Generate comprehensive API documentation from code. Use when creating API docs, documenting endpoints, or generating OpenAPI specs.
---

# API Documentation Generator

When generating API documentation:

1. Identify all API endpoints and routes
2. Document request/response formats
3. Include authentication requirements
4. Add example requests and responses
5. Generate OpenAPI/Swagger specification if needed

3. 驗證 Skill 載入

Skill 建立或修改後在新會話中會自動載入。輸入如下內容，驗證是否載入成功：

What Skills are available?

或者輸入命令驗證：

/skills

對話中應顯示 api-doc-generator 及其描述。

4. 測試 Skill

開啟專案中的 API 路由檔案，輸入與 Skill 描述匹配的問題：

為這個 API 產生文檔

Qoder CN CLI 應用 api-doc-generator Skill 並產生相關 API 文檔。若未觸發，嘗試使用 description 中的關鍵詞重新描述需求。

儲存位置

儲存位置決定 Skill 的可用範圍：

同名時，專案級 Skill 覆蓋使用者級 Skill。

Skill 與 Command 的區別

核心區別：Skill 支援命令載入和自動觸發，Command 需顯式輸入 /command-name。

選擇儲存位置

建立目錄：

# 使用者級
mkdir -p ~/.qoder-cn/skills/{skill-name}

# 專案級
mkdir -p .qoder/skills/{skill-name}

組織目錄結構

目錄結構樣本：

{skill-name}/
├── SKILL.md          # 必需：主檔案
├── REFERENCE.md      # 可選：詳細參考文檔
├── EXAMPLES.md       # 可選：文檔樣本
├── scripts/          # 可選：輔助指令碼
│   └── helper.py
└── templates/        # 可選：模板檔案
    └── template.txt

在 SKILL.md 中引用輔助檔案實現漸進式披露：

For better usage,see [REFERENCE.md].
For examples, see [EXAMPLES.md].
Run the helper script: python scripts/helper.py input.txt

編寫 SKILL.md

SKILL.md 是 Skill 中唯一必需的檔案，包含 YAML 中繼資料和 Markdown 指令：

---
name: skill-name
description: Skill 功能簡述，說明何時使用
---

# Skill Name

## Instructions
提供清晰的分步指導。

## Examples
展示具體用法。

Frontmatter 欄位：

自動觸發

直接描述需求，模型自動判斷是否使用 Skill：

分析這個記錄檔中的錯誤

模型識別並調用 log-analyzer Skill。

手動觸發

輸入 /skill-name 手動觸發：

/log-analyzer

查看可用 Skill

CLI 中查看：

What Skills are available?

檔案系統查看：

# 列出使用者級 Skill
ls ~/.qoder-cn/skills/

# 列出專案級 Skill
ls .qoder/skills/

# 查看 SKILL.md 檔案
ls ~/.qodercn/skills/*/SKILL.md
ls .qodercn/skills/*/SKILL.md

更新 Skill

直接編輯 SKILL.md，下次啟動 Qoder CN CLI 時生效。CLI 運行中需重啟以載入更新。

刪除 Skill

刪除 Skill 目錄：

# 使用者級
rm -rf ~/.qoder-cn/skills/{skill-name}

# 專案級
rm -rf .qoder/skills/{skill-name}

保持專註

每個 Skill 專註於一個領域或任務類型。

推薦：

• log-analyzer - 日誌分析

• security-auditor - 安全審計

• database-migrator - 資料庫遷移

不推薦：

• coding-helper - 功能過於寬泛

編寫清晰的 description

description 應包含：Skill 功能、使用時機和觸發關鍵詞。

對比：

# 不推薦：模糊
description: Helps with logs

# 推薦：具體
description: Analyze log files to identify errors, patterns, and performance issues. Use when debugging logs, investigating errors, or monitoring application behavior.

共用前測試

共用 Skill 前確保：

• 預期情境下能觸發

• 指令清晰

• 覆蓋常見邊界情況

記錄版本變更

在 SKILL.md 中添加版本歷史：

## 版本歷史
- v2.0.0 (2026-10-01): API 重大變更
- v1.1.0 (2026-09-15): 新增功能
- v1.0.0 (2026-09-01): 首次發布

Skill 未觸發

檢查檔案位置：

ls ~/.qoder-cn/skills/*/SKILL.md
ls .qoder/skills/*/SKILL.md

確認 SKILL.md 存在且路徑正確。

檢查 YAML 格式：查看 SKILL.md，驗證 frontmatter 無語法錯誤（縮排、引號匹配）。

檢查 description 具體性：使用清晰具體的描述：

# 推薦：明確用途和觸發條件
description: Analyze log files to identify errors, patterns, and performance issues. Use when debugging logs, investigating errors, or monitoring application behavior.

# 不推薦：模糊
description: For logs

Skill 執行出錯

檢查依賴：CLI 在需要時自動安裝依賴（或請求許可權）。

檢查指令碼許可權：

chmod +x .qoder/skills/my-skill/scripts/*.py

多個 Skill 衝突

Skill 相似導致混淆時，在 description 中使用不同觸發詞區分。

樣本 1：簡單 Skill

分析記錄檔並診斷問題。

目錄結構：

log-analyzer/
└── SKILL.md

SKILL.md：

---
name: log-analyzer
description: Analyze log files to identify errors, patterns, and performance issues. Use when debugging logs, investigating errors, or monitoring application behavior.
---

# Log Analyzer

## Instructions

1. Read the log file to understand its format
2. Identify and categorize issues:
   - Error patterns and stack traces
   - Warning messages
   - Performance bottlenecks
   - Unusual patterns or anomalies
3. Provide summary with:
   - Issue severity and frequency
   - Root cause analysis
   - Recommended solutions

## Analysis tips
- Focus on recent critical errors first
- Look for recurring patterns
- Check timestamp correlations across entries

樣本 2：多檔案 Skill

資料庫遷移與版本管理工具。

目錄結構：

database-migrator/
├── SKILL.md
├── MIGRATION_GUIDE.md
├── ROLLBACK.md
└── scripts/
    ├── generate_migration.py
    ├── validate_schema.py
    └── backup_db.sh

SKILL.md：

---
name: database-migrator
description: Generate and manage database migrations, schema changes, and data transformations. Use when creating migrations, modifying database schema, or managing database versions. Requires sqlalchemy and alembic packages.
---

# Database Migrator

## Quick start

Generate a new migration:

```bash
python scripts/generate_migration.py --name add_user_table
```

For detailed migration patterns, see [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md).
For rollback strategies, see [ROLLBACK.md](ROLLBACK.md).

## Workflow

1. **Analyze changes**: Compare current schema with desired state
2. **Generate migration**: Create migration file with up/down operations
3. **Validate**: Run `python scripts/validate_schema.py` to check syntax
4. **Backup**: Execute `scripts/backup_db.sh` before applying
5. **Apply**: Run migration in staging environment first
6. **Verify**: Check data integrity after migration

## Requirements

Install required packages:

```bash
pip install sqlalchemy alembic psycopg2-binary
```

## Safety checks

- Always backup before migrations
- Test rollback procedures
- Validate data integrity after changes
- Use transactions for atomic operations