using-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

using-skills

The map, not the territory — and the map projects the ADOPTED surface, not the installed one. Install granularity is per-repo (

npx skills

pulls whole packs); usage granularity is per-skill. The gap between them is bloat, and it stays OUT of this file:

~/.agents/.skill-lock.json

records what is installed (L0), the generated skill manifest shows the full roster with the gap made visible (L1), and this file routes only what is actually in use (L2). Route by INTENT, not by remembering ~100 names. When the owner is already obvious, skip this map and enter the domain router or member directly.

Legend — type:

ROUTER

(meta-router skill) ·

SKILL

(direct member) ·

RECIPE

~/.claude/workflows/

recipe, entered THROUGH

using-workflows

) ·

RULE

~/.agents/rules/

file, not a skill). mode:

Skill()

model-invocable ·

manual

(

disable-model-invocation

— read its SKILL.md inline or use its slash command) ·

via-router

inline

(just do it).

Two-hop max:

using-skills

→ domain router → member. Never deeper, and never route back here from inside a domain router. Visual work always enters

using-design-skills

;

html

does not provide a route around its owner selection.

本文件是「地图」而非「实际领地」——且该地图仅展示已采用的技能范围，而非全部已安装技能。安装粒度为整个仓库（

npx skills

拉取完整包）；使用粒度为单个Skill。两者之间的差距即为冗余内容，且不会出现在本文件中：

~/.agents/.skill-lock.json

记录已安装的技能（L0），生成的skill manifest展示完整技能列表并显式标注差距（L1），而本文件仅路由实际正在使用的技能（L2）。按意图路由，而非记忆约100个技能名称。若归属已明确，跳过此映射直接进入领域路由器或成员。

图例 — 类型:

ROUTER

（元路由Skill）·

SKILL

（直接成员）·

RECIPE

（

~/.claude/workflows/

中的工作流，需通过

using-workflows

调用）·

RULE

（

~/.agents/rules/

中的文件，不属于Skill）。模式:

Skill()

可由模型调用 ·

manual

（

disable-model-invocation

— 阅读其内置SKILL.md或使用斜杠命令）·

via-router

inline

（直接执行）。

最多两跳路由：

using-skills

→ 领域路由器 → 成员。路由深度不得超过此，且领域路由器内部不得路由回此处。视觉类工作需始终进入

using-design-skills

；

html

技能无法绕过其归属选择流程。

Intent table — "I need to…" → target

意图对照表 —「我需要…」→ 目标

I need to…	Target	Type · mode
run loop-shaped work (audit / plan→build / consensus / triage)	`using-workflows`	ROUTER · Skill()
build/critique anything visual (page, screen, HTML deliverable, chart, artifact, motion, module/API design)	`using-design-skills`	ROUTER · Skill()
run/supervise a CLI as a tmux worker, or decide inline-vs-worker	`using-tmux-agent-tools`	ROUTER · Skill()
shape a fuzzy idea before building (parallel divergence: `adhd` )	`brainstorming`	SKILL · Skill()
stress-test a plan/decision/idea (frontier rounds; `grill-with-docs` when ADRs/glossary should be written as you go)	`grilling`	SKILL · Skill()
plan an effort too big for one session — chart it as decision tickets on the issue tracker, resolved one at a time	`wayfinder`	SKILL · manual
not sure which flow fits (kickoff, cross-domain, fuzzy situation)	`ask-nova`	SKILL · manual
check "is it actually done?"	`verification-before-completion`	SKILL · Skill()
dig a weird bug to root cause (loop version)	`root-cause-deep-dive-audit`	RECIPE · via `using-workflows`
reconcile docs/design vs code drift	`docs-vs-code-audit` / `design-vs-code-audit`	RECIPE · via `using-workflows`
sort a pile of audit findings	`findings-triage`	RECIPE · via `using-workflows`
get a second-model verdict on ONE artifact	`consensus-gate` (preferred; `oracle` for a one-off deep review)	RECIPE · via `using-workflows`
diagnose a bug inline	`diagnosing-bugs`	SKILL · Skill()
tidy or restructure code	`simplify` (just-written, behavior-preserving) · `refactor` (structural)	SKILL · Skill()
design a module/interface/domain (code, not pixels)	`design-an-interface` · `codebase-design` · `domain-modeling`	SKILL · Skill() (or via `using-design-skills` Pipeline D)
investigate a question / gather evidence	`research`	SKILL · Skill()
write tests / plan test coverage	`tdd` · `qa-test-planner`	SKILL · Skill()
drive a browser, test a web app, fill forms, screenshot / drive a device or TV app	`agent-browser` · `agent-device`	SKILL · Skill()
read a pasted URL (article, docs page)	`defuddle` (WebFetch replacement; not for `.md` URLs)	SKILL · Skill()
read or produce a PDF	`pdf`	SKILL · Skill()
hand off to a fresh session	`session-handoff`	SKILL · Skill()
write anything meant to be read (in-repo docs, problem writeup, long-form piece → md / html / Artifact / image)	`writing-artifacts` (unified writing entry: Stage 0 genre branch → `documentation-writing` for in-repo software docs, `writing-beats` / `writing-shape` for prose; `stop-slop` throughout, renders via `using-design-skills` )	SKILL · Skill()
commit / release	`git-commit` · `release-plannotator` (that repo only)	SKILL · Skill()
just implement something straightforward	—	inline (no skill; the domain is obvious)

