Agent Skills 深度解析：为 AI 代理构建可复用的技能生态系统

<!-- 旧方式：在 main rule 中手动维护 -->
# AVAILABLE SKILLS

Skills are pre-packaged instructions. When a task matches a skill,
use read_file to load the SKILL.md and follow its instructions.

Available skills:
- **frontend-design**: Create distinctive UI components
  Location: ~/.kilocode/skills/frontend-design/SKILL.md
  
- **code-review**: Automated code quality analysis
  Location: ~/.kilocode/skills/code-review/SKILL.md
  
- **pdf-processing**: PDF manipulation toolkit
  Location: ~/.kilocode/skills/pdf-processing/SKILL.md

To use: read_file the location → follow instructions

# 新方式：只需将技能放入目录
~/.kilocode/skills/
├── frontend-design/
│   └── SKILL.md
├── code-review/
│   └── SKILL.md
└── pdf-processing/
    └── SKILL.md

# KiloCode 自动发现并加载！

Write Once, Use Everywhere
一次编写，到处使用

启动时：加载所有技能的 name + description（几百字节）
         ↓
匹配任务：识别相关技能
         ↓
执行时：读取完整的 SKILL.md 指令（几KB）
         ↓
需要时：加载脚本、资源文件（按需）

skill-name/
├── SKILL.md          # 必需：指令 + 元数据
├── scripts/          # 可选：可执行代码
│   ├── process.py
│   └── helper.sh
├── references/       # 可选：参考文档
│   └── api-docs.md
└── assets/           # 可选：模板、资源
    └── template.json

---
name: skill-identifier
description: A concise description of what this skill does
tags: [tag1, tag2]
version: 1.0.0
author: Your Name
dependencies: []
---

# Skill Name

## When to use this skill
Explain when and why to use this skill...

## Instructions
Step-by-step guide on how to perform the task...

## Examples
Concrete examples showing the skill in action...

## Best Practices
Tips and recommendations...

name: pdf-processing          # 技能唯一标识符
description:|                # 简洁的功能描述
ExtracttextandtablesfromPDFfiles,
fillforms,mergedocuments

tags: [pdf, document, extraction]    # 便于分类和搜索
version: 1.2.0                       # 语义化版本
author: John Doe                     # 作者信息
license: MIT                         # 开源协议

dependencies:                        # 依赖的其他技能
-skill:python-development
    version:">=1.0.0"
-skill:file-operations
    version:"*"

modes:[code,ask,debug]           # 适用的代理模式

requires:                           # 外部依赖
python:">=3.8"
packages:
    -pdfplumber>=0.10.0
    -PyPDF2>=3.0.0

## When to use this skill

Use this skill when the user needs to:
- Extract text or tables from PDF documents
- Read PDF forms and extract field data
- Merge multiple PDFs into one document
- Fill out PDF forms programmatically
- Split PDF files into separate pages

## Instructions

### Step 1: Analyze the PDF
First, determine what operation the user wants:
- Text extraction → Use pdfplumber
- Form filling → Use PyPDF2
- Merging → Use PyPDF2.PdfMerger

### Step 2: Execute the operation
For text extraction:
1. Import pdfplumber
2. Open the PDF file
3. Extract text from each page
4. Return formatted results

[Code example here]

## Examples

### Example 1: Extract text from PDF

