skills-creation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skills Creation & Maintenance

Skill创建与维护

Agent guide for creating and updating skills in Editframe's centralized skills system.

Editframe集中式Skill系统中创建与更新Skill的Agent指南。

Overview

概述

Skills are the foundation of agent capabilities. This skill provides directives for:

Creating new skills from scratch with user guidance
Updating existing skills with validation
Maintaining skill quality through structured authoring
Syncing skills across agent directories after changes

Skill是Agent能力的基础。本Skill提供以下方面的指令：

从零创建新Skill并提供用户指导
更新现有Skill并进行验证
通过结构化编写维护Skill质量
变更后在各Agent目录间同步Skill

Quick Start: Creating a New Skill

快速入门：创建新Skill

Ask the user what skill they want to create
Gather requirements: purpose, capabilities, use cases
Create skill structure in
```
.skills/internal/{skill-name}/
```
Write content (SKILL.md + optional references/)
Validate the structure and frontmatter
Sync changes across agent directories
Commit to git

询问用户想要创建的Skill类型
收集需求：用途、功能、使用场景
在
```
.skills/internal/{skill-name}/
```
中创建Skill结构
编写内容（SKILL.md + 可选的references/目录）
验证结构和前置元数据
在各Agent目录间同步变更
提交到Git

Agent Workflow Directives

Agent工作流指令

Phase 1: Discovery

阶段1：需求探索

When a user requests a new skill or skill update:

Ask clarifying questions:
- "What is the primary purpose of this skill?"
- "Who will use this skill (which agents/users)?"
- "What are the key capabilities or topics?"
- "Is this updating an existing skill or creating new?"
Document requirements:
- Skill name (kebab-case:
```
my-skill-name
```
  )
- Description (one sentence for LLMs)
- Key sections/topics to cover
- Example use cases

当用户请求创建新Skill或更新现有Skill时：

提出澄清问题：
- "该Skill的主要用途是什么？"
- "谁会使用这个Skill（哪些Agent/用户）？"
- "核心功能或主题有哪些？"
- "这是更新现有Skill还是创建新Skill？"
记录需求：
- Skill名称（短横线命名法：
```
my-skill-name
```
  ）
- 描述（供LLM使用的一句话简介）
- 需要涵盖的关键章节/主题
- 示例使用场景

Phase 2: Structure Planning

阶段2：结构规划

Before writing, plan the skill structure:

Determine skill type:
- Reference skill: Documenting an existing system/API (most common)
- Tutorial skill: Step-by-step learning with examples
- How-to skill: Specific task guidance
- Explanation skill: Deep conceptual understanding
Classify each piece of planned content:

Before writing anything, categorize every section you plan to include:
- Procedural -- how to do something (deploy, rollback, create a release). Stable. Write as prose.
- Architectural -- how a system works at a high level (what connects to what, why things are structured a certain way). Moderately stable. Write as concise narrative, but avoid enumerating specifics.
- Enumerated data -- lists of things, tables of values, counts, names, versions (service lists, resource allocations, package names, secret names, route tables). Volatile. Do not write into the skill. Instead, point the agent at the source file or create a companion script that queries it (see "Companion Scripts" below).
The goal: if a config file changes, no skill doc should need updating. The skill teaches agents how to reason about a domain; scripts and source files provide the current facts.

Plan file structure:

.skills/internal/{skill-name}/
└── SKILL.md                    # Main entry point (required)

OR if detailed:

.skills/internal/{skill-name}/
├── SKILL.md                    # Overview + quick start
└── references/
    ├── topic-1.md              # Deep dive on topic 1
    ├── topic-2.md              # Deep dive on topic 2
    └── topic-3.md              # Examples/guides

Quick reference template:
- SKILL.md: 200-400 words introducing the skill
- Each reference: 400-800 words covering one topic
- Focus on clarity for LLM consumption

编写前，先规划Skill结构：

确定Skill类型：
- 参考型Skill：记录现有系统/API（最常见）
- 教程型Skill：带示例的分步学习指南
- 操作型Skill：特定任务的操作指导
- 解释型Skill：深度概念讲解
对规划内容进行分类：

