Skip to content

Commit 8e64d4a

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 1494564 commit 8e64d4a

2 files changed

Lines changed: 152 additions & 0 deletions

File tree

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

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

‎AGENTS.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,10 @@ Key top-level docs:
4242
new reference file must be reachable from `SKILL.md` and must not link to
4343
another reference file (the one-hop rule, enforced by
4444
`scripts/check_router_reachability.py`).
45+
3. For the step-by-step authoring procedure (which router tables to edit, in
46+
what order, and how to validate), use the `author-auth0-skill` skill in
47+
Claude Code. It walks through adding a framework, feature, tooling, or
48+
pattern reference so the change passes CI the first time.
4549

4650
## Required SKILL.md frontmatter
4751

0 commit comments

Comments
 (0)