agent-skills

Category: Tools & Productivity | Uploader: zht043 | Downloads: 0 | Version: v1.0（Latest）

AI Agent 技能库项目规范，指导 agent 正确阅读和使用 skill

Changelog: Source: GitHub https://github.com/zht043/AgentSkills

Directory Structure

Current level: tree/main/

📁 skill-creator/
- 📄 README.md 2.0 KB
- 📄 SKILL.md 6.6 KB
📁 skills/
- 📁 ascend-drivingsdk-skills/
  - 📁 cann-install/
    
    📄 README.md 1.0 KB
    
    📄 SKILL.md 5.2 KB
  - 📁 container-deploy/
    
    📁 scripts/
    
    📄 deploy-container.sh 15.9 KB
    
    📄 config.example.yaml 573 B
    
    📄 README.md 4.3 KB
    
    📄 SKILL.md 6.7 KB
  - 📁 drivingsdk-install/
    
    📁 references/
    
    📄 troubleshooting.md 791 B
    
    📄 version-table.md 573 B
    
    📄 README.md 1.2 KB
    
    📄 SKILL.md 4.6 KB
  - 📁 npu-basics/
    
    📄 README.md 850 B
    
    📄 SKILL.md 4.4 KB
  - 📁 test-coverage/
    
    📁 _lib/
    
    📄 coverage-common.sh 1.8 KB
    
    📁 docs/
    
    📄 build-integration.md 1.5 KB
    
    📁 scripts/
    
    📄 collect-cpp-coverage.sh 2.3 KB
    
    📄 run-py-coverage.sh 3.9 KB
    
    📄 config.example.yaml 693 B
    
    📄 README.md 1.7 KB
    
    📄 SKILL.md 2.6 KB
  - 📁 torch-npu-install/
    
    📄 README.md 1.1 KB
    
    📄 SKILL.md 5.4 KB
  - 📄 README.md 1.4 KB
  - 📄 SKILL.md 2.1 KB
- 📁 doc-illustrator/
  - 📁 templates/
    
    📄 architecture.yaml 859 B
    
    📄 concept.yaml 807 B
    
    📄 flow.yaml 800 B
    
    📄 sequence.yaml 805 B
  - 📄 config.example.yaml 162 B
  - 📄 README.md 1.3 KB
  - 📄 SKILL.md 2.6 KB
- 📁 export-history/
  - 📁 scripts/
    
    📄 export-claude-history.mjs 10.8 KB
  - 📄 README.md 565 B
  - 📄 SKILL.md 898 B
- 📁 markdown-mermaid-illustrator/
  - 📁 templates/
    
    📄 affinity.yaml 1.6 KB
    
    📄 architecture.yaml 1.0 KB
    
    📄 class.yaml 1.3 KB
    
    📄 concept.yaml 951 B
    
    📄 decision.yaml 879 B
    
    📄 er.yaml 1.4 KB
    
    📄 fishbone.yaml 1.9 KB
    
    📄 flow.yaml 975 B
    
    📄 gantt.yaml 1.3 KB
    
    📄 journey.yaml 1.1 KB
    
    📄 mindmap.yaml 1.1 KB
    
    📄 pie.yaml 803 B
    
    📄 quadrant.yaml 1.3 KB
    
    📄 sankey.yaml 1.1 KB
    
    📄 sequence.yaml 967 B
    
    📄 state.yaml 1.1 KB
    
    📄 swimlane.yaml 1.8 KB
    
    📄 timeline.yaml 1.1 KB
    
    📄 tree.yaml 1.4 KB
    
    📄 xychart.yaml 1.3 KB
  - 📄 config.example.yaml 97 B
  - 📄 README.md 4.8 KB
  - 📄 SKILL.md 17.3 KB