在开始编写前，对计划包含的每个章节进行分类：
- 流程类 -- 如何完成某件事（部署、回滚、创建版本）。内容稳定，采用散文式写法。
- 架构类 -- 系统高层运作方式（组件间连接、结构设计原因）。内容相对稳定，采用简洁叙述方式，避免列举细节。
- 枚举数据类 -- 事物列表、数值表格、数量、名称、版本（服务列表、资源分配、包名、密钥名、路由表）。内容易变，请勿写入Skill中。应引导Agent查看源文件或创建配套脚本查询数据（见下文“配套脚本”）。
目标：若配置文件变更，无需更新任何Skill文档。Skill教Agent如何推理某个领域，而脚本和源文件提供当前事实。

规划文件结构：

.skills/internal/{skill-name}/
└── SKILL.md                    # 主入口文件（必填）

若内容复杂则采用：

.skills/internal/{skill-name}/
├── SKILL.md                    # 概述+快速入门
└── references/
    ├── topic-1.md              # 主题1深度讲解
    ├── topic-2.md              # 主题2深度讲解
    └── topic-3.md              # 示例/指南

快速参考模板：
- SKILL.md：200-400字介绍Skill
- 每个参考文件：400-800字讲解一个主题
- 注重LLM可读性

Phase 3: Content Creation

阶段3：内容创建

SKILL.md frontmatter (required):

yaml

---
name: skill-name-kebab-case
description: One sentence describing what this skill does and who should use it.
---

name

must always be dash-case with no whitespace. Tools that load skills by name may fail silently or behave incorrectly when names contain spaces. The

name

field is the machine identifier; use the

# Heading

in the body for human-readable display.

SKILL.md body (recommended structure):

markdown

undefined

SKILL.md前置元数据（必填）：

yaml

---
name: skill-name-kebab-case
description: One sentence describing what this skill does and who should use it.
---

name

必须始终使用短横线命名，无空格。按名称加载Skill的工具可能会静默失败或行为异常。

name

字段是机器标识符；请在正文中使用

# 标题

作为人类可读的显示名称。

SKILL.md正文（推荐结构）：

markdown

undefined

{Skill Title}

{Skill标题}

{2-3 sentence overview}

{2-3句话概述}

Quick Start

快速入门

{Most essential information to start using - code snippet, key concept, or first steps}

{开始使用所需的核心信息 - 代码片段、关键概念或第一步操作}

Key Concepts

核心概念

{Explain the main ideas or capabilities}

{解释主要理念或功能}

Common Patterns

常见模式

{Show 2-3 typical use cases with examples}

{展示2-3个典型使用场景及示例}

When to Use This Skill

何时使用该Skill

{Guidance on when agents should invoke this skill}


**Reference files** (optional, for complex skills):
```yaml
---
name: reference-title
description: What this reference covers
---

{指导Agent何时调用此Skill}


**参考文件**（复杂Skill可选）：
```yaml
---
name: reference-title
description: What this reference covers
---

Reference Title

参考标题

{Introduction}

{简介}

Section 1 章节1

{Content}

{内容}

Section 2 章节2

{Content}


**Writing guidelines**:
- Target 300-500 words for SKILL.md
- Use concrete examples over abstract explanations
- Include code blocks or snippets when relevant
- Link between skills using relative paths: `[skill-name](...)`
- Write for LLM consumption (clear, structured, no marketing)
- **Never duplicate data that lives in source files.** If information can be derived from a config file, script, or definition that already exists in the repo, don't copy it into the skill. Instead, tell the agent where to find it (`"Run scripts/deploy-info telecine for current service list"`) or which file to read (`"See telecine/deploy/worker-resources.config.ts for current allocations"`). Skills should be a guide to reasoning, not a cache of facts.
- **Test for drift:** before finalizing any section, ask: "If someone changes a config file tomorrow, will this prose become wrong?" If yes, rewrite the section to reference the source rather than restating it.

{内容}