Vocabulary loaded as criteria, not stations:

delegation-templates

(SKILL — every delegated worker prompt),

unknowns-discovery

(SKILL — surface assumptions first),

karpathy-guidelines

full-output-enforcement

(SKILL — coding discipline),

~/.agents/rules/judgment-rubrics.md

(RULE — decision scoring / wrong-direction signals / done-criteria).

我需要…	目标	类型 · 模式
执行循环类工作（审计 / 规划→构建 / 共识达成 / 问题分类）	`using-workflows`	ROUTER · Skill()
构建/评审任何视觉内容（页面、界面、HTML交付物、图表、制品、动效、模块/API设计）	`using-design-skills`	ROUTER · Skill()
以tmux worker身份运行/管理CLI，或决定采用内联还是worker模式	`using-tmux-agent-tools`	ROUTER · Skill()
在构建前梳理模糊想法（并行发散： `adhd` ）	`brainstorming`	SKILL · Skill()
对计划/决策/想法进行压力测试（前沿轮询；若需同步编写ADR/术语表则使用 `grill-with-docs` ）	`grilling`	SKILL · Skill()
规划超出单次会话范围的工作 — 将其拆分为问题追踪器上的决策工单，逐一解决	`wayfinder`	SKILL · manual
不确定适用哪个流程（启动阶段、跨领域、模糊场景）	`ask-nova`	SKILL · manual
检查「任务是否真的完成？」	`verification-before-completion`	SKILL · Skill()
深入排查疑难bug（循环版本）	`root-cause-deep-dive-audit`	RECIPE · 通过 `using-workflows` 调用
协调文档/设计与代码的偏差	`docs-vs-code-audit` / `design-vs-code-audit`	RECIPE · 通过 `using-workflows` 调用
整理审计发现结果	`findings-triage`	RECIPE · 通过 `using-workflows` 调用
获取第二个模型对单个制品的评估意见	`consensus-gate` （优先选择；如需一次性深度评审则使用 `oracle` ）	RECIPE · 通过 `using-workflows` 调用
内联诊断bug	`diagnosing-bugs`	SKILL · Skill()
整理或重构代码	`simplify` （刚编写完成，保留原有行为）· `refactor` （结构性重构）	SKILL · Skill()
设计模块/接口/领域（代码层面，非视觉层面）	`design-an-interface` · `codebase-design` · `domain-modeling`	SKILL · Skill()（或通过 `using-design-skills` 的Pipeline D调用）
调查问题 / 收集证据	`research`	SKILL · Skill()
编写测试 / 规划测试覆盖范围	`tdd` · `qa-test-planner`	SKILL · Skill()
驱动浏览器、测试Web应用、填写表单、截图 / 驱动设备或TV应用	`agent-browser` · `agent-device`	SKILL · Skill()
读取粘贴的URL（文章、文档页面）	`defuddle` （替代WebFetch；不适用于 `.md` 格式URL）	SKILL · Skill()
读取或生成PDF	`pdf`	SKILL · Skill()
切换到新会话	`session-handoff`	SKILL · Skill()
编写任何需要被阅读的内容（仓库内文档、问题描述、长篇内容 → md / html / Artifact / 图片）	`writing-artifacts` （统一写作入口：阶段0按体裁分支 → 仓库内软件文档使用 `documentation-writing` ，散文类使用 `writing-beats` / `writing-shape` ；全程使用 `stop-slop` ，通过 `using-design-skills` 渲染）	SKILL · Skill()
提交代码 / 发布版本	`git-commit` · `release-plannotator` （仅限对应仓库）	SKILL · Skill()
直接实现简单明确的内容	—	inline（无需Skill；领域归属已明确）

