feat(tooling): enforce docs freshness and modernize agent skills (#6756)

* feat(docs): fail CI when generated integration docs are stale

* fix(docs): don't flag delete-then-recreated trigger pages in check mode

* docs(skills): require docs:check in the integration authoring skills

* chore(skills): migrate agent commands to native skills

* fix(skills): clean orphaned Claude projections

Author: j15z

.agents/skills/add-block/SKILL.md

@@ -993,11 +993,15 @@ After adding or changing one, run:
 ```bash
 bun run scripts/generate-docs.ts
 bun run integration-catalog:check
+bun run docs:check
 ```
 
 The catalog check independently derives deployment metadata from the executable block registry and
-compares it with the committed `apps/sim/lib/integrations/integrations.json`. Review the generated
-diff and keep only intentional changes.
+compares it with the committed `apps/sim/lib/integrations/integrations.json`. `docs:check` re-renders
+every generated docs artifact in memory and fails on any committed file that differs — it runs in CI
+via `check:audits`, so commit the full generator output. If the generator also trues up pages an
+earlier PR left stale, commit that catch-up too; reverting it as "unrelated drift" makes `docs:check`
+fail.
 ## Checklist Before Finishing
 
 - [ ] `integrationType` is set to the correct `IntegrationType` enum value
@@ -1018,6 +1022,7 @@ diff and keep only intentional changes.
 - [ ] If any tool was added, changed or removed alongside the block: ran `bun run tool-metadata:generate` and committed the artifacts
 - [ ] Ran `bun run scripts/generate-docs.ts`, reviewed the generated diff, and committed the integration catalog changes
 - [ ] `bun run integration-catalog:check` passes
+- [ ] `bun run docs:check` passes (CI gate — fails on any stale generated docs page)
 - [ ] If icon missing: asked user to provide SVG
 - [ ] If triggers exist: `triggers` config set, trigger subBlocks spread
 - [ ] Optional/rarely-used fields set to `mode: 'advanced'`

.agents/skills/add-integration/SKILL.md

@@ -561,6 +561,7 @@ Run the documentation generator:
 ```bash
 bun run scripts/generate-docs.ts
 bun run integration-catalog:check
+bun run docs:check
 ```
 
 This creates `apps/docs/content/docs/en/integrations/{service}.mdx` — one page per service carrying the block's Actions and, if it has one, its Triggers section. Never hand-edit generated pages; the only editable region is the `{/* MANUAL-CONTENT */}` block (see `scripts/README.md`).
@@ -651,6 +652,9 @@ If creating V2 versions (API-aligned outputs):
 - [ ] Verified docs file created
 - [ ] Reviewed and committed the generated `apps/sim/lib/integrations/integrations.json` change
 - [ ] `bun run integration-catalog:check` passes
+- [ ] `bun run docs:check` passes — CI fails on stale generated docs, so commit the full generator
+      output, including catch-up regeneration for pages another PR left stale (never revert it as
+      "unrelated drift")
 
 ### Final Validation (Required)
 - [ ] Read every tool file and cross-referenced inputs/outputs against the API docs

.agents/skills/add-tools/SKILL.md

@@ -475,6 +475,9 @@ All tool IDs MUST use `snake_case`: `{service}_{action}` (e.g., `x_create_tweet`
 - [ ] Index.ts exports all tools and re-exports types (`export * from './types'`)
 - [ ] Tools registered in `tools/registry.ts`
 - [ ] `bun run tool-metadata:generate` run and the regenerated artifacts committed
+- [ ] `bun run scripts/generate-docs.ts` run and the refreshed docs committed — the integration's
+      docs page is rendered from each tool's description, params, and outputs, and CI's
+      `bun run docs:check` fails on stale pages
 - [ ] Block wired: `tools.access`, dropdown options, subBlocks, `tools.config`, outputs, inputs
 - [ ] Model, durable-storage, and internal-execution boundaries use the shared provenance mechanisms
       only where a concrete Sim `{{...}}` resolution path requires them

.agents/skills/add-trigger/SKILL.md

@@ -511,3 +511,6 @@ Add to `helm/sim/values.yaml` under the existing polling cron jobs:
 - [ ] `bun run type-check` passes
 - [ ] Manually verify output keys match trigger `outputs` keys
 - [ ] Trigger UI shows correctly in the block
+- [ ] Ran `bun run scripts/generate-docs.ts` and committed the refreshed pages — trigger sections
+      render into the owning integration's docs page, and CI's `bun run docs:check` fails on stale
+      pages

.agents/skills/validate-integration/SKILL.md

@@ -388,15 +388,25 @@ Several files are generated from tool and block definitions. Editing a tool or b
 bun run tool-metadata:generate       # repo root — apps/sim/tools/generated/*
 bun run scripts/generate-docs.ts     # docs .mdx + lib/integrations/integrations.json + docs icons
 bun run integration-catalog:check    # registry ↔ committed deployment metadata drift
+bun run docs:check                   # committed docs ↔ what the generator renders today
 ```
 
 - **`tool-metadata:generate`** — required whenever a tool's `outputs`, `params`, or descriptions change. CI enforces this with `bun run tool-metadata:check`, which fails with *"Generated tool metadata is stale"*. This is the easiest gate to miss, because nothing in the tool file hints that a generated artifact mirrors it.
 - **`generate-docs`** — required whenever block metadata changes (`bgColor`, `name`, `description`, operations, outputs). Regenerates the integration `.mdx`, `integrations.json`, and the docs copy of `components/icons.tsx`.
 - **`integration-catalog:check`** — loads the executable block registry, derives visible integration
   deployment fields, and compares them with the committed catalog. It catches missing/unexpected
   entries and stale auth/service IDs without loading the executable registry in client code.
-
-**Always diff the regen output before committing.** These generators rewrite every file they own, so they will also sweep in unrelated drift that accumulated on the base branch — pages losing sections, unrelated icons appearing. Keep only the hunks belonging to the integration under validation and `git checkout --` the rest, otherwise an unrelated doc regression rides along in the PR. Verify no page was silently dropped by comparing the directory listing before and after.
+- **`docs:check`** — check mode of `generate-docs.ts`: renders every generated docs artifact in
+  memory and fails listing any committed file that differs. Runs in CI via `check:audits`.
+
+**Always diff the regen output before committing — but commit all of it.** These generators rewrite
+every file they own, so they also true up drift that accumulated on the base branch (pages whose
+source changed without a regen). That catch-up is correct output, not a regression: `docs:check`
+fails CI on any page left stale, so reverting swept-in hunks with `git checkout --` reintroduces the
+failure. Review the diff to confirm each hunk is explained by a real source change (yours or an
+upstream PR that skipped regeneration), and investigate anything that looks like content loss — a
+page losing a section usually means its source block moved or a generator input broke, not that the
+hunk should be reverted.
 
 If an icon changed, `apps/sim/components/icons.tsx` is the source of truth and `apps/docs/components/icons.tsx` is its generated mirror — they must end up byte-identical for that component.
 
@@ -408,9 +418,10 @@ After fixing, confirm:
 3. The integration's tests pass, and any test you added actually fails without its fix (revert it once and watch it go red)
 4. Derived artifacts regenerated and their diffs reviewed (see above)
 5. `bun run integration-catalog:check` passes
-6. For OAuth or service-account changes, `bun test apps/sim/lib/integrations/availability.server.test.ts` passes
-7. Re-read all modified files to verify fixes are correct
-8. Any remaining unknown response schemas were explicitly reported to the user instead of guessed
+6. `bun run docs:check` passes
+7. For OAuth or service-account changes, `bun test apps/sim/lib/integrations/availability.server.test.ts` passes
+8. Re-read all modified files to verify fixes are correct
+9. Any remaining unknown response schemas were explicitly reported to the user instead of guessed
 
 ## Checklist Summary
 
@@ -439,7 +450,7 @@ After fixing, confirm:
 - [ ] Reported all issues grouped by severity
 - [ ] Fixed all critical and warning issues
 - [ ] Ran `bun run tool-metadata:generate` if any tool outputs/params changed, and confirmed `bun run tool-metadata:check` passes
-- [ ] Ran `bun run generate-docs` if any block metadata changed, and reverted unrelated drift the generator swept in
+- [ ] Ran `bun run generate-docs` if any block metadata changed, and committed the full generated diff — including stale-page catch-up for other integrations (`bun run docs:check` fails CI on reverted generator output)
 - [ ] Ran `bun run lint` after fixes
 - [ ] Verified TypeScript compiles clean
 - [ ] Verified added tests fail without their fix