- 📁 ssh-dev-suite/
  - 📁 _lib/
    
    📄 _python.sh 697 B
    
    📄 ssh-config.py 3.4 KB
  - 📁 connect/
    
    📁 scripts/
    
    📄 ssh-download.sh 3.1 KB
    
    📄 ssh-exec.sh 1.5 KB
    
    📄 ssh-job.sh 5.8 KB
    
    📄 ssh-test.sh 1.4 KB
    
    📄 ssh-upload.sh 3.1 KB
    
    📄 SKILL.md 4.0 KB
  - 📁 debug/
    
    📄 SKILL.md 2.9 KB
  - 📁 deploy/
    
    📁 scripts/
    
    📄 ssh-deploy.sh 2.5 KB
    
    📄 SKILL.md 1.1 KB
  - 📁 long-task/
    
    📁 scripts/
    
    📄 checkpoint.sh 1.9 KB
    
    📄 SKILL.md 3.0 KB
  - 📁 tunnel/
    
    📁 scripts/
    
    📄 ssh-tunnel.sh 9.8 KB
    
    📄 SKILL.md 3.1 KB
  - 📄 config.example.yaml 2.1 KB
  - 📄 README.md 2.1 KB
  - 📄 SKILL.md 1.7 KB
📄 .gitignore 81 B
📄 AgentSkills_refactor_spec_v1.md 23.7 KB
📄 README.md 1.8 KB
📄 SKILL.md 6.5 KB

SKILL.md

---
name: agent-skills
description: AI Agent 技能库项目规范，指导 agent 正确阅读和使用 skill
---

# AgentSkills

## 项目目标
开发泛用、简洁、稳定、专业的 agent skills。

## Agent 阅读规范（极其重要）

**Agent 在使用任何 skill 前，必须深入阅读其完整文档树。** 仅读取入口 SKILL.md 是不够的。

### 必读规则

1. **Suite / Skills 类型**（含多个子模块的 skill 集合）：入口 SKILL.md 只是路由索引。Agent 必须递归读取所有子模块的 SKILL.md 和关键脚本
   ```
   skills/<suite-name>/
     SKILL.md            ← 读（路由索引，不含执行细节）
     README.md           ← 读（使用说明）
     config.example.yaml ← 读（配置模板，了解可配置项）
     <module-1>/
       SKILL.md          ← 必须读（子模块完整交互流程和规范）
       scripts/*.sh      ← 必须读（理解脚本参数、行为、退出码）
     <module-2>/
       SKILL.md          ← 必须读
       scripts/*.sh      ← 必须读
     _lib/               ← 选读（共享工具库）
   ```

2. **单体 skill**：SKILL.md + scripts/ 目录下的脚本都需要读取

3. **能力依赖发现**：当 skill 描述中提到需要某种能力（如"需要 SSH 隧道能力"、"需要反向代理"），agent 应在本项目 `skills/` 目录下扫描可用 skill，找到能提供该能力的 skill 并读取其文档。参见下方"能力索引"

### 能力索引

当 skill 描述中提到需要以下能力时，优先在 `skills/` 目录下寻找匹配的 skill：

| 能力需求 | 匹配 skill 目录 | 说明 |
|----------|-----------------|------|
| SSH 远程连接/执行 | `ssh-dev-suite/connect/` | 多 profile 连接管理、远程命令执行、文件传输 |
| SSH 隧道/端口转发/反向代理 | `ssh-dev-suite/tunnel/` | 端口转发、SOCKS代理、反向代理 |
| 远程部署/同步 | `ssh-dev-suite/deploy/` | 项目同步、部署钩子、回滚 |
| 远程调试/排查 | `ssh-dev-suite/debug/` | 结构化远程问题排查 |
| 长耗时远程任务 | `ssh-dev-suite/long-task/` | 断连恢复、checkpoint 管理 |
| NPU 状态监控/设备管理 | `ascend-drivingsdk-skills/npu-basics/` | npu-smi、设备指定、版本查询 |
| CANN 安装 | `ascend-drivingsdk-skills/cann-install/` | 社区版/商业版，run包/conda/下载 |
| PyTorch NPU 安装 | `ascend-drivingsdk-skills/torch-npu-install/` | PyTorch + torch_npu 版本匹配安装 |
| DrivingSDK 编译安装 | `ascend-drivingsdk-skills/drivingsdk-install/` | mx_driving 编译、依赖处理 |
| 容器环境部署 | `ascend-drivingsdk-skills/container-deploy/` | Docker 容器一键部署、NPU挂载 |
| 代码覆盖率收集 | `ascend-drivingsdk-skills/test-coverage/` | C++ gcov/lcov、Python coverage |
| 文档插图/图表生成 | `doc-illustrator/` | Mermaid 插图、模板匹配+LLM设计 |
| 对话历史导出 | `export-history/` | Claude Code 会话导出为 HTML |