以下词汇作为判定标准加载，而非独立技能：

delegation-templates

（SKILL — 所有委派工作的提示模板），

unknowns-discovery

（SKILL — 先梳理隐含假设），

karpathy-guidelines

full-output-enforcement

（SKILL — 编码规范），

~/.agents/rules/judgment-rubrics.md

（RULE — 决策评分 / 方向错误信号 / 完成判定标准）。

Adopted families beyond the table — one line each

对照表之外的已采用技能家族 — 每行一项

Meta-routers (backbone) → this map +
```
using-design-skills
```
,
```
using-workflows
```
,
```
using-tmux-agent-tools
```
; enter a domain router directly when the goal names it.
Design-visual →
```
html
```
/
```
html-*
```
,
```
diagram-design
```
,
```
impeccable
```
,
```
design-taste-frontend
```
,
```
high-end-visual-design
```
,
```
apple-design
```
,
```
imagegen-*
```
,
```
image-to-code
```
,
```
data-report
```
— ALWAYS through
```
using-design-skills
```
, the sole arbiter among overlapping anti-slop members (default
```
impeccable
```
; new landing pages →
```
design-taste-frontend
```
; Apple-grade polish →
```
apple-design
```
; house-style diagrams →
```
diagram-design
```
, one-off/interactive diagrams →
```
html-diagram
```
).
Ideation →
```
brainstorming
```
(mandatory gate before creative work),
```
adhd
```
(parallel divergence),
```
prototype
```
(throwaway prototype answers a design question).
Grilling →
```
grilling
```
(the implementation — asks each frontier of questions in one round, numbered, each with a recommended answer; dispatches sub-agents for facts).
```
grill-me
```
/
```
grill-with-docs
```
are manual slash entries into it; the latter runs
```
domain-modeling
```
alongside for ADRs/glossary.
Workflow orchestration →
```
codex-dynamic-workflows
```
, via
```
using-workflows
```
(approved designs only).

Delegation →

tmux-agent-tools

delegation-templates

via

using-tmux-agent-tools

; in-session parallel dispatch:

dispatching-parallel-agents

subagent-driven-development

(direct).

Git ops →

git-commit

resolving-merge-conflicts

;

review-renovate

(supply-chain review, direct).

Ingest →
```
defuddle
```
,
```
pdf
```
,
```
arc-artifact-fetcher
```
(NOT in the skill lock — unmanaged),
```
context7-cli
```
(library docs only; skill discovery belongs to
```
find-skills
```
).
Continuity / memory →
```
session-handoff
```
,
```
shared-memory-intake
```
(curate shared Codex memory / submit external findings).
Fleet meta →
```
skill-creator
```
owns the create/optimize/eval PROCESS, with
```
writing-great-skills
```
loaded as drafting criteria at every write/edit step (the stop-slop pattern);
```
find-skills
```
(discovery/install).
Project-specific (Plannotator) →
```
pierre-guard
```
,
```
release-plannotator
```
— only inside that repo.

