Skip to content

Commit 8efa1a0

Browse files
frederikprijckfrederikprijck
committed
feat: add author-auth0-skill contributor skill
Consolidates the design spec, implementation plan, and review-fix iterations into a single skill: a router SKILL.md that guides contributors through authoring or editing an Auth0 skill (frontmatter, directory structure, naming, and validation).
1 parent ce81350 commit 8efa1a0

2 files changed

Lines changed: 155 additions & 3 deletions

File tree

‎.claude/skills/author-auth0-skill/SKILL.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
name: author-auth0-skill
3+
description: >
4+
Use when adding or editing Auth0 guidance in this repo's single auth0 skill —
5+
a new framework, feature, tooling, or pattern reference — to get the file
6+
structure, router wiring, and validation right the first time. Use even if the
7+
request just says "add a reference" or "document X in the skill" without naming
8+
the router.
9+
license: Apache-2.0
10+
metadata:
11+
author: Auth0 <support@auth0.com>
12+
---
13+
14+
# Authoring an Auth0 skill reference
15+
16+
Add or edit guidance in the single `auth0` skill
17+
(`plugins/auth0/skills/auth0/`). This walks you through structure + router
18+
wiring so the change passes CI on the first try.
19+
20+
Source of truth (read, don't duplicate): [`CONTRIBUTING.md`](../../../CONTRIBUTING.md)
21+
and [`docs/architecture.md`](../../../docs/architecture.md).
22+
23+
## Critical rules (get these wrong and CI fails)
24+
25+
- **One-hop rule + reachability:** every `references/` file MUST be named in a
26+
`SKILL.md` router table, and MUST NOT link to any other `.md` file. Both are
27+
stated in full under
28+
[`CONTRIBUTING.md` → "Make it routable"](../../../CONTRIBUTING.md#make-it-routable-required--ci-enforces-this);
29+
the paths below tell you which table to edit.
30+
- **Strict mode:** avoid vague quality adverbs that assert an outcome without
31+
showing it — state the concrete behavior instead (what happens, to what,
32+
when); give a positive alternative for every prohibition; hoist MUST/NEVER
33+
directives near the top of the file.
34+
35+
## Step 0 — Classify the contribution
36+
37+
| What you're adding | Prefix | Router edits |
38+
|---|---|---|
39+
| A single SDK/framework integration | `framework-<name>.md` | Step 2 all 3 tiers (+ variant row if web/API split) |
40+
| A capability spanning frameworks | `feature-<name>.md` | Step 1 intent row + Step 4 load block |
41+
| A provisioning tool | `tooling-<name>.md` | Step 3 tooling table |
42+
| Cross-cutting guidance | `pattern-<name>.md` | Step 4 load block(s) referencing it |
43+
| Editing an existing reference | (n/a) | Usually none — re-check the one-hop rule |
44+
45+
Then follow the matching path below.
46+
47+
## Path A — New framework reference
48+
49+
1. Create `plugins/auth0/skills/auth0/references/framework-<slug>.md`
50+
(kebab-case). Follow the split used by peers: `## Setup`, `## Integration`,
51+
`## API` sections; self-contained (no `.md` links).
52+
2. Wire detection into **all three tiers** of Step 2 in
53+
`plugins/auth0/skills/auth0/SKILL.md`:
54+
- Tier 1 — the Auth0 SDK package row (e.g. `@auth0/auth0-remix` → `remix`).
55+
Put it above less-specific rows.
56+
- Tier 2 — the non-Auth0 workspace dependency row (e.g. `@remix-run/react`
57+
in `package.json` → `remix`).
58+
- Tier 3 — the prompt-keyword row (e.g. "Remix" → `remix`).
59+
3. If the framework has a web-app vs API split, add a row to
60+
**Variant disambiguation**.
61+
4. No separate list to update: the reachability checker derives routable slugs
62+
from the backticked value column of these tables, so naming `<slug>` in a
63+
table makes `framework-<slug>.md` reachable.
64+
5. The `integrate` load block in Step 4 already reads
65+
`references/framework-{framework}.md` — no Step 4 edit needed.
66+
67+
## Path B — New feature reference
68+
69+
1. Create `plugins/auth0/skills/auth0/references/feature-<slug>.md`
70+
(self-contained).
71+
2. Add an **intent row** to the Step 1 table. The `Intent` value is a lookup
72+
key reused verbatim as a Step 4 heading. Describe the goal in plain language,
73+
not just the Auth0 term. Example row:
74+
`| Let users sign in without a password ... *Auth0: passwordless.* | **feature:passwordless** |`
75+
3. Add a matching **load block** in Step 4 whose heading is that intent. The
76+
heading is Markdown (`### feature:passwordless`); the `Read:` lines sit inside
77+
a fenced block beneath it, matching the existing Step 4 blocks:
78+
79+
~~~
80+
### feature:passwordless
81+
```
82+
Read: references/feature-passwordless.md
83+
Read: references/tooling-{tooling}.md
84+
If framework detected: Read references/framework-{framework}.md
85+
```
86+
~~~
87+
88+
## Path C — New tooling or pattern reference
89+
90+
- **Tooling:** create
91+
`plugins/auth0/skills/auth0/references/tooling-<slug>.md`, then add a row to
92+
the Step 3 table. Backtick the value exactly as the existing rows do
93+
(`` | <project signal> | `tooling-<slug>.md` | ``) — reachability picks up
94+
tooling files only via their backticked bare filename, so an unbackticked
95+
value leaves the file unreachable. Note `validate-skill.sh` hardcodes
96+
`cli mcp terraform` — a genuinely new tooling file also needs that list
97+
extended.
98+
- **Pattern:** create
99+
`plugins/auth0/skills/auth0/references/pattern-<slug>.md`, then reference it
100+
from the relevant Step 4 load block(s) (patterns are pulled in conditionally,
101+
e.g. `pattern-multi-tenant.md` under `guidance`). `validate-skill.sh`
102+
hardcodes `security token-handling multi-tenant rate-limiting common-errors` —
103+
extend that list for a new pattern file.
104+
105+
## Path D — Editing an existing reference
106+
107+
Usually no router edit. Before finishing: confirm you introduced no link to
108+
another `.md` file (one-hop rule), and that any new prohibition has a positive
109+
alternative and any weak language is reworded.
110+
111+
## Step 5 — Add a routing eval
112+
113+
Add a case to `plugins/auth0/skills/auth0/tests/routing-cases.json` so the new
114+
intent/framework is asserted. Replace the `remix` placeholder below with your
115+
own slug — `expect_refs` must name files that already exist under
116+
`references/`, or `check_routing_evals.py` rejects the case:
117+
118+
```json
119+
{
120+
"id": "integrate-remix",
121+
"intent": "integrate",
122+
"framework": "remix",
123+
"tooling": "cli",
124+
"expect_refs": ["framework-remix.md", "tooling-cli.md"]
125+
}
126+
```
127+
128+
## Step 6 — Validate (the gate)
129+
130+
Run all three, in order. The change is not done until every one passes:
131+
132+
```bash
133+
bash plugins/auth0/skills/auth0/scripts/validate-skill.sh
134+
python3 scripts/check_router_reachability.py plugins/auth0/skills/auth0
135+
uvx skillsaw --strict
136+
```
137+
138+
What each catches:
139+
- unreachable file or a second-hop `.md` link → `check_router_reachability.py`
140+
- weak language or missing frontmatter fields (license, author, openclaw) → `skillsaw --strict`
141+
- description length, required sections, expected file presence → `validate-skill.sh`
142+
143+
Also update `plugins/auth0/README.md` when the change adds visible coverage —
144+
the linter enforces README documentation.

‎AGENTS.md‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,17 @@ Key top-level docs:
3232

3333
1. Read [`CONTRIBUTING.md`](./CONTRIBUTING.md). The conventions there are
3434
enforced and not optional.
35-
2. Match the patterns of neighboring skills rather than inventing new structure.
36-
The reference-file convention (`setup.md` / `integration.md` / `api.md`) and
37-
the shared section layout exist on purpose — keep them consistent.
35+
2. Match the patterns of the existing reference files rather than inventing new
36+
structure. The flat naming convention (`framework-<name>.md`,
37+
`feature-<name>.md`, `tooling-<name>.md`, `pattern-<name>.md`) and the
38+
router-in-`SKILL.md` layout exist on purpose — keep them consistent. Every
39+
new reference file must be reachable from `SKILL.md` and must not link to
40+
another reference file (the one-hop rule, enforced by
41+
`scripts/check_router_reachability.py`).
42+
3. For the step-by-step authoring procedure (which router tables to edit, in
43+
what order, and how to validate), use the `author-auth0-skill` skill in
44+
Claude Code. It walks through adding a framework, feature, tooling, or
45+
pattern reference so the change passes CI the first time.
3846

3947
## Required SKILL.md frontmatter
4048

0 commit comments

Comments
 (0)