**编写指南**：
- SKILL.md目标字数300-500字
- 优先使用具体示例而非抽象解释
- 相关时包含代码块或片段
- 使用相对路径关联其他Skill：`[skill-name](...)`
- 为LLM编写（清晰、结构化、无营销内容）
- **切勿复制源文件中的数据**。若信息可从仓库中已有的配置文件、脚本或定义中获取，请勿复制到Skill中。应告知Agent数据位置（`"运行scripts/deploy-info telecine获取当前服务列表"`）或要读取的文件（`"查看telecine/deploy/worker-resources.config.ts获取当前资源分配"`）。Skill应是推理指南，而非事实缓存。
- **检查内容漂移**：完成任何章节前，问自己：“如果明天有人修改配置文件，这段内容会失效吗？”如果是，重写章节以引用源文件而非重复内容。

Companion Scripts

配套脚本

Some skills need a companion script -- a script that queries local config files and emits current data for agents to consume. This replaces hardcoded tables and lists in skill prose.

When to create a companion script:

The skill domain involves configuration that changes (service lists, resource allocations, package versions, routing tables, secret names)
Multiple source files must be read and correlated to answer common questions
The source files are in formats that require domain knowledge to parse (Pulumi TypeScript, GitHub Actions YAML, complex configs)

Design principles:

Local only. No network, no Docker, no auth. The script parses files on disk. It should run in under a second.
Root-level. Place companion scripts at
```
scripts/
```
in the monorepo root, not inside a package.
Structured plain text output. One field per line, YAML-ish. Readable by humans and LLMs. Not JSON (too verbose for context windows), not pretty-printed tables (ambiguous to parse).
Thin wrapper pattern. A bash script (
```
scripts/{name}
```
) that calls
```
npx tsx scripts/{name}.ts
```
. Matches the existing convention (see
```
scripts/skills-sync
```
).

When NOT to create a companion script:

The data lives in a single, simple file the agent can read directly (e.g., a
```
package.json
```
)
The skill domain is purely procedural (how-to steps, debugging workflows)
The data rarely changes (deployment process, toolchain choices)

In these cases, just tell the agent which file to read:

"See telecine/deploy/worker-resources.config.ts for current allocations."

Example: The

deployments

skill uses

scripts/deploy-info telecine

and

scripts/deploy-info elements

to query current services, resources, routes, secrets, packages, and release pipeline steps from local config files.

部分Skill需要配套脚本——一种查询本地配置文件并输出当前数据供Agent使用的脚本。这替代了Skill文本中硬编码的表格和列表。

何时创建配套脚本：

Skill领域涉及易变的配置（服务列表、资源分配、包版本、路由表、密钥名）
需要读取并关联多个源文件才能回答常见问题
源文件格式需要领域知识才能解析（Pulumi TypeScript、GitHub Actions YAML、复杂配置）

设计原则：

仅限本地。无网络、无Docker、无认证。脚本仅解析磁盘上的文件，运行时间应在1秒内。
根目录存放。配套脚本放在单体仓库根目录的
```
scripts/
```
中，而非某个包内。
结构化纯文本输出。每行一个字段，类YAML格式。人类和LLM均可读取。不使用JSON（上下文窗口中过于冗长），不使用格式化表格（解析歧义）。
轻量包装模式。bash脚本（
```
scripts/{name}
```
）调用
```
npx tsx scripts/{name}.ts
```
。符合现有约定（见
```
scripts/skills-sync
```
）。

何时无需创建配套脚本：

数据存放在Agent可直接读取的单个简单文件中（如
```
package.json
```
）
Skill领域纯流程化（操作步骤、调试工作流）
数据极少变更（部署流程、工具链选择）

这些情况下，只需告知Agent要读取的文件：

"查看telecine/deploy/worker-resources.config.ts获取当前资源分配。"

示例：

deployments

Skill使用

scripts/deploy-info telecine

和

scripts/deploy-info elements

从本地配置文件中查询当前服务、资源、路由、密钥、包和发布流水线步骤。