元路由器（核心架构） → 本映射 +
```
using-design-skills
```
、
```
using-workflows
```
、
```
using-tmux-agent-tools
```
；若目标明确指定领域，直接进入该领域路由器。
设计-视觉类 →
```
html
```
/
```
html-*
```
、
```
diagram-design
```
、
```
impeccable
```
、
```
design-taste-frontend
```
、
```
high-end-visual-design
```
、
```
apple-design
```
、
```
imagegen-*
```
、
```
image-to-code
```
、
```
data-report
```
— 必须通过
```
using-design-skills
```
调用，它是解决重叠防冗余成员的唯一仲裁者（默认使用
```
impeccable
```
；新落地页使用
```
design-taste-frontend
```
；苹果级精致设计使用
```
apple-design
```
；统一风格图表使用
```
diagram-design
```
，一次性/交互式图表使用
```
html-diagram
```
）。
创意构思类 →
```
brainstorming
```
（创意工作前的强制环节）、
```
adhd
```
（并行发散）、
```
prototype
```
（一次性原型用于解答设计问题）。
压力测试类 →
```
grilling
```
（具体实现 — 一次性提出各维度的前沿问题并编号，每个问题附推荐答案；调度子Agent获取事实）。
```
grill-me
```
/
```
grill-with-docs
```
是手动斜杠调用入口；后者会同步运行
```
domain-modeling
```
以生成ADR/术语表。
工作流编排类 →
```
codex-dynamic-workflows
```
，通过
```
using-workflows
```
调用（仅用于已批准的设计）。

任务委派类 →

tmux-agent-tools

delegation-templates

，通过

using-tmux-agent-tools

调用；会话内并行调度：

dispatching-parallel-agents

、

subagent-driven-development

（直接调用）。

Git操作类 →
```
git-commit
```
、
```
resolving-merge-conflicts
```
；
```
review-renovate
```
（供应链评审，直接调用）。
内容导入类 →
```
defuddle
```
、
```
pdf
```
、
```
arc-artifact-fetcher
```
（不在skill lock中 — 未被管理）、
```
context7-cli
```
（仅用于库文档；技能发现属于
```
find-skills
```
）。
连续性/记忆类 →
```
session-handoff
```
、
```
shared-memory-intake
```
（整理共享Codex记忆 / 提交外部发现结果）。
集群元管理类 →
```
skill-creator
```
负责创建/优化/评估流程，编写/编辑的每一步都会加载
```
writing-great-skills
```
作为起草标准（防冗余模式）；
```
find-skills
```
（技能发现/安装）。
项目专属类（Plannotator） →
```
pierre-guard
```
、
```
release-plannotator
```
— 仅限对应仓库内使用。

Dormant — installed, not routed

休眠状态 — 已安装但未路由

Whole packs or chains that are installed (in the lock, listed in the skill manifest) but currently unused. They cost nothing while dormant; wake one by reading its SKILL.md and, if it sticks, promote it into the table above:

matt planning/tracker:
```
triage
```
·
```
wizard
```

niche code-craft:

improve-codebase-architecture

migrate-to-shoehorn

request-refactor-plan

qa

misc singles:
```
update-deps
```

已安装（在lock文件中，列于skill manifest）但当前未使用的完整包或技能链。休眠状态下无任何消耗；若需启用，阅读其SKILL.md，若适用则将其提升至上方对照表中：

matt规划/追踪类：
```
triage
```
·
```
wizard
```

小众代码工艺类：

improve-codebase-architecture

、

migrate-to-shoehorn

、

request-refactor-plan

、

qa

其他单个技能：
```
update-deps
```

Secondary view — the idea→ship lifecycle

次级视角 — 从想法到交付的生命周期

A journey, not the primary index (most tasks enter mid-stream via the table):

brainstorming

→

grilling

→ plan (via

using-workflows

: plan-pipeline / feature-plan-consensus, tracked in a

.workflow/

run dir) → build (via

using-workflows

lifecycle, or

using-design-skills

for visual) →

verification-before-completion

. Keep brainstorm→plan in ONE context window; use

session-handoff

at a session seam, not a

/compact

这是一个流程路径，而非主索引（大多数任务通过对照表进入流程中段）：

brainstorming

→

grilling

→ 规划（通过

using-workflows

：plan-pipeline / feature-plan-consensus，在

.workflow/

运行目录中跟踪）→ 构建（通过

using-workflows

生命周期，或视觉类通过

using-design-skills

）→

verification-before-completion

。将头脑风暴→规划阶段放在同一个上下文窗口中；仅在会话衔接处使用

session-handoff

，而非

/compact

。

Curated map vs live availability

精选映射与实时可用状态

This file is CURATED first-hop navigation over the ADOPTED surface. It is NOT the inventory of what is installed. For "does skill X exist on this machine / which runtime sees it / is it manual-only / how bloated is a source repo", consult the generated skill manifest (per-repo roster with the installed-vs-adopted gap visible) and the live directories — never assume from this map.

