技能 Skills

有了记忆系统，AI 记住了你的项目规则。这一章更进一步 —— 把专业知识打包成可调用的能力包，让 AI 在合适的时机自动变专家。

专业的重复

有些任务需要专业流程，你每次都要重新指导 AI

什么是 Skill

定义、白话、和命令的区别

Skill 是 Qoder CLI 中把专业知识打包成可复用功能的机制。每个 Skill 是一个目录，核心是 SKILL.md 文件，定义了技能描述、使用时机和执行指令。

说白了，Skill 就是一份"专家操作手册"——AI 平时是个通才，遇到匹配场景时调出对应手册，立刻变专家。

SKILL.md 结构

frontmatter 加正文，这就是一个完整技能

每个 Skill 的核心文件是 SKILL.md，由两部分组成：YAML 元数据（frontmatter）和 Markdown 指令。

---
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

创建第一个 Skill

四步做出一个能用的日志分析技能

第 1 步：创建目录（用户级，所有项目可用）

mkdir -p ~/.qoder/skills/log-analyzer

第 2 步：编写 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 (errors, warnings, bottlenecks)
3. Provide summary with severity, root cause, and fixes

第 3 步：验证加载（新会话自动加载，或运行中用 /skills reload）

What Skills are available?
（应显示 log-analyzer 及其描述）

第 4 步：测试触发——打开一个日志文件，说"分析这个日志里的错误"，AI 应自动调用该技能。

存储位置

用户级和项目级，决定技能的可用范围

自动触发

description 写得好，技能才能在对的时机被调用

Skill 的自动触发完全依赖 description——模型根据用户请求和各技能描述做匹配。描述写得模糊，技能永远不被触发；写得具体，命中率飙升。

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.

手动触发

不想等模型判断，也可以直接喊

有时你明确知道要用某个技能，不想赌自动触发，可以直接用斜杠命令手动调用：

/log-analyzer

这会强制加载该技能的完整 SKILL.md 并按其指令执行。

# 问 AI
What Skills are available?

# 或用命令
/skills

# 文件系统查看
ls ~/.qoder/skills/
ls .qoder/skills/

渐进式披露

复杂技能用多文件组织，按需加载

简单技能一个 SKILL.md 够用。但复杂技能（如数据库迁移工具）有大量参考文档、脚本、模板——全塞进一个文件会让模型每次加载全部内容，浪费 token。

渐进式披露的思路：主文件只放核心指令，详细内容放辅助文件，需要时再引用。

database-migrator/
├── SKILL.md            # 核心：流程入口
├── MIGRATION_GUIDE.md  # 详细迁移模式
├── ROLLBACK.md         # 回滚策略
└── scripts/
    ├── generate_migration.py
    └── backup_db.sh

在 SKILL.md 中引用：
For detailed patterns, see [MIGRATION_GUIDE.md].
Run backup: python scripts/backup_db.sh

最佳实践

写技能时容易踩的坑

排错指南

技能相关的高频问题

动手练习

做一个属于你工作流的技能

本章回顾

带走的三个核心认知

延伸阅读