improve AGENTS.md and skill to create-adapter

Author: HugoRCD

.agents/skills/create-adapter/SKILL.md

@@ -1,11 +1,21 @@
 ---
 name: create-evlog-adapter
-description: Create a new built-in evlog adapter to send wide events to an external observability platform. Use when adding a new drain adapter (e.g., for Datadog, Sentry, Loki, Elasticsearch, etc.) to the evlog package. Covers source code, build config, package exports, tests, and documentation.
+description: Create a new built-in evlog adapter to send wide events to an external observability platform. Use when adding a new drain adapter (e.g., for Datadog, Sentry, Loki, Elasticsearch, etc.) to the evlog package. Covers source code, build config, package exports, tests, and all documentation.
 ---
 
 # Create evlog Adapter
 
-Add a new built-in adapter to evlog. Every adapter follows the same architecture. This skill walks through all 5 touchpoints.
+Add a new built-in adapter to evlog. Every adapter follows the same architecture. This skill walks through all 8 touchpoints. **Every single touchpoint is mandatory** -- do not skip any.
+
+## PR Title
+
+Recommended format for the pull request title:
+
+```
+feat: add {name} adapter
+```
+
+The exact wording may vary depending on the adapter (e.g., `feat: add OTLP adapter`, `feat: add Axiom drain adapter`), but it should always follow the `feat:` conventional commit prefix.
 
 ## Touchpoints Checklist
 
@@ -15,9 +25,12 @@ Add a new built-in adapter to evlog. Every adapter follows the same architecture
 | 2 | `packages/evlog/build.config.ts` | Add build entry |
 | 3 | `packages/evlog/package.json` | Add `exports` + `typesVersions` entries |
 | 4 | `packages/evlog/test/adapters/{name}.test.ts` | Create tests |
-| 5 | `apps/docs/content/3.adapters/{n}.{name}.md` | Create doc page (before `custom.md`) |
+| 5 | `apps/docs/content/3.adapters/{n}.{name}.md` | Create adapter doc page (before `custom.md`) |
+| 6 | `apps/docs/content/3.adapters/1.overview.md` | Add adapter to overview (links, card, env vars) |
+| 7 | `AGENTS.md` | Add adapter to the "Built-in Adapters" table |
+| 8 | Renumber `custom.md` | Ensure `custom.md` stays last after the new adapter |
 
-After all 5 steps, update `AGENTS.md` to list the new adapter in the adapters table.
+**Important**: Do NOT consider the task complete until all 8 touchpoints have been addressed.
 
 ## Naming Conventions
 
@@ -96,7 +109,7 @@ Required test categories:
 5. Batch operations (`sendBatchTo{Name}`)
 6. Timeout handling (default 5000ms + custom)
 
-## Step 5: Documentation
+## Step 5: Adapter Documentation Page
 
 Create `apps/docs/content/3.adapters/{n}.{name}.md` where `{n}` is the next number before `custom.md` (custom should always be last).
 
@@ -133,17 +146,81 @@ Sections to include:
 5. **Configuration Priority** -- overrides > runtimeConfig > env vars
 6. **Advanced** -- custom options, event transformation details
 7. **Querying/Using** -- how to find evlog events in the target service
+8. **Troubleshooting** -- common errors (missing config, auth failures)
+9. **Direct API Usage** -- `sendTo{Name}()` and `sendBatchTo{Name}()` examples
+10. **Next Steps** -- links to other adapters and best practices
+
+Use the existing Axiom adapter page (`apps/docs/content/3.adapters/2.axiom.md`) as a reference for tone, structure, and depth.
+
+## Step 6: Update Adapters Overview Page
+
+Edit `apps/docs/content/3.adapters/1.overview.md` to add the new adapter in **three** places:
+
+### 6a. Frontmatter `links` array
+
+Add a link entry alongside the existing adapters:
+
+```yaml
+- label: "{Name}"
+  icon: i-simple-icons-{name}
+  to: /adapters/{name}
+  color: neutral
+  variant: subtle
+```
+
+### 6b. `::card-group` section
+
+Add a card block for the new adapter (before the Custom card):
 
-Renumber `custom.md` if needed so it stays last.
+```markdown
+  :::card
+  ---
+  icon: i-simple-icons-{name}
+  title: {Name}
+  to: /adapters/{name}
+  ---
+  [Short description of what the adapter does.]
+  :::
+```
+
+### 6c. Zero-Config Setup `.env` example
+
+Add the adapter's env vars in the `.env` code block. The variable names depend on the service (e.g., `NUXT_AXIOM_TOKEN`, `NUXT_OTLP_ENDPOINT`, `NUXT_POSTHOG_API_KEY`):
 
-## Final Step: Update AGENTS.md
+```bash
+# {Name}
+NUXT_{NAME}_<RELEVANT_VAR>=xxx
+```
 
-Add the new adapter to the adapters table in the root `AGENTS.md` file, in the "Log Draining & Adapters" section:
+## Step 7: Update AGENTS.md
+
+Add the new adapter to the **"Built-in Adapters"** table in the root `AGENTS.md` file, in the "Log Draining & Adapters" section:
 
 ```markdown
 | {Name} | `evlog/{name}` | Send logs to {Name} for [description] |
 ```
 
+Also add a usage example block (following the pattern of existing adapters in AGENTS.md):
+
+```markdown
+**Using {Name} Adapter:**
+
+\`\`\`typescript
+// server/plugins/evlog-drain.ts
+import { create{Name}Drain } from 'evlog/{name}'
+
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('evlog:drain', create{Name}Drain())
+})
+\`\`\`
+
+Set the required environment variables (e.g., \`NUXT_{NAME}_TOKEN\`, \`NUXT_{NAME}_ENDPOINT\`, etc. -- depends on the service).
+```
+
+## Step 8: Renumber `custom.md`
+
+If the new adapter's number conflicts with `custom.md`, renumber `custom.md` to be the last entry. For example, if the new adapter is `5.{name}.md`, rename `5.custom.md` to `6.custom.md`.
+
 ## Verification
 
 After completing all steps, run:

AGENTS.md

@@ -211,6 +211,8 @@ export default defineNitroPlugin((nitroApp) => {
 
 evlog provides built-in adapters for popular observability platforms. Use the `evlog:drain` hook to send logs to external services.
 
+> **Creating a new adapter?** Follow the skill at `.agents/skills/create-adapter/SKILL.md`. It covers all touchpoints: source code, build config, package exports, tests, and all documentation updates.
+
 **Built-in Adapters:**
 
 | Adapter | Import | Description |