本文件是针对已采用技能范围的精选一级导航。它并非已安装技能的清单。若需查询「Skill X是否存在于本机 / 哪个运行时可见 / 是否仅支持手动调用 / 源仓库冗余度如何」，请查阅生成的skill manifest（展示仓库级技能列表并显式标注已安装vs已采用的差距）和实时目录 — 切勿仅凭本映射做出假设。

Red flags — rationalizations that have burned us

警示信号 — 曾导致问题的合理化借口

Naming one and proceeding anyway requires a stated reason:

「這只是小問題，不用 skill」— if the domain is obvious, go direct; if ownership is unclear, let this map decide. Don't skip routing on substantial work — but don't force the map when the owner is already plain.
「我記得那支 skill / recipe 的內容」— members evolve; read the live SKILL.md or recipe header before acting. Never route from memory of an old inventory.
「先做完再回頭套流程」— for loop-shaped or visual work the router picks the RIGHT process first; retrofitting it is how half-done work ships.
「裝了就該路由」— installed ≠ adopted. A dormant pack stays dormant until a real task wakes it; never widen the table to mirror the lock.

若使用以下借口并继续操作，需说明理由：

「這只是小問題，不用Skill」— 若领域归属明确，直接进入；若归属不明确，由本映射决定。对于重要工作不要跳过路由 — 但当归属已明确时也无需强制使用映射。
「我記得那支Skill/工作流的內容」— 成员会不断演进；操作前请阅读最新的SKILL.md或工作流头部内容。切勿根据旧技能清单的记忆进行路由。
「先做完再回頭套流程」— 对于循环类或视觉类工作，路由器会先选择正确的流程；事后补流程是导致半成品交付的原因。
「裝了就該路由」— 已安装≠已采用。休眠包保持休眠状态直到实际任务启用它；切勿为了匹配lock文件而扩大对照表范围。

Subagent exemption

子Agent豁免规则

A delegated worker executing one assigned task does NOT enter this router — the dispatcher already routed; the worker follows its brief.

执行指定任务的委派Worker无需进入此路由器 — 调度器已完成路由；Worker只需遵循其任务说明。

Freshness self-check (this map WILL drift)

新鲜度自检（本映射必然会滞后）

It lists intents and paths, not a registry. When routing feels off, confirm the map still matches the machine — check the SKILL fleet (not workflow-manifest, which inventories recipes), across BOTH runtime dirs:

bash

installed=$(ls ~/.claude/skills ~/.agents/skills 2>/dev/null | grep -v '^$' | grep -v ':$' | sort -u | wc -l | tr -d ' ')
locked=$(node -e 'const j=require(process.env.HOME+"/.agents/.skill-lock.json");console.log(Object.keys(j.skills||{}).length)' 2>/dev/null)
echo "installed(union)=$installed locked=$locked"

A large mismatch, a station skill that no longer resolves, or a member the active available-skills listing does not show → the map is stale: regenerate the skill manifest before trusting a name here.

本文件列出意图和路径，而非注册表。当路由感觉异常时，确认映射仍与本机状态匹配 — 检查Skill集群（而非工作流清单，后者是工作流的清单），覆盖两个运行时目录：

bash

installed=$(ls ~/.claude/skills ~/.agents/skills 2>/dev/null | grep -v '^$' | grep -v ':$' | sort -u | wc -l | tr -d ' ')
locked=$(node -e 'const j=require(process.env.HOME+"/.agents/.skill-lock.json");console.log(Object.keys(j.skills||{}).length)' 2>/dev/null)
echo "installed(union)=$installed locked=$locked"

若两者差距较大、某个技能无法解析，或活跃可用技能列表中未显示某个成员 → 映射已过期：在信任本映射中的名称前，重新生成skill manifest。

NOT-FOUND

未找到匹配项

No intent fits and it is not loop-shaped or visual → check the Dormant list above (installed but unrouted — wake it), then the active available-skills listing, then plain inline work. A genuinely new recurring intent → propose a new skill/recipe to the user; never improvise a half-router inline.

无匹配意图且不属于循环类或视觉类工作 → 先检查上方的休眠列表（已安装但未路由 — 可启用），再检查活跃可用技能列表，最后考虑直接内联工作。若确实是新的重复出现的意图 → 向用户提议新的Skill/工作流；切勿在内部临时拼凑半路由方案。