feat(tooling): enforce docs freshness and modernize agent skills by j15z · Pull Request #6756 · simstudioai/sim

j15z · 2026-08-16T00:22:42Z

Summary

Add a read-only docs:check mode that detects stale generated integration docs and run it through the existing check:audits CI gate.
Preserve final-output comparison for trigger-owned pages and regenerate the five pages already stale on staging.
Keep .agents/skills/<name>/SKILL.md as the canonical skill source, expose complete skill directories to Claude through generated .claude/skills/<name> symlinks, and let Cursor discover .agents/skills directly.
Remove all 36 deprecated .claude/commands projections, all 36 deprecated .cursor/commands projections, and the stale duplicate Cursor add-hosted-key skill.
Update skill syncing, pre-commit behavior, contributor guidance, and integration-authoring skills for the new layout; rename skills:check to check:skills so the existing CI audit runner discovers it automatically and continues rejecting stale Claude links or reintroduced command projections.

This prevents generated docs and agent-specific skill copies from silently drifting away from their canonical sources.

Type of Change

Testing

bun run agent-stream-docs:generate
bun run skills:sync
bun run lint
bun run apps/sim/scripts/check-block-registry.ts origin/staging
bun run check:audits (28 audits, including docs:check and check:skills)
bun run check:skills
git diff --check

Checklist

Code follows project style guidelines
Self-reviewed my changes
Tests added/updated and passing
No new warnings introduced
I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

Screenshots/Videos

Not applicable; this PR only changes developer tooling, generated documentation, and agent configuration.

vercel · 2026-08-16T00:22:48Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 16, 2026 1:56am

cursor · 2026-08-16T00:22:56Z

PR Summary

Low Risk
Changes are contributor docs, agent command removals, and CI-adjacent skill checklists; no runtime product code in the shown diff.

Overview
Integration authoring skills now treat generated integration docs as a CI gate: run bun run docs:check after generate-docs and integration-catalog:check, and add checklist items so stale .mdx fails in check:audits.

Regeneration policy flipped in validate-integration and related skills: contributors must commit the full generator diff, including catch-up pages from earlier PRs that skipped regen — reverting swept-in hunks as "unrelated drift" is documented as breaking docs:check.

Agent skill layout cleanup: large deprecated .claude/commands/* projections (e.g. add-block, add-integration, add-tools) are deleted from the diff; canonical guidance stays under .agents/skills/*/SKILL.md (the PR description also covers skills:sync, check:skills, and symlinked .claude/skills — not all of that appears in this diff hunk set).

^{Reviewed by Cursor Bugbot for commit 3ce4b6c. Bugbot is set up for automated code reviews on this repo. Configure here.}

greptile-apps · 2026-08-16T00:25:35Z

Greptile Summary

The PR adds read-only generated-documentation freshness enforcement and migrates agent integrations from copied command projections to canonical skill directories.

Adds docs:check and includes generated-documentation verification in the audit suite.
Replaces Claude command copies with generated skill-directory symlinks while allowing Cursor to consume canonical skills directly.
Removes deprecated projections, refreshes stale integration documentation, and updates contributor and skill guidance.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains within the eligible follow-up review scope.

No blocking failure remains.

Important Files Changed

Filename	Overview
scripts/generate-docs.ts	Adds an in-memory overlay and final-output comparison so CI can detect stale generated documentation without mutating the checkout.
scripts/sync-skills.ts	Replaces copied command projections with Claude directory symlinks and introduces validation and cleanup for generated skill surfaces.
scripts/run-audits.ts	Adds documentation freshness checking while renamed `check:skills` remains covered through automatic `check:*` discovery.
package.json	Exposes the new documentation and skill checks through repository scripts.
.husky/pre-commit	Updates canonical-skill synchronization to stage generated Claude skill links.
.github/CONTRIBUTING.md	Documents the canonical skill directory and the current Claude and Cursor discovery model.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Canonical[".agents/skills/name/"] --> Cursor["Cursor direct discovery"]
  Canonical --> Sync["scripts/sync-skills.ts"]
  Sync --> Claude[".claude/skills/name symlink"]
  Sources["Blocks, tools, and triggers"] --> Generator["scripts/generate-docs.ts"]
  Generator --> Docs["Generated integration docs"]
  Audits["check:audits"] --> SkillCheck["check:skills"]
  Audits --> DocsCheck["docs:check"]
  SkillCheck --> Claude
  DocsCheck --> Docs