Phase 4: Validation

阶段4：验证

Before syncing, validate the skill:

File structure check:

bash

# Verify files exist
ls -la .skills/internal/{skill-name}/

# Should see: SKILL.md (required)
# May see: references/ directory with additional .md files

Frontmatter validation:
- Required fields present:
```
name
```
  ,
```
description
```
- ```
name
```
  is kebab-case and matches directory name
- ```
description
```
  is a single sentence
- No syntax errors (valid YAML)
Content validation:
- Clear introductory section
- Well-organized subsections
- Concrete examples included
- Links formatted correctly:
```
[text](path)
```
  or
```
[text](references/file.md)
```
Drift check:
- Scan every section for enumerated data: tables of values, bulleted lists of names, hardcoded counts or versions
- For each instance, ask: "Does this data live in a source file that could change independently?"
- If yes: replace with a reference to the source file or companion script
- Common offenders: service/worker lists, resource allocations, package names, secret names, route tables, pipeline step lists, environment variables

Example check:

bash

# Manually verify the content structure
cat .skills/internal/{skill-name}/SKILL.md

同步前，验证Skill：

文件结构检查：

bash

# 验证文件存在
ls -la .skills/internal/{skill-name}/

# 应看到：SKILL.md（必填）
# 可能看到：包含额外.md文件的references/目录

前置元数据验证：
- 必填字段存在：
```
name
```
  、
```
description
```
- ```
name
```
  为短横线命名且与目录名匹配
- ```
description
```
  为一句话
- 无语法错误（有效YAML）
内容验证：
- 清晰的介绍章节
- 组织有序的子章节
- 包含具体示例
- 链接格式正确：
```
[文本](路径)
```
  或
```
[文本](references/file.md)
```
漂移检查：
- 扫描每个章节中的枚举数据：数值表格、名称项目符号列表、硬编码数量或版本
- 对每个实例，问：“这些数据是否存放在可能独立变更的源文件中？”
- 如果是：替换为源文件或配套脚本的引用
- 常见易漂移内容：服务/worker列表、资源分配、包名、密钥名、路由表、流水线步骤列表、环境变量

示例检查：

bash

# 手动验证内容结构
cat .skills/internal/{skill-name}/SKILL.md

Phase 5: Synchronization

阶段5：同步

Once the skill is complete and validated:

Confirm with user: "Ready to sync this skill across all agent directories?"
Run the sync script:
bash
```
npm run skills:sync
```

Verify the sync:

bash

# Check that files now exist in all 3 directories
ls -la .skills/internal/{skill-name}/SKILL.md
ls -la .cursor/skills/{skill-name}/SKILL.md
ls -la .claude/skills/{skill-name}/SKILL.md

Report success:

✅ Skill synced successfully!

Synced to:
- .skills/internal/ (canonical source)
- .cursor/skills/ (Cursor agent)
- .claude/skills/ (Claude Code agent)

Skill完成并验证后：

确认用户：“准备好将此Skill同步到所有Agent目录了吗？”
运行同步脚本：
bash
```
npm run skills:sync
```

验证同步结果：

bash

# 检查文件是否存在于所有3个目录中
ls -la .skills/internal/{skill-name}/SKILL.md
ls -la .cursor/skills/{skill-name}/SKILL.md
ls -la .claude/skills/{skill-name}/SKILL.md

报告成功：

✅ Skill同步成功！

已同步至：
- .skills/internal/（标准源）
- .cursor/skills/（Cursor Agent）
- .claude/skills/（Claude Code Agent）

Phase 6: Commit to Git

阶段6：提交到Git

If the skill is complete and approved:

Stage the changes:
bash
```
git add .skills/internal/{skill-name}/
```

Create a commit:

bash

git commit -m "Create {skill-name} skill"

Confirm commit:
bash
```
git log -1 --name-status
```

Skill完成并批准后：

暂存变更：
bash
```
git add .skills/internal/{skill-name}/
```

创建提交：

bash

git commit -m "Create {skill-name} skill"

确认提交：
bash
```
git log -1 --name-status
```

