author-auth0-skill

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

Then follow the matching path below.

Path A — New framework reference

1. 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.
2. 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).
3. If the framework has a web-app vs API split, add a row to Variant disambiguation.
4. 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.
5. The integrate load block in Step 4 already reads references/framework-{framework}/index.md — no Step 4 edit needed.

Path B — New feature reference

1. 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).

2. 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** |

3. 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:

{
  "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 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.