_{Reviews (5): Last reviewed commit: "fix(skills): clean orphaned Claude proje..." | Re-trigger Greptile}

j15z · 2026-08-16T00:54:12Z

@greptile

j15z · 2026-08-16T00:54:13Z

@cursor review

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 36e2316. Configure here.}

j15z · 2026-08-16T01:03:45Z

@greptile

j15z · 2026-08-16T01:03:46Z

@cursor review

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit ccedbb2. Configure here.}

j15z · 2026-08-16T01:42:58Z

@greptile

j15z · 2026-08-16T01:43:01Z

@cursor review

j15z · 2026-08-16T01:50:08Z

@greptile

j15z · 2026-08-16T01:50:11Z

@cursor review

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 3ce4b6c. Configure here.}

j15z requested a review from a team as a code owner August 16, 2026 00:22

cursor Bot reviewed Aug 16, 2026

View reviewed changes

Comment thread scripts/generate-docs.ts

vercel Bot deployed to Preview August 16, 2026 00:28 View deployment

cursor Bot reviewed Aug 16, 2026

View reviewed changes

vercel Bot deployed to Preview August 16, 2026 01:00 View deployment

cursor Bot reviewed Aug 16, 2026

View reviewed changes

vercel Bot deployed to Preview August 16, 2026 01:09 View deployment

j15z added 4 commits August 15, 2026 18:40

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

c986794

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

a6b0600

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

3eeccf5

chore(skills): migrate agent commands to native skills

8491532

j15z force-pushed the feat/docs-drift-check branch from ccedbb2 to 8491532 Compare August 16, 2026 01:42

j15z changed the title ~~feat(docs): fail CI when generated integration docs are stale~~ feat(tooling): enforce docs freshness and modernize agent skills Aug 16, 2026

cursor Bot reviewed Aug 16, 2026

View reviewed changes

Comment thread scripts/sync-skills.ts

vercel Bot deployed to Preview August 16, 2026 01:48 View deployment

fix(skills): clean orphaned Claude projections

3ce4b6c

cursor Bot reviewed Aug 16, 2026

View reviewed changes

vercel Bot deployed to Preview August 16, 2026 01:56 View deployment

waleedlatif1 approved these changes Aug 16, 2026

View reviewed changes

waleedlatif1 merged commit 7f936dc into staging Aug 16, 2026
31 checks passed

waleedlatif1 deleted the feat/docs-drift-check branch August 16, 2026 02:08

waleedlatif1 mentioned this pull request Aug 16, 2026

v0.8.3: sim cli, new tools, credential groups, splunk, finder-like files refactor, security hardening #6765

Open

Uh oh!

Conversation

j15z commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Type of Change

Testing

Checklist

Screenshots/Videos

Uh oh!

vercel Bot commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

greptile-apps Bot commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Flowchart

Uh oh!

Uh oh!

j15z commented Aug 16, 2026

Uh oh!

j15z commented Aug 16, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

j15z commented Aug 16, 2026

Uh oh!

j15z commented Aug 16, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

j15z commented Aug 16, 2026

Uh oh!

j15z commented Aug 16, 2026

Uh oh!

Uh oh!

j15z commented Aug 16, 2026

Uh oh!

j15z commented Aug 16, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

j15z commented Aug 16, 2026 •

edited

Loading

vercel Bot commented Aug 16, 2026 •

edited

Loading

cursor Bot commented Aug 16, 2026 •

edited

Loading

greptile-apps Bot commented Aug 16, 2026 •

edited

Loading