Complete Example Interaction

完整示例交互

User: "I need a skill for debugging video rendering issues"

Agent (Discovery Phase):

I'll help you create a debugging skill for video rendering. Let me gather some details:

Should this cover common rendering errors (artifacts, playback issues, encoding)?

Who are the primary users (developers, content creators)?

What systems does it cover (Elements, React, API)?

User: "Yes to all - it's for developers debugging Elements rendering."

Agent (Planning Phase):

Perfect! I'll create a reference skill called
elements-rendering-debug
with:
SKILL.md: Overview of debugging workflow

references/common-issues.md: Artifacts, playback, memory issues

references/diagnostics.md: How to inspect and troubleshoot

references/solutions.md: Common fixes and workarounds

Agent (Creation Phase):

Creating the skill structure...

[writes files]

Agent (Validation Phase):

Validating the skill: ✅ Directory structure correct ✅ SKILL.md frontmatter valid ✅ All references included ✅ Links formatted correctly

Agent (Sync Phase):

Ready to sync this skill across all agent directories?

Running: npm run skills:sync

✅ Synced successfully!

.skills/internal/elements-rendering-debug/ (canonical)

.cursor/skills/elements-rendering-debug/

.claude/skills/elements-rendering-debug/

Agent (Commit Phase):

Committing to git:
git add .skills/internal/elements-rendering-debug/
git commit -m "Add elements-rendering-debug skill"
✅ Complete! The skill is now available in all agent directories.

用户：“我需要一个用于调试视频渲染问题的Skill”

Agent（需求探索阶段）：

我将帮你创建一个视频渲染调试Skill。请提供一些细节：

是否需要涵盖常见渲染错误（ artifacts、播放问题、编码）？

主要用户是谁（开发者、内容创作者）？

涵盖哪些系统（Elements、React、API）？

用户：“全部涵盖 - 供开发者调试Elements渲染问题。”

Agent（规划阶段）：

完美！我将创建名为
elements-rendering-debug
的参考型Skill，包含：
SKILL.md：调试工作流概述

references/common-issues.md： artifacts、播放、内存问题

references/diagnostics.md：检查与故障排除方法

references/solutions.md：常见修复与解决方法

Agent（创建阶段）：

创建Skill结构中...

[写入文件]

Agent（验证阶段）：

验证Skill： ✅ 目录结构正确 ✅ SKILL.md前置元数据有效 ✅ 包含所有参考文件 ✅ 链接格式正确

Agent（同步阶段）：

准备好将此Skill同步到所有Agent目录了吗？

运行：npm run skills:sync

✅ 同步成功！

.skills/internal/elements-rendering-debug/（标准源）

.cursor/skills/elements-rendering-debug/

.claude/skills/elements-rendering-debug/

Agent（提交阶段）：

提交到Git：
git add .skills/internal/elements-rendering-debug/
git commit -m "Add elements-rendering-debug skill"
✅ 完成！该Skill现已在所有Agent目录中可用。

Example: Identifying and Extracting Volatile Data

示例：识别并提取易变数据

This example shows what happens when a first draft contains data that will drift.

Agent writes a deployment skill with a table:

Service CPU Memory Max Instances
web 1000m 1Gi 10
render-fragment 2000m 4Gi 200

Service	CPU	Memory	Max Instances
web	1000m	1Gi	10
render-fragment	2000m	4Gi	200

Review (Phase 4 drift check) catches this: the CPU, memory, and instance counts all come from

worker-resources.config.ts

and Pulumi

cloudrun.ts

files. If someone tunes render-fragment to 8Gi, the skill doc is immediately wrong.

Resolution: Create a companion script (

scripts/deploy-info

) that parses those source files and emits current values. Replace the table in the skill with:

Run
scripts/deploy-info telecine
to see current services and resource allocations.

The skill keeps its procedural and architectural content (how deployment works, how to scale resources, how to roll back). The volatile data is always queried fresh.

此示例展示初稿中包含易漂移数据时的处理方式。

Agent编写的部署Skill包含表格：

