author-auth0-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Authoring an Auth0 skill reference

编写Auth0 skill参考内容

Add or edit guidance in the single

auth0

skill (

plugins/auth0/skills/auth0/

). This walks you through structure + router wiring so the change passes CI on the first try.

Source of truth (read, don't duplicate):

CONTRIBUTING.md

and

docs/architecture.md

在单个

auth0

skill（

plugins/auth0/skills/auth0/

）中添加或编辑相关指南。本指南将带您完成结构搭建与路由配置，确保修改首次提交即可通过CI校验。

权威参考（仅阅读，请勿复制）：

CONTRIBUTING.md

和

docs/architecture.md

。

Critical rules (get these wrong and CI fails)

关键规则（违反将导致CI失败）

Depth-3 tree + reachability: every reference is a directory
```
<name>/
```
containing an
```
index.md
```
, and that directory name MUST be named in a
```
SKILL.md
```
router table. Start index-only (the whole reference lives in
```
index.md
```
, no leaves — one hop from the router).
```
index.md
```
MUST NOT exceed 1000 lines — once it passes ~500 lines, consider splitting it into a leaf group (
```
index.md
```
becomes a hub — shared prerequisites + an intent→leaf dispatch table — over document-section leaves), but only if the content actually separates into distinct sections; don't split a reference that's long but cohesive. An index-only
```
index.md
```
, and any leaf inside a leaf group, MUST NOT link to any other
```
.md
```
file — they are sinks. The only second hop allowed is a leaf-group hub dispatching to leaves in its own directory; cross-group links are forbidden. Both are stated in full under
```
CONTRIBUTING.md
```
→ "Make it routable"
and
```
CONTRIBUTING.md
```
→ "Adding a reference"
; the paths below tell you which table to edit.
Strict mode: avoid vague quality adverbs that assert an outcome without showing it — state the concrete behavior instead (what happens, to what, when); give a positive alternative for every prohibition; hoist MUST/NEVER directives near the top of the file.

三级目录结构 + 可达性：每个参考内容都对应一个
```
<name>/
```
目录，目录下包含
```
index.md
```
文件，且该目录名称必须在
```
SKILL.md
```
的路由表中声明。初始阶段请采用仅索引文件的形式（所有参考内容都放在
```
index.md
```
中，无子文件——仅需通过路由跳转一次）。
```
index.md
```
的行数不得超过1000行——当行数达到约500行时，可考虑将其拆分为叶子组（
```
index.md
```
变为枢纽文件，包含共享前置条件以及意图→叶子文件的调度表，对应文档各章节的叶子文件），但仅当内容确实可划分为不同独立章节时才进行拆分；对于内容连贯的长文档，请勿拆分。仅索引形式的
```
index.md
```
以及叶子组中的任何叶子文件，不得链接到其他
.md
文件——它们是终端节点。仅允许的二次跳转是叶子组的枢纽文件跳转到其自身目录下的叶子文件；跨组链接是被禁止的。上述规则在
```
CONTRIBUTING.md
```
→ "确保可路由"
和
```
CONTRIBUTING.md
```
→ "添加参考内容"
中有完整说明；下文路径将告知您需要编辑哪张表。
严格模式：避免使用模糊的修饰性副词来断言结果却不展示具体过程——应改为陈述具体行为（发生了什么、作用于什么、何时发生）；对于每一项禁止性要求，都要给出对应的正向替代方案；将MUST/NEVER类指令放在文件顶部附近。

Step 0 — Classify the contribution

步骤0 — 对贡献内容进行分类

What you're adding	Prefix	Router edits
A single SDK/framework integration	`framework-<name>/`	Step 2 all 3 tiers (+ variant row if web/API split)
A capability spanning frameworks	`feature-<name>/`	Step 1 intent row + Step 4 load block
A provisioning tool	`tooling-<name>/`	Step 3 tooling table
Cross-cutting guidance	`pattern-<name>/`	Step 4 load block(s) referencing it
Editing an existing reference	(n/a)	Usually none — re-check the depth-3 tree rules

Then follow the matching path below.

您要添加的内容类型	前缀	路由编辑操作
单个SDK/框架集成	`framework-<name>/`	步骤2中的所有三层（若存在Web/API拆分，则需添加变体行）
跨框架的功能	`feature-<name>/`	步骤1添加意图行 + 步骤4添加加载块
配置工具	`tooling-<name>/`	步骤3添加工具表行
跨领域指南	`pattern-<name>/`	步骤4添加引用它的加载块
编辑现有参考内容	(无)	通常无需操作——重新检查三级目录结构规则即可

然后遵循下方对应的路径操作。

Path A — New framework reference

路径A — 新增框架参考内容

Create
```
plugins/auth0/skills/auth0/references/framework-<slug>/index.md
```
(kebab-case directory). Start index-only: the whole reference lives in
```
index.md
```
, following the split used by peers (
```
## Setup
```
,
```
## Integration
```
,
```
## API
```
sections); self-contained (no
```
.md
```
links). Only split into a leaf group once it's large — see "Splitting into a leaf group" below.
Wire detection into all three tiers of Step 2 in
```
plugins/auth0/skills/auth0/SKILL.md
```
:
- Tier 1 — the Auth0 SDK package row (e.g.
```
@auth0/auth0-remix
```
  →
```
remix
```
  ). Put it above less-specific rows.
- Tier 2 — the non-Auth0 workspace dependency row (e.g.
```
@remix-run/react
```
  in
```
package.json
```
  →
```
remix
```
  ).
- Tier 3 — the prompt-keyword row (e.g. "Remix" →
```
remix
```
  ).
If the framework has a web-app vs API split, add a row to Variant disambiguation.
No separate list to update: the reachability checker derives routable slugs from the backticked value column of these tables, so naming
```
<slug>
```
in a table makes
```
framework-<slug>/index.md
```
reachable.
The
```
integrate
```
load block in Step 4 already reads
```
references/framework-{framework}/index.md
```
— no Step 4 edit needed.

创建
```
plugins/auth0/skills/auth0/references/framework-<slug>/index.md
```
（目录采用短横线分隔命名法）。初始采用仅索引文件形式：所有参考内容都放在
```
index.md
```
中，遵循同类文件的结构（分为
```
## 安装配置
```
、
```
## 集成
```
、
```
## API
```
等章节）；确保内容自包含（无
```
.md
```
文件链接）。仅当文档篇幅较大时才拆分为叶子组——详见下方“拆分为叶子组”部分。
在
```
plugins/auth0/skills/auth0/SKILL.md
```
的步骤2中，将检测逻辑接入所有三层：
- 第一层——Auth0 SDK包行（例如
```
@auth0/auth0-remix
```
  →
```
remix
```
  ）。将其放在特异性较低的行上方。
- 第二层——非Auth0工作区依赖行（例如
```
package.json
```
  中的
```
@remix-run/react
```
  →
```
remix
```
  ）。
- 第三层——提示关键词行（例如“Remix” →
```
remix
```
  ）。
如果框架存在Web应用与API的拆分，需在变体消歧义部分添加一行。
无需更新单独的列表：可达性检查器会从这些表格的反引号值列中提取可路由的slug，因此在表格中命名
```
<slug>
```
即可让
```
framework-<slug>/index.md
```
具备可达性。
步骤4中的
```
integrate
```
加载块已默认读取
```
references/framework-{framework}/index.md
```
——无需编辑步骤4。

Path B — New feature reference

路径B — 新增功能参考内容

Create
```
plugins/auth0/skills/auth0/references/feature-<slug>/index.md
```
(index-only, self-contained — see "Splitting into a leaf group" below for when to add leaves).
Add an intent row to the Step 1 table. The
```
Intent
```
value is a lookup key reused verbatim as a Step 4 heading. Describe the goal in plain language, not just the Auth0 term. Example row:
```
| Let users sign in without a password ... *Auth0: passwordless.* | **feature:passwordless** |
```

Add a matching load block in Step 4 whose heading is that intent. The heading is Markdown (

### feature:passwordless

); the

Read:

lines sit inside a fenced block beneath it, matching the existing Step 4 blocks:

### feature:passwordless
```
Read: references/feature-passwordless/index.md
Read: references/tooling-{tooling}/index.md
If framework detected: Read references/framework-{framework}/index.md
```

创建
```
plugins/auth0/skills/auth0/references/feature-<slug>/index.md
```
（采用仅索引文件形式，内容自包含——何时添加叶子文件详见下方“拆分为叶子组”部分）。
在步骤1的表格中添加意图行。
```
Intent
```
值是一个查找键，需与步骤4的标题完全一致。用通俗易懂的语言描述目标，而非仅使用Auth0术语。示例行：
```
| 让用户无需密码即可登录……*Auth0：无密码认证。* | **feature:passwordless** |
```

在步骤4中添加匹配的加载块，其标题为该意图值。标题采用Markdown格式（

### feature:passwordless

）；

Read:

行放在标题下方的代码块中，与现有步骤4的块格式一致：

### feature:passwordless
```
Read: references/feature-passwordless/index.md
Read: references/tooling-{tooling}/index.md
If framework detected: Read references/framework-{framework}/index.md
```

Path C — New tooling or pattern reference

路径C — 新增工具或模式参考内容

Tooling: create
```
plugins/auth0/skills/auth0/references/tooling-<slug>/index.md
```
, then add a row to the Step 3 table. Backtick the value exactly as the existing rows do (
```
| <project signal> | `tooling-<slug>/index.md` |
```
) — reachability picks up tooling references only via their backticked group name, so an unbackticked value leaves the reference unreachable. Note
```
validate-skill.sh
```
hardcodes
```
cli mcp terraform
```
— a genuinely new tooling reference also needs that list extended.
Pattern: create
```
plugins/auth0/skills/auth0/references/pattern-<slug>/index.md
```
, then reference it from the relevant Step 4 load block(s) (patterns are pulled in conditionally, e.g.
```
pattern-multi-tenant/index.md
```
under
```
guidance
```
).
```
validate-skill.sh
```
hardcodes
```
security token-handling multi-tenant rate-limiting common-errors
```
— extend that list for a new pattern reference.

工具类：创建
```
plugins/auth0/skills/auth0/references/tooling-<slug>/index.md
```
，然后在步骤3的表格中添加一行。反引号中的值需与现有行完全一致（
```
| <项目标识> | `tooling-<slug>/index.md` |
```
）——仅通过反引号中的组名，可达性检查器才能识别工具类参考内容，因此未加反引号的值会导致参考内容不可达。注意
```
validate-skill.sh
```
中硬编码了
```
cli mcp terraform
```
——若新增的是真正全新的工具类参考内容，还需扩展该列表。
模式类：创建
```
plugins/auth0/skills/auth0/references/pattern-<slug>/index.md
```
，然后在相关的步骤4加载块中引用它（模式类内容会被条件性调用，例如
```
guidance
```
下的
```
pattern-multi-tenant/index.md
```
）。
```
validate-skill.sh
```
中硬编码了
```
security token-handling multi-tenant rate-limiting common-errors
```
——若新增模式类参考内容，需扩展该列表。

Path D — Editing an existing reference

路径D — 编辑现有参考内容

Usually no router edit. Before finishing: confirm you introduced no link to another

.md

file from an index-only

index.md

or a leaf, and that any new prohibition has a positive alternative and any weak language is reworded. If you're editing a leaf group's hub, confirm any new

Read:

dispatch still points only at a leaf in its own directory.

通常无需编辑路由。完成编辑前：确认您未在仅索引形式的

index.md

或叶子文件中添加指向其他

.md

文件的链接；确认所有新增的禁止性要求都有对应的正向替代方案，且所有模糊表述都已修改。若您编辑的是叶子组的枢纽文件，确认所有新增的

Read:

调度仅指向其自身目录下的叶子文件。

Step 5 — Splitting into a leaf group (only for large references)

步骤5 — 拆分为叶子组（仅适用于大篇幅参考内容）

Skip this step for an index-only reference. Past ~500 lines (the 1000-line cap is in "Critical rules" above), consider splitting into a leaf group so the router pulls just the slice a task needs — but only if the content actually separates into distinct sections; a long but cohesive reference stays index-only:

references/framework-<slug>/
├── index.md          # hub: shared prerequisites + intent→leaf dispatch table
├── integrate.md      # document-section leaves (one per section, not per intent)
├── api-reference.md
├── patterns.md
├── setup.md
└── migration.md      # only if the SDK has a major-version migration

Leaves are document sections, not intents (
```
integrate
```
,
```
api-reference
```
,
```
patterns
```
,
```
setup
```
,
```
migration
```
, …).
index.md
becomes a lean hub: shared setup every leaf needs, then a dispatch table with one row per router intent, each an imperative
```
`Read: references/<slug>/<leaf>.md`
```
pointing at that intent's primary leaf. Intent strings must match Step 1 exactly (
```
feature:mfa
```
, not
```
mfa
```
). A "Then, if the task requires it" list of
```
Read:
```
bullets makes secondary leaves reachable. Every leaf must appear in at least one
```
Read:
```
line or it's an orphan.
Lossless + self-contained: every line of the original
```
index.md
```
lands in exactly one destination; leaves repeat shared context inline rather than linking to the hub or each other. If two sections cross-reference too heavily to separate, merge them into one leaf instead of adding a link.
You don't edit
```
SKILL.md
```
's routing tables — the router always emits
```
Read: references/{framework}/index.md
```
regardless of whether the target is index-only or a leaf group; a global Step 4 note tells the agent to follow the hub's dispatch table to a leaf if it has one.