### 按领域分组

| 领域 | Skills |
|------|--------|
| **devops** | `ssh-dev-suite/`（connect、deploy、tunnel、debug、long-task） |
| **ai-infra** | `ascend-drivingsdk-skills/`（npu-basics、cann-install、torch-npu-install、drivingsdk-install、container-deploy、test-coverage） |
| **documentation** | `doc-illustrator/` |
| **general** | `export-history/` |

> **注意**：此索引仅对本项目 skills/ 目录生效。skill 文档本身不直接引用其他 skill 名称，以保持独立可移植性。当 skill 被拷贝到其他项目使用时，用户需根据自己环境的可用工具替换上述映射。

### Agent 阅读策略（渐进式加载）

为优化 token 使用，agent 应分阶段加载 skill 文档：

1. **路由阶段**（轻量）：只读本文件的能力索引表，确定需要哪个 skill
2. **使用阶段**（深入）：读取目标 skill 的完整文档树（SKILL.md + scripts/ + config.example.yaml）
3. **不要一次性加载所有 skill 的完整文档**，按需加载即可

### SSH 远程开发规范

当 agent 需要通过 SSH 连接远程服务器执行操作时（无论是用户直接要求还是其他 skill 提到需要远程能力），**必须**：

1. 先检查 `skills/` 下是否有提供 SSH 能力的 skill（本项目为 `ssh-dev-suite`）
2. 读取该 skill 的完整文档树（入口 SKILL.md + 相关子模块 SKILL.md + 脚本）
3. 按其规范的 profile 管理、ControlMaster 会话复用、容器感知等机制操作
4. **不要自行拼接裸 ssh/scp 命令**，应使用 SSH skill 提供的脚本和流程

### 常见错误

- ❌ 只读了 suite 的入口 SKILL.md，跳过了子模块的 SKILL.md
- ❌ 读了 SKILL.md 但没读脚本，不了解参数和退出码
- ❌ skill 提到需要某种能力但没有在 skills/ 下寻找匹配工具
- ❌ 有可用的 SSH skill 却自行拼接裸 ssh/scp 命令
- ❌ 没有读 config.example.yaml，不了解可配置项
- ❌ 在交互流程中自作主张跳过了 skill 规定的步骤（如 workspace 路径询问、数据集挂载询问）
- ❌ 自行决定了本应询问用户的配置（如服务器上的工作目录路径）

### 验证方法

Agent 读取完 skill 后，应能回答以下问题：
- 这个 skill 有哪些子模块？每个子模块做什么？
- 脚本有哪些参数？哪些必填？退出码含义？
- 交互流程有哪些阶段？每个阶段问什么？
- 需要哪些外部能力？本项目 skills/ 下有匹配工具吗？

如果无法回答，说明阅读不够深入。

## 目录结构
```
skill-creator/               # Meta skill（开发规范与模板）
  SKILL.md
  README.md

skills/<skill-name>/          # 单体 skill
  SKILL.md                    # 核心文档（给 agent 看）
  README.md                   # 使用说明（给用户看）
  config.example.yaml         # 可选，配置模板，入库
  scripts/                    # 可选，工具脚本目录

skills/<suite-name>/          # Skill suite / Skills 集合（多子模块）
  SKILL.md                    # Suite 入口：总览 + 路由
  README.md                   # 使用说明（整个 suite）
  config.example.yaml         # 可选，共享配置
  _lib/                       # 可选，共享工具脚本
  <module>/                   # 子模块目录
    SKILL.md                  # 子模块文档
    scripts/                  # 可选，子模块脚本

docs/plans/                   # 设计与计划文档
```

## 开发规范
所有 skill 的开发模板、规范约束、配置引导规则详见 `skill-creator/SKILL.md`。

开发新 skill 时，请先阅读该 meta skill。

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

agent-skills

Directory Structure

SKILL.md

Report

Notice