Service CPU Memory Max Instances
web 1000m 1Gi 10
render-fragment 2000m 4Gi 200

Service	CPU	Memory	Max Instances
web	1000m	1Gi	10
render-fragment	2000m	4Gi	200

审核（阶段4漂移检查）发现问题：CPU、内存和实例数均来自

worker-resources.config.ts

和Pulumi

cloudrun.ts

文件。若有人将render-fragment调整为8Gi，Skill文档会立即失效。

解决方案：创建配套脚本（

scripts/deploy-info

）解析这些源文件并输出当前值。将Skill中的表格替换为：

运行
scripts/deploy-info telecine
查看当前服务和资源分配。

Skill保留流程和架构内容（部署工作原理、如何扩展资源、如何回滚）。易变数据始终实时查询。

Updating Existing Skills

更新现有Skill

To update an existing skill:

Locate the skill:
bash
```
ls .skills/internal/{skill-name}/
```
Make changes:
- Edit SKILL.md content
- Add/modify reference files
- Update frontmatter if needed
Validate (same as Phase 4 above)
Sync:
bash
```
npm run skills:sync
```

Commit:

bash

git add .skills/internal/{skill-name}/
git commit -m "Update {skill-name} skill"

更新现有Skill步骤：

定位Skill：
bash
```
ls .skills/internal/{skill-name}/
```
进行变更：
- 编辑SKILL.md内容
- 添加/修改参考文件
- 必要时更新前置元数据
验证（同阶段4）
同步：
bash
```
npm run skills:sync
```

提交：

bash

git add .skills/internal/{skill-name}/
git commit -m "Update {skill-name} skill"

Skill Directory

Skill目录

List current skills by inspecting the canonical directory:

bash

ls .skills/internal/

Each subdirectory is a skill. Read its

SKILL.md

frontmatter for the name and description.

通过查看标准目录列出当前Skill：

bash

ls .skills/internal/

每个子目录对应一个Skill。读取其

SKILL.md

前置元数据获取名称和描述。

Key Files & Scripts

关键文件与脚本

Scripts

脚本

npm run skills:sync
- Sync internal skills to all agent directories
npm run skills:sync:dry
- Preview what would be synced
npm run skills:sync:verbose
- Detailed sync output
npm run skills:generate
- Generate external published skills

npm run skills:sync
- 将内部Skill同步到所有Agent目录
npm run skills:sync:dry
- 预览同步内容
npm run skills:sync:verbose
- 详细同步输出
npm run skills:generate
- 生成外部发布Skill

Directories

Documentation

文档

skills/SYNC.md
- Complete skills sync system documentation
.skills/internal/skills-docs/SKILL.md
- Detailed skills documentation system

skills/SYNC.md
- 完整Skill同步系统文档
.skills/internal/skills-docs/SKILL.md
- 详细Skill文档系统

Improving Skills From Use

通过使用改进Skill

Internal skills should self-improve through use. When an agent follows a skill and the result is wrong, incomplete, or suboptimal -- and the user provides feedback -- the agent should update the skill before finishing the task.

When to update a skill:

The skill's guidance led to an incorrect result that required user correction
The skill was missing a step or consideration that the user had to supply
The user provided a principle or constraint that generalizes beyond the current task

How to update:

Generalize. Extract the reusable lesson from the specific instance. "Always classify content as procedural, architectural, or enumerated" -- not "when building the deployments skill, we learned that service tables go stale."
Stay terse. A skill improvement should make the skill more precise, not longer. If adding a paragraph, look for one to remove or tighten.
Don't append. Skills are not logs. Don't add "lessons learned" sections or accumulate examples. Integrate the improvement into the existing structure -- revise a guideline, add a validation check, adjust a phase description.
Sync and commit. Skill updates follow the same workflow: edit in
```
.skills/internal/
```
, run
```
npm run skills:sync
```
, commit.

What NOT to do:

Don't record session-specific details ("on Feb 17 we discovered...")
Don't add every edge case as a new bullet point -- skills should stay general
Don't weaken existing guidance to accommodate a one-off exception