仅索引形式的参考内容可跳过此步骤。当文档行数超过约500行（关键规则中规定了1000行的上限）时，可考虑拆分为叶子组，以便路由仅提取任务所需的部分内容——但仅当内容确实可划分为不同独立章节时才进行拆分；对于内容连贯的长文档，仍保持仅索引形式：

references/framework-<slug>/
├── index.md          # 枢纽文件：共享前置条件 + 意图→叶子文件调度表
├── integrate.md      # 文档章节叶子文件（每个文件对应一个章节，而非一个意图）
├── api-reference.md
├── patterns.md
├── setup.md
└── migration.md      # 仅当SDK存在大版本迁移时添加

叶子文件对应文档章节，而非意图（例如
```
integrate
```
、
```
api-reference
```
、
```
patterns
```
、
```
setup
```
、
```
migration
```
等）。
index.md
变为精简的枢纽文件：包含所有叶子文件都需要的共享安装配置，然后是一个调度表，每行对应一个路由意图，每行都是一个命令式的
```
`Read: references/<slug>/<leaf>.md`
```
，指向该意图对应的主要叶子文件。意图字符串必须与步骤1的内容完全一致（例如
```
feature:mfa
```
，而非
```
mfa
```
）。“Then, if the task requires it”列表中的
```
Read:
```
项目符号可让次要叶子文件具备可达性。每个叶子文件必须至少出现在一行
```
Read:
```
中，否则会成为孤立文件。
无损且自包含：原
```
index.md
```
中的每一行内容都要准确放入一个目标文件中；叶子文件需重复共享上下文内容，而非链接到枢纽文件或其他叶子文件。若两个章节交叉引用过于频繁而无法拆分，应将它们合并为一个叶子文件，而非添加链接。
您无需编辑
```
SKILL.md
```
的路由表——无论目标是仅索引形式还是叶子组，路由始终会输出
```
Read: references/{framework}/index.md
```
；步骤4中的全局说明会告知agent，如果枢纽文件存在调度表，则需遵循该表跳转到对应的叶子文件。

