Authoring an Auth0 skill reference

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

Critical rules (get these wrong and CI fails)

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.

Step 0 — Classify the contribution

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.

Path A — New framework reference

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.

Path B — New feature reference

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
```

Path C — New tooling or pattern reference

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.

Path D — Editing an existing reference

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.

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

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.

Step 6 — Add a routing eval

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"]
}

Step 7 — Validate (the gate)

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.

author-auth0-skill

NPX Install

Tags

SKILL.md Content