---
title: "Skills"
description: "按需加载的专项行为协议，以及本地、插件、内置和 MCP 来源的优先级。"
---

> Documentation Index
> Fetch the complete documentation index at: https://konghayao.github.io/peri-cool/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

Skill 是一份带 frontmatter 的 `SKILL.md`。它告诉 Agent 何时采用某种工作流、需要读取哪些
资源，以及完成前如何验证。Skill 不是可执行工具；它通过 System Prompt 提供行为指引，
真正的文件、Shell、MCP 或 Workflow 操作仍由工具系统执行。

## 项目 Skill

```md
---
name: diagnosing-build
description: 在项目构建失败时定位根因并给出可验证修复。
---

# Diagnosing Build

先复现失败，再缩小到最小命令；修改后重跑同一命令。
```

放在项目目录：

- .claude/
  - skills/
    - diagnosing-build/
      - SKILL.md

Skill 目录可以包含脚本、模板和参考资料。`SKILL.md` 应给出读取路由，不要在主文件里复制
所有素材。

## 来源与优先级

本地来源按以下顺序扫描，先出现的 canonical name 或 alias 占用该名称：

1. `~/.claude/skills/`；
2. `<cwd>/.claude/skills/`；
3. Plugin manifest 声明的 Skill；
4. 随 Peri 编译分发的 builtin Skill。

`skillsDir` / `skills_dir` 配置已移除，旧值不再添加技能来源。
`~/.peri/settings.json` 中的 `disableBundledSkills` 仍可关闭 builtin Skill，
支持顶层字段或放在 `config` 中，不影响用户、项目和 Plugin 来源。

builtin 的 canonical name 与 alias 是保留名称，非 builtin Skill 不能冒用。MCP server 还可以
通过 `skill://` 资源发布远端 Skill；它们追加到当前 session catalog，不覆盖已经存在的本地项。

## 如何触发

- **按任务自动匹配**：Agent 先看到 name 与 description 摘要，再按需加载全文；
- **直接点名**：说“使用 diagnosing-build”或输入可调用 Skill 的 `/skill-name` 形式；
- **由另一个 Skill 路由**：上层 Skill 可以要求加载更具体的专项 Skill。

`/skill-name` 会由预加载路径识别，但它不是 TUI 本地面板命令。是否允许用户直接调用还取决于
该 Skill 的 frontmatter 和当前装配。

## 当前内置 Skills

| Skill | 用途 |
| --- | --- |
| `cron` | 创建与维护定时任务 |
| `goal` | 跟踪需要跨轮次持续推进的目标 |
| `ultra-adlc` | 超大规模端到端完整交付 |
| `ultra-task` | 由主 Agent 监督 Subagent 完成复杂任务 |
| `ultracode` | 生成并运行多 Agent Workflow |
| `use-artifacts` | 使用制品上传工具 |

内置清单随版本变化。需要确认当前会话时，让 Agent 使用 `DiscoverSkillsTool`，不要只依赖这张表。

## MCP Skill 的额外边界

远端 Skill 的元数据、正文和资源 URI 绑定到发布它的 MCP server。加载后需要工具时，仍应先
搜索该 server 的 deferred 工具并读取实际 schema，不能从 Skill 文本猜测工具名或参数。

> **Caution**
>
> Skill 提供方法，不扩大权限。它不能绕过工具审批、文件系统边界、MCP server 授权或用户对
> commit、push、发布和部署的单独授权。

相关内容：[工具系统](/peri-cool/docs/features/tools/) · [MCP](/peri-cool/docs/features/mcp/) · [插件管理](/peri-cool/docs/guides/plugins/)

Source: https://konghayao.github.io/peri-cool/docs/features/skills/index.mdx