Step 6 — Add a routing eval

步骤6 — 添加路由评估用例

Add a case to

evals/routing-cases.json

(repo root, not inside the skill) so the new intent/framework is asserted. Replace the

remix

placeholder below with your own slug —

expect_refs

must name references that already exist under

references/

(as

<name>/index.md

, or

<name>/<leaf>.md

for a leaf group), or

check_routing_evals.py

rejects the case:

json

{
  "id": "integrate-remix",
  "intent": "integrate",
  "framework": "remix",
  "tooling": "cli",
  "expect_refs": ["framework-remix/index.md", "tooling-cli/index.md"]
}

在

evals/routing-cases.json

（仓库根目录，非skill内部）中添加一个用例，以便对新增的意图/框架进行验证。将下方的

remix

占位符替换为您自己的slug——

expect_refs

必须命名

references/

下已存在的参考内容（例如

<name>/index.md

，或叶子组的

<name>/<leaf>.md

），否则

check_routing_evals.py

会拒绝该用例：

json

{
  "id": "integrate-remix",
  "intent": "integrate",
  "framework": "remix",
  "tooling": "cli",
  "expect_refs": ["framework-remix/index.md", "tooling-cli/index.md"]
}

Step 7 — Validate (the gate)

步骤7 — 验证（准入门槛）