内部Skill应通过使用实现自我改进。当Agent遵循Skill指导但结果错误、不完整或次优，且用户提供反馈时，Agent应在完成任务前更新Skill。

何时更新Skill：

Skill指导导致错误结果，需用户纠正
Skill缺少用户必须补充的步骤或考虑因素
用户提供的原则或约束可推广到当前任务之外

更新方式：

通用化。从具体实例中提取可复用的经验。比如“始终将内容分类为流程类、架构类或枚举数据类”——而非“构建deployments Skill时，我们发现服务表格会失效”。
保持简洁。Skill改进应使Skill更精准，而非更长。若添加一段内容，应删除或精简一段现有内容。
不要追加。Skill不是日志。不要添加“经验教训”章节或累积示例。将改进整合到现有结构中——修订指南、添加验证检查、调整阶段描述。
同步并提交。Skill更新遵循相同工作流：在
```
.skills/internal/
```
中编辑，运行
```
npm run skills:sync
```
，提交。

请勿执行：

记录会话特定细节（“2月17日我们发现...”）
将每个边缘情况添加为新的项目符号——Skill应保持通用性
为了适应一次性例外而弱化现有指导

When NOT to Create a Skill

无需创建Skill的场景

A skill is not needed for:

One-off tasks or debugging sessions
Temporary utilities or scripts
Content that belongs in code comments
Questions that agents can answer inline

A skill is appropriate for:

Repeatable processes (create new projects, debug patterns)
Guidance that multiple agents should follow
Knowledge that needs to be discoverable
Practices that should be standardized

以下情况无需创建Skill：

一次性任务或调试会话
临时工具或脚本
属于代码注释的内容
Agent可直接回答的问题

以下情况适合创建Skill：

可重复流程（创建新项目、调试模式）
多个Agent应遵循的指导
需要可发现的知识
应标准化的实践

Tips for Good Skills

优质Skill技巧

✅ Clear purpose - One skill, one clear purpose or domain ✅ Self-contained - Can be understood independently ✅ Practical - Includes real examples and patterns ✅ Discoverable - Name clearly describes what it covers ✅ Linkable - References other skills when relevant ✅ Current - Updated when practices change

✅ 明确用途 - 一个Skill对应一个清晰的用途或领域 ✅ 独立完整 - 可独立理解 ✅ 实用性 - 包含真实示例和模式 ✅ 易发现 - 名称清晰描述涵盖内容 ✅ 可关联 - 相关时引用其他Skill ✅ 时效性 - 实践变更时及时更新

Troubleshooting

故障排除

Q: Skill not syncing? A: Run

npm run skills:sync:dry

to see if there are errors. Check file permissions in

.skills/internal/

Q: Should I edit in .cursor/ or .skills/? A: Always edit in

.skills/internal/

(canonical source). That's what gets committed to git.

Q: Can I have agent-specific skills? A: No, all agents get identical skills. Use

.skills/internal/

as the single source.

Q: How do I delete a skill? A: Delete from

.skills/internal/

, then run

npm run skills:sync

. The skill is automatically removed from agent directories.

Q: Need to revert a skill change? A: Use git:

git checkout HEAD -- .skills/internal/{skill-name}/

then

npm run skills:sync

Q: Skill无法同步？ A: 运行

npm run skills:sync:dry

查看是否有错误。检查

.skills/internal/

中的文件权限。

Q: 应在.cursor/还是.skills/中编辑？ A: 始终在

.skills/internal/

（标准源）中编辑。这是提交到Git的内容。

Q: 可以有Agent专属Skill吗？ A: 不行，所有Agent使用相同的Skill。使用

.skills/internal/

作为单一源。

Q: 如何删除Skill？ A: 从

.skills/internal/

中删除，然后运行

npm run skills:sync

。Skill会自动从Agent目录中移除。

Q: 需要回滚Skill变更？ A: 使用Git：

git checkout HEAD -- .skills/internal/{skill-name}/

然后运行

npm run skills:sync

。",