# About Agent Skills

## What Is an Agent Skill?

An **Agent Skill** is a self-contained directory that gives an AI agent specialized, domain-specific
capabilities. Skills follow the open **Agent Skills** standard ([agentskills.io](https://agentskills.io)),
making them portable across all compatible AI tools.

Every skill has this structure:

```
skill-name/
├── SKILL.md          # Required: instructions + metadata (frontmatter)
├── scripts/          # Optional: executable scripts
├── references/       # Optional: reference documents
└── assets/           # Optional: templates and other static files
```

The agent reads `SKILL.md` first, then loads other files only when needed.

---

## This Repository

Skills are leaf directories that contain a `SKILL.md` file. The top-level folders (e.g.,
`职场相关 Skill/`, `16 个 Anthropic 官方 Skill/`) are **category folders, not skills**.

```
shared_skills/
├── 16 个 Anthropic 官方 Skill/      ← category folder — NOT a skill
│   ├── docx/                         ← skill (contains SKILL.md)
│   ├── pdf/                          ← skill (contains SKILL.md)
│   └── ...
├── 职场相关 Skill/                    ← category folder — NOT a skill
│   ├── resume-screener/              ← skill (contains SKILL.md)
│   └── ...
└── ...
```

**Install the individual skill folder only**. Do not install the category folder.

---

## Correct Directory Structure After Installation

After installation, the skill's `SKILL.md` must be located at exactly:

```
<install-path>/<skill-name>/SKILL.md
```

| Result | Status |
|--------|--------|
| `.agents/skills/docx/SKILL.md` | ✅ Correct |
| `.agents/skills/docx/docx/SKILL.md` | ❌ Wrong — extra level (copied folder into itself) |
| `.agents/skills/SKILL.md` | ❌ Wrong — missing level (copied folder contents, not folder) |

**How to copy without errors:** Copy the entire skill folder (e.g., `docx/`) into the target
directory. Copy the folder itself, not its contents.

- Source folder: `…/shared_skills/16 个 Anthropic 官方 Skill/docx/`
- Target base directory: `.agents/skills/`
- Expected result: `.agents/skills/docx/SKILL.md` ✓

> **Important:** Each tool requires that the skill directory name exactly matches the `name` field
> in the skill's `SKILL.md` frontmatter. The skills in this repository already follow this convention.

---

## Installation Scopes

| Scope | When to use |
|-------|-------------|
| **Project** *(default)* | Skill is available only inside the current project directory |
| **Global (User)** | Skill is available in all projects on this machine; use only when the user asks |

---

## Tool-Specific Installation Paths

### GitHub Copilot (VS Code / GitHub.com)

| Scope | macOS / Linux | Windows |
|-------|--------------|---------|
| Project | `.github/skills/<name>/` | `.github\skills\<name>\` |
| Project (alt) | `.agents/skills/<name>/` | `.agents\skills\<name>\` |
| Global | `~/.copilot/skills/<name>/` | `%USERPROFILE%\.copilot\skills\<name>\` |
| Global (alt) | `~/.agents/skills/<name>/` | `%USERPROFILE%\.agents\skills\<name>\` |

VS Code also accepts `.claude/skills/<name>/` as a compatibility path.  
After installing, run `/skills` in the Copilot Chat input to verify discovery.

---

### Cursor

| Scope | macOS / Linux | Windows |
|-------|--------------|---------|
| Project | `.agents/skills/<name>/` | `.agents\skills\<name>\` |
| Project (alt) | `.cursor/skills/<name>/` | `.cursor\skills\<name>\` |
| Global | `~/.cursor/skills/<name>/` | `%USERPROFILE%\.cursor\skills\<name>\` |

Cursor also loads from `.claude/skills/` and `.codex/skills/` as compatibility aliases.  
View discovered skills in **Cursor Settings → Rules** (under the "Agent Decides" section).

---

### Claude Code

| Scope | macOS / Linux | Windows |
|-------|--------------|---------|
| Project | `.claude/skills/<name>/` | `.claude\skills\<name>\` |
| Global | `~/.claude/skills/<name>/` | `%USERPROFILE%\.claude\skills\<name>\` |

Priority: Global overrides Project when names conflict.

---

### Gemini CLI

| Scope | macOS / Linux | Windows |
|-------|--------------|---------|
| Project | `.gemini/skills/<name>/` | `.gemini\skills\<name>\` |
| Project (alt) | `.agents/skills/<name>/` | `.agents\skills\<name>\` |
| Global | `~/.gemini/skills/<name>/` | `%USERPROFILE%\.gemini\skills\<name>\` |
| Global (alt) | `~/.agents/skills/<name>/` | `%USERPROFILE%\.agents\skills\<name>\` |

Use `gemini skills list` to verify. Use `gemini skills install /path/to/skill` to install.

---

### OpenCode

| Scope | macOS / Linux | Windows |
|-------|--------------|---------|
| Project | `.opencode/skills/<name>/` | `.opencode\skills\<name>\` |
| Project (alt) | `.agents/skills/<name>/` | `.agents\skills\<name>\` |
| Global | `~/.config/opencode/skills/<name>/` | `%APPDATA%\opencode\skills\<name>\` |
| Global (alt) | `~/.agents/skills/<name>/` | `%USERPROFILE%\.agents\skills\<name>\` |

---

### Trae (ByteDance)

Trae supports the Agent Skills standard. Its native skill path is `.trae/skills/`. Trae also
recognizes `.agents/skills/` as a compatibility alias (see [Universal Path](#universal-path-maximum-compatibility)).

| Scope | macOS / Linux | Windows |
|-------|--------------|---------|
| Project | `.trae/skills/<name>/` | `.trae\skills\<name>\` |
| Global | `~/.trae/skills/<name>/` | `%USERPROFILE%\.trae\skills\<name>\` |

See also: https://www.trae.ai/blog/trae_tutorial_0115

---

### Windsurf (Codeium)

Windsurf does not currently support the Agent Skills standard natively. It uses rules files
instead. To make a skill available in Windsurf, add a reference to the skill and its path
in the rules file:

| Scope | Path |
|-------|------|
| Project | `.windsurfrules` in the project root |
| Global | Windsurf Settings → AI → Global Rules |

---

### Antigravity

Antigravity is a community framework for multi-IDE context management. Its native configuration
lives in the project's `.antigravity/` directory:

| Location | Path |
|----------|------|
| Project | `.antigravity/rules.md` |

`ag init` (from the Antigravity CLI) also auto-generates `CLAUDE.md`, `AGENTS.md`,
`.cursorrules`, and `.windsurfrules` from the same source, covering multiple IDEs at once.

---

### CodeBuddy (Tencent / 腾讯 CodeBuddy)

CodeBuddy is Tencent's AI coding assistant (IDE, plugin, and CLI). Skills are placed under
`.codebuddy/skills/` in the project root:

| Scope | macOS / Linux | Windows |
|-------|--------------|---------|
| Project | `.codebuddy/skills/<name>/` | `.codebuddy\skills\<name>\` |
| Global | `~/.codebuddy/skills/<name>/` | `%USERPROFILE%\.codebuddy\skills\<name>\` |

Skills can also be managed via the CodeBuddy settings UI (Settings → Skills → Import Skill).  
See also: https://www.codebuddy.cn/docs/ide/Features/Skills

---

### WorkBuddy (Tencent / 腾讯 WorkBuddy)

WorkBuddy is Tencent's AI workplace agent desktop app (separate from the coding-focused
CodeBuddy IDE). Both products share the same underlying platform (`codebuddy.cn`) and
the same skills directory path:

| Scope | macOS / Linux | Windows |
|-------|--------------|---------|
| Project | `.codebuddy/skills/<name>/` | `.codebuddy\skills\<name>\` |
| Global | `~/.codebuddy/skills/<name>/` | `%USERPROFILE%\.codebuddy\skills\<name>\` |

Note: WorkBuddy is primarily a workplace automation agent (documents, spreadsheets, PPTs).
Skills targeting file-processing or office workflows are most applicable.

---

### 通义灵码 (Tongyi Lingma / Alibaba)

通义灵码 is Alibaba's AI coding assistant (VS Code and JetBrains plugin). It has native
support for the Agent Skills standard:

| Scope | macOS / Linux | Windows |
|-------|--------------|---------|
| Project | `.lingma/skills/<name>/` | `.lingma\skills\<name>\` |
| Global | `~/.lingma/skills/<name>/` | `%USERPROFILE%\.lingma\skills\<name>\` |

Project-level skills take priority over user-level skills when names conflict.  
After installing, restart the IDE and type `/` in the chat input to see the loaded skills list.  
See also: https://help.aliyun.com/zh/lingma/user-guide/skills

---

## Universal Path (Maximum Compatibility)

The `.agents/skills/` path is recognized by GitHub Copilot (VS Code), Cursor, Gemini CLI,
OpenCode, and Trae. Use it when the target tool is unknown or for cross-tool setups:

| Scope | macOS / Linux | Windows |
|-------|--------------|---------|
| Project | `<project-root>/.agents/skills/<name>/` | `<project-root>\.agents\skills\<name>\` |
| Global | `~/.agents/skills/<name>/` | `%USERPROFILE%\.agents\skills\<name>\` |

---

## Agent Decision Flow

1. **Identify which AI tool you are running inside** (e.g., GitHub Copilot, Cursor, Claude Code,
   Gemini CLI, OpenCode, Trae, Windsurf, Antigravity).
2. **If you know the tool:** Use the project-scoped path from the table for that tool (default).
   Use the global path only if the user asks for global installation.
3. **If you do not know which tool you are:** Ask the user before proceeding:
   > "Which AI tool are you using? (GitHub Copilot / Cursor / Claude Code / Gemini CLI /
   > OpenCode / Trae / Windsurf / Antigravity / CodeBuddy / WorkBuddy / 通义灵码 / other)"
4. **After installing**, confirm the exact path of the installed skill to the user.