\`\`\`python
import pdfplumber

def extract_text(pdf_path):
    with pdfplumber.open(pdf_path) as pdf:
        text = ""
        for page in pdf.pages:
            text += page.extract_text()
    return text

# Usage
text = extract_text("document.pdf")
print(text)
\`\`\`

<!-- 旧方式：在 main rule 中手动维护 -->
# AVAILABLE SKILLS

Skills are pre-packaged instructions for specific tasks. When a user request matches a skill description, read the full SKILL.md file to get detailed instructions.

These are the currently available skills:

- **frontend-design**: Create distinctive, production-grade UI components
  - Location: ~/.kilocode/skills/frontend-design/SKILL.md
  - Use read_file tool to load this skill when needed

- **code-review**: Automated code quality analysis with specialized patterns
  - Location: ~/.kilocode/skills/code-review/SKILL.md
  - Use read_file tool to load this skill when needed

- **pdf-processing**: Comprehensive PDF manipulation toolkit
  - Location: ~/.kilocode/skills/pdf-processing/SKILL.md
  - Use read_file tool to load this skill when needed

...（每添加技能都要手动更新这个列表）

## How to use skills
1. Identify which skill matches the user's request based on the description
2. Use read_file to load the full SKILL.md file from the location shown
3. Follow the instructions in the skill file
4. Access any bundled files (scripts, references, assets) as needed

// KiloCode 新实现（简化版）
asyncfunction discoverSkills(skillsDir: string): Promise<Skill[]> {
const skills: Skill[] = [];
const entries = await fs.readdir(skillsDir, { withFileTypes: true });

for (const entry of entries) {
    if (entry.isDirectory()) {
      const skillPath = path.join(skillsDir, entry.name);
      const skillMd = path.join(skillPath, 'SKILL.md');
      
      if (await fs.pathExists(skillMd)) {
        const skill = await loadSkillMetadata(skillMd);
        skills.push(skill);
      }
    }
  }

return skills;
}

// 启动时自动发现
const skills = await discoverSkills('~/.kilocode/skills/');
console.log(`Auto-discovered ${skills.length} skills`);

# 现在的工作流
$ cd ~/.kilocode/skills/
$ npx ai-agent-skills install frontend-design
✓ Installed to ~/.kilocode/skills/frontend-design

# 立即在 KiloCode 中可用，无需任何配置！
# 当你说："Create a pricing card"
# KiloCode 自动：
# 1. 扫描到 frontend-design 技能
# 2. 匹配到 "Create" 和 "pricing card" 关键词
# 3. 加载完整 SKILL.md 指令
# 4. 按照指令生成高质量组件

// 自动生成的提示词格式
AVAILABLE SKILLS

Skills are pre-packaged instructions for specific tasks.
When a user request matches a skill description, read the full
SKILL.md file to get detailed instructions.

- These are the currently available skills for "${currentMode}" mode:
${skillsList}

To use a skill:
1. Identify which skill matches the user's request based on the description
2. Use read_file to load the full SKILL.md file from the path shown in brackets
3. Follow the instructions in the skill file
4. Access any bundled files (scripts, references, assets) as needed

用户请求: "Extract text from PDF"
         ↓
Step 1: 技能匹配
├─ 扫描所有技能元数据
├─ 关键词匹配: "PDF", "extract"
└─ 找到: pdf-processing
         ↓
Step 2: 技能激活
├─ 读取完整 SKILL.md
├─ 注入系统提示词
└─ 加载相关脚本/资源
         ↓
Step 3: 执行任务
├─ 按照指令步骤执行
├─ 调用脚本（如需要）
└─ 返回结果
         ↓
Step 4: 技能卸载
└─ 从上下文中移除（为下次任务腾出空间）

# 从内置库安装
npx ai-agent-skills install pdf-processing

# 从 GitHub 安装
npx ai-agent-skills install anthropics/skills/pdf

# 从本地路径安装
npx ai-agent-skills install ./my-custom-skill

# 安装到特定代理
npx ai-agent-skills install frontend-design --agent cursor

# 安装到 Claude Desktop
npx ai-agent-skills install code-review --agent claude

# 安装到 KiloCode（即将支持）
npx ai-agent-skills install pdf-processing --agent kilocode

npx ai-agent-skills browse

npx ai-agent-skills install pdf --agent kilocode --dry-run

Would install: pdf
Agent: kilocode
Source: /Users/addo/Workspaces/github_w/Ai-Agent-Skills/skills/pdf
Destination: /Users/addo/.kilocode/skills/pdf
Size: 2.4 KB
Note: Would overwrite existing installation

skills-registry/
├── development/          # 开发类 (13个)
│   ├── frontend-design/
│   ├── code-review/
│   ├── mcp-builder/
│   └── ...
├── documents/           # 文档类 (4个)
│   ├── pdf/
│   ├── excel/
│   └── ...
├── creative/            # 创意类 (6个)
│   ├── canvas-design/
│   └── ...
├── business/            # 商业类 (5个)
│   └── ...
└── productivity/        # 生产力类 (12个)
    └── ...

# Step 1: 安装必要技能到 KiloCode
npx ai-agent-skills install frontend-design --agent kilocode
npx ai-agent-skills install code-review --agent kilocode
npx ai-agent-skills install qa-testing --agent kilocode

# Step 2: 验证安装
npx ai-agent-skills list --installed --agent kilocode

#!/bin/bash
# setup-kilocode-skills.sh

echo"Installing skills to KiloCode..."

skills=(
"frontend-design"
"code-review"
"python-development"
"qa-regression"
"git-workflow"
)

for skill in"${skills[@]}"; do
  npx ai-agent-skills install "$skill" --agent kilocode
echo"✓ Installed $skill to KiloCode"
done

echo"KiloCode skills setup complete!"

mkdir -p ~/my-skills/company-api
cd ~/my-skills/company-api

---
name: company-api
description: Interact with our internal company APIs
version: 1.0.0
author: DevTeam
---

# Company API Integration

## When to use this skill
Use this skill when you need to:
- Query employee database
- Fetch project information
- Update task status

## Instructions

### Authentication
All API calls require a token:
\`\`\`python
import os
token = os.getenv('COMPANY_API_TOKEN')
headers = {'Authorization': f'Bearer {token}'}
\`\`\`

### Query Employees
\`\`\`python
import requests

def get_employee(employee_id):
    response = requests.get(
        f'https://api.company.com/employees/{employee_id}',
        headers=headers
    )
    return response.json()
\`\`\`

# 从本地路径安装到 KiloCode
npx ai-agent-skills install ~/my-skills/company-api --agent kilocode

# 在 KiloCode 中测试
# 输入："Get employee info for ID 12345"
# 代理应该激活 company-api 技能并执行查询

# 推送到 GitHub
cd ~/my-skills/company-api
git init
git add .
git commit -m "Initial commit"
git remote add origin git@github.com:company/ai-skills.git
git push -u origin main

# 团队成员可以直接安装
npx ai-agent-skills install company/ai-skills/company-api

diagnostic-skill/
├── SKILL.md
└── scripts/
    ├── analyze.py      # 分析脚本
    ├── fix.py          # 修复脚本
    └── verify.sh       # 验证脚本

## Step 3: Run Diagnostics

Execute the analysis script:
\`\`\`bash
python scripts/analyze.py --input data.json
\`\`\`

The script will output a detailed report.

template-generator/
├── SKILL.md
└── assets/
    ├── react-component.template
    ├── api-route.template
    └── test-suite.template

## Generate React Component

Use the template from `assets/react-component.template`:
\`\`\`javascript
// Load template
const template = readFile('assets/react-component.template');
// Customize based on user requirements
const component = template.replace('{{name}}', componentName);
\`\`\`

---
name: api-integration
description: |
  Integrate with RESTful APIs including authentication,
  error handling, and response parsing
tags: [api, rest, integration]
---

# API Integration

## When to use this skill
Use this skill when the user needs to:
- Connect to external REST APIs
- Handle OAuth authentication
- Parse and transform API responses
- Implement retry logic and error handling

## Prerequisites
- API endpoint URL
- Authentication credentials (API key, OAuth token, etc.)
- Required HTTP method (GET, POST, PUT, DELETE)

## Instructions

### Step 1: Analyze API Requirements
First, gather information:
- What is the base URL?
- What authentication method is used?
- What data needs to be sent/received?

### Step 2: Implement Authentication
[详细步骤...]

### Step 3: Make API Request
\`\`\`python
import requests

def make_api_call(url, method='GET', headers=None, data=None):
    try:
        response = requests.request(
            method=method,
            url=url,
            headers=headers,
            json=data,
            timeout=30
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"API call failed: {e}")
        return None
\`\`\`

## Error Handling
Common errors and solutions:
- 401 Unauthorized → Check authentication credentials
- 429 Too Many Requests → Implement rate limiting
- 500 Server Error → Add retry logic with exponential backoff

## Examples

### Example 1: GET Request with API Key
\`\`\`python
headers = {'Authorization': f'Bearer {api_key}'}
data = make_api_call('https://api.example.com/users', headers=headers)
\`\`\`

### Example 2: POST Request with JSON Body
\`\`\`python
data = {'name': 'John', 'email': 'john@example.com'}
result = make_api_call(
    'https://api.example.com/users',
    method='POST',
    headers=headers,
    data=data
)
\`\`\`

---
name: api
description: API stuff
---

# API

Use this to call APIs.

## How to use
Just call the API.

\`\`\`python
import requests
response = requests.get(url)
\`\`\`

❌ super-developer-skill
   包含前端、后端、数据库、测试所有内容
   → 太大，难以维护，很少全部使用

❌ add-console-log
   只做一件事：添加 console.log
   → 太小，不值得单独创建技能

✅ frontend-design
   专注于前端 UI 组件设计
   → 边界清晰，复用价值高

✅ code-review
   专注于代码质量分析
   → 功能完整，独立使用

# 1. 安装 CLI
npx ai-agent-skills --version

# 2. 浏览技能
npx ai-agent-skills browse

# 3. 安装技能
npx ai-agent-skills install frontend-design

# 4. 开始使用
# 在你的 AI 代理中说："Create a pricing card component"