Run all four, in order. The change is not done until every one passes:

bash

bash plugins/auth0/skills/auth0/scripts/validate-skill.sh
python3 scripts/check_router_reachability.py plugins/auth0/skills/auth0
python3 scripts/check_routing_evals.py plugins/auth0/skills/auth0
uvx skillsaw --strict

What each catches:

unreachable reference, orphaned leaf, or a link that breaks the depth-3 tree (sideways/cross-group/second-hop-from-a-sink) →
```
check_router_reachability.py
```

a routing decision that doesn't match

evals/routing-cases.json

→

check_routing_evals.py

weak language or missing frontmatter fields (license, author, openclaw) →
```
skillsaw --strict
```
description length, required sections, expected file presence →
```
validate-skill.sh
```

Also update

plugins/auth0/README.md

when the change adds visible coverage — the linter enforces README documentation.

按顺序运行以下四个命令。只有所有命令都通过，修改才算完成：

bash

bash plugins/auth0/skills/auth0/scripts/validate-skill.sh
python3 scripts/check_router_reachability.py plugins/auth0/skills/auth0
python3 scripts/check_routing_evals.py plugins/auth0/skills/auth0
uvx skillsaw --strict

每个命令的检测范围：

不可达的参考内容、孤立的叶子文件，或违反三级目录结构的链接（横向/跨组/从终端节点发起二次跳转）→
```
check_router_reachability.py
```

与

evals/routing-cases.json

不匹配的路由决策→

check_routing_evals.py

模糊表述或缺失的前置元数据字段（许可证、作者、openclaw）→
```
skillsaw --strict
```
描述长度、必填章节、预期文件是否存在→
```
validate-skill.sh
```

此外，当修改新增了可见的覆盖范围时，请更新

plugins/auth0/README.md

——代码检查器会强制要求README文档同步更新。