pythia-skill-author

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Authoring a New Skill

创建新Skill

Announce at start: "Using pythia-skill-author — let's capture how you actually work."

A skill is a decision captured so it never has to be re-argued. Capture what the team actually does — with evidence from the database — not what anyone remembers about it.

会话开始时告知：“正在使用pythia-skill-author —— 让我们记录下你实际的工作方式。”

Skill是对决策的固化记录，无需再反复争论。记录团队实际执行的内容——以数据库中的证据为准——而非任何人的记忆。

Step 1 — Interview, one question at a time

步骤1 —— 逐一提问访谈

Ask, in order, waiting for each answer:

**What task is this for?» One skill per concern — "our report procedure ritual" is one skill; "everything about our team" is not.
When should it trigger? Collect the developer's own words — the phrases they would type ("làm báo cáo", "clone the export proc", an error code, a file pattern). These go into the description verbatim; triggering lives or dies on them.
Which parts are law, which are taste? Hard rules get an Iron Law and a red-flags table; preferences get a "default unless told otherwise".
What does wrong look like? Past incidents make the best red-flag rows.

按顺序提出以下问题，等待每个问题的答复：

该Skill针对什么任务？ 一个Skill对应一个关注点——“我们的报告流程”是一个Skill；“关于团队的所有内容”则不是。
何时触发该Skill？ 收集开发者的原话——他们会输入的短语（例如“làm báo cáo”、“clone the export proc”、错误代码、文件模式）。这些内容将原封不动地放入描述中；触发效果完全依赖于这些短语。
哪些部分是硬性规则，哪些是偏好选择？ 硬性规则需标注为“Iron Law”并添加红标表格；偏好选择则标注为“默认遵循，除非另有说明”。
错误示例是什么样的？ 过往事件是红标行的最佳素材。

Step 2 — Mine the evidence

步骤2 —— 挖掘证据

Memory lies; the schema does not. Before writing a line:

```
pythia similar <TYPICAL_NAME>
```
→ which family of programs embodies this workflow; open the top hits with
```
pythia src
```
and extract the actual naming, parameter and structure conventions.
```
pythia args
```
/
```
pythia cols
```
for the signatures and types the skill will tell people to use.
Save two or three short verbatim snippets as examples — real code outranks invented code.

记忆不可靠，但数据库不会出错。在开始编写前：

```
pythia similar <TYPICAL_NAME>
```
→ 找出体现此工作流程的程序类别，使用
```
pythia src
```
打开排名靠前的结果，提取实际的命名、参数和结构惯例。
使用
```
pythia args
```
/
```
pythia cols
```
获取Skill将指导使用的签名和类型。
保存两到三个简短的原文片段作为示例——真实代码比虚构代码更具权威性。

Step 3 — Draft in the house format

步骤3 —— 按照内部格式起草

Frontmatter: kebab-case
```
name
```
matching the folder;
```
description
```
that opens with the trigger condition (
```
Use when ...
```
) and contains the developer's phrases from step 1.
Body budget ~150 lines. Long material (templates, checklists, snippet libraries) goes to
```
reference/
```
and is linked, not pasted.
Structure menu — use what the answers call for, skip the rest: Iron Law (one line, caps) · numbered workflow · red-flags table ("thought → reality") · "When NOT to use" · an Announce at start line.
Write in the language the team works in; this pack is English, a private team skill may be Vietnamese — the developer decides.

Not everything needs a skill. Pure naming and style rules travel better as

.pythia/conventions.json

(machine-checked at every apply preview) plus

.pythia/conventions.md

(prose the agent reads). Reserve skills for workflows — things with steps, gates and judgment.

前置内容：使用短横线分隔的小写
```
name
```
，与文件夹名称匹配；
```
description
```
需以触发条件开头（
```
Use when ...
```
），并包含步骤1中开发者提供的短语。
正文篇幅控制在约150行以内。较长内容（模板、检查表、代码片段库）应放入
```
reference/
```
目录并通过链接引用，而非直接粘贴。
结构菜单——根据回答选择所需模块，其余可省略：Iron Law（一行大写）· 编号工作流程 · 红标表格（“想法→实际情况”）· “何时不使用” · 会话开始时告知语句。
使用团队日常工作语言编写；本套件为英文，私有团队Skill可使用越南语——由开发者决定。

并非所有内容都需要做成Skill。 纯命名和样式规则更适合以

.pythia/conventions.json

（每次应用预览时由机器检查）加

.pythia/conventions.md

（供Agent读取的说明文档）的形式呈现。Skill应保留给工作流程——即包含步骤、关卡和判断逻辑的内容。

Step 4 — Place it

步骤4 —— 存放位置

User skills live in the developer's project, e.g.

.claude/skills/<name>/SKILL.md

for Claude Code (other agents: the layout

skills/<name>/SKILL.md

works with

npx skills add

). Never write into the installed pythia pack — updates would overwrite it, and the pack's lint enforces its own fixed skill list.

用户Skill需存放在开发者的项目中，例如Claude Code对应的

.claude/skills/<name>/SKILL.md

（其他Agent：

skills/<name>/SKILL.md

的结构可兼容

npx skills add

命令）。切勿写入已安装的pythia套件——更新会覆盖该内容，且套件的代码检查会强制执行其固定的Skill列表。

Step 5 — Verify it triggers

步骤5 —— 验证触发效果

In a fresh session, give a task phrased the way the developer would really ask (step 2's phrases). The skill must activate unprompted. If it does not, the description is the bug: sharpen it with the exact phrases that failed, and test again.

在全新会话中，以开发者实际会使用的表述方式提出任务（即步骤2中的短语）。Skill必须自动激活，无需手动触发。若未激活，则说明描述存在问题：添加触发失败时使用的精确短语来优化描述，然后再次测试。

Keep it alive

保持Skill的时效性

When the developer corrects the agent for the same thing twice, propose folding that correction into the skill — that is the skill earning its keep. Retire rules that stopped being true; a stale skill is worse than none.

当开发者第二次纠正Agent的同一问题时，建议将该纠正内容整合到Skill中——这正是Skill的价值所在。淘汰不再适用的规则；过时的Skill比没有Skill更糟糕。

Before sharing outside the team

向团队外分享前的检查

Run the hygiene check this pack applies to itself: no hosts, schema names, credentials, or internal identifiers in the skill or its references. What is fine in a private repo is a leak in a public one.

运行本套件自带的合规检查：确保Skill及其引用内容中不包含主机名、数据库表名、凭证或内部标识符。在私有仓库中没问题的内容，在公共仓库中可能会造成信息泄露。

Red Flags — STOP if you catch yourself thinking

红标警示——若出现以下想法请立即停止

Thought	Reality
"I'll write it from memory of this chat"	Mine `similar` / `src` first — the codebase is the authority.
"One big skill covering everything"	One concern per skill, or nothing triggers cleanly.
"Paste the whole style guide in"	Budget is ~150 lines; long material goes to reference/.
"The description can be generic"	Generic descriptions never trigger. Use the developer's own phrases.
"It works, no need to test triggering"	Untested triggering = a skill nobody ever sees again.

想法	实际情况
“我会根据本次聊天的记忆来编写”	先使用 `similar` / `src` 挖掘信息——代码库才是权威来源。
“用一个大Skill涵盖所有内容”	一个Skill对应一个关注点，否则无法清晰触发。
“把整个样式指南粘贴进来”	篇幅控制在约150行以内；较长内容应放入reference/目录。
“描述可以写得通用一些”	通用描述永远无法触发。请使用开发者的原话。
“它能用，没必要测试触发效果”	未测试触发效果的Skill会被所有人遗忘。