feat(skills): canonicalize skills to a single source with generated .claude/.cursor projections by TheodoreSpeaks · Pull Request #5609 · simstudioai/sim

TheodoreSpeaks · 2026-07-12T00:20:08Z

Summary

Establishes a single source of truth for the repo's agent skills and eliminates the three-copy drift that had accumulated across .agents/skills, .claude/commands, and .cursor/commands.

Single source: every skill now lives once at .agents/skills/<name>/SKILL.md (frontmatter name + description + optional argument-hint, then body). .claude/commands/<name>.md and .cursor/commands/<name>.md are generated from it by scripts/sync-skills.ts — never hand-edited.
Drift made impossible: bun run skills:sync regenerates; bun run skills:check fails on any stale projection and is wired into CI (test-build.yml); a pre-commit hook auto-regenerates when a SKILL.md is staged. CONTRIBUTING.md documents "edit canonical only."
Reconciliation: the three drifted copies of each skill were reconciled to the latest content (26 canonical skills touched). Where a newer copy had dropped a section, it was merged back — and referenced code (e.g. listingCapped, registry-maps.ts) was verified still live before restoring guidance. Stale-and-wrong instructions were corrected (e.g. the old "don't add tags to BlockConfig" rule, now the opposite in current code).
/cleanup overhaul (the original seed of this PR): rewritten from sequential to parallel read-only analysis → converge → sequential pass-ordered apply, avoiding concurrent-write clobbering while keeping the analysis speedup. Adds a new comment-reduction pass (you-might-not-need-a-comment) and wires you-might-not-need-url-state into the set (8 passes total).
Structural fixes that fell out of generating from canonical: the abbreviated .claude/commands/ship.md is now the full ship; Cursor gained the 8 skills it was missing; babysit's /ship references now point at the canonical source.

Type of Change

Improvement / refactor (tooling + docs; no runtime app code)

Testing

bun run skills:check passes; all three trees hold the same 31 skills with no orphans
Verified .agents/skills is tracked (not gitignored) so the CI gate runs on a fresh checkout
Generator is idempotent (re-running skills:sync is a no-op); biome-clean
Per-skill reconciliation decisions (which copy won / what was merged) are documented in the commit history

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)

…ially

vercel · 2026-07-12T00:20:14Z

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jul 13, 2026 10:47pm

cursor · 2026-07-12T00:20:18Z

PR Summary

Low Risk
Documentation-only changes to agent skills and commands; no production code paths or deploy behavior are modified.

Overview
This PR is almost entirely agent skill and slash-command documentation under .agents/skills/ and mirrored .claude/commands/ — no application runtime code.

/cleanup is rewritten to run eight quality passes in parallel with fix=false, then converge overlapping proposals and apply fixes sequentially (effects → state → memo → callback → React Query → url-state → emcn → comments), including content-anchored edits when parallel analysis goes stale. Two new passes join the set: you-might-not-need-url-state and you-might-not-need-a-comment.

New skills/commands document operational workflows: add-block-preview (AppConfig/PREVIEW_BLOCKS gating), add-feature-flag (AppConfig vs env flags), babysit (Greptile/Cursor review loop), and db-migrate (zero-downtime migrations and -- migration-safe).

Integration builder docs are aligned across add/validate skills: no guessed API/webhook/tool outputs; blocks register in registry-maps.ts (BLOCK_REGISTRY / BLOCK_META_REGISTRY); BlockMeta requires ≥7 templates plus grounded skills; block outputs clarified as flat/json-only (no nested tool-style properties); icons use currentColor + check:bare-icons; BYOK registration points at lib/api/contracts/byok-keys.ts; internal tool routes use lib/api/contracts/tools/{service}.ts.

Connector/trigger docs add syncContext.listingCapped for truncated listings, @/connectors/utils helpers, expanded polling trigger registration, and stricter validate-connector checks for deletion reconciliation.

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

greptile-apps · 2026-07-12T00:21:28Z

Greptile Summary

This PR updates the cleanup skill and skill command projection flow. The main changes are:

Runs cleanup analysis passes in parallel before applying fixes in order.
Parses cleanup scope and fix arguments before spawning read-only passes.
Adds and updates canonical skill files plus Claude and Cursor command projections.
Adds a skills:check CI step for projection drift.

Confidence Score: 5/5

This looks safe to merge.

No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
.agents/skills/cleanup/SKILL.md	Defines the parallel analysis and sequential apply workflow for the cleanup skill.
.claude/commands/cleanup.md	Updates the Claude cleanup command with parsed scope substitution and read-only analysis passes.
.cursor/commands/cleanup.md	Updates the Cursor cleanup command with the same cleanup orchestration flow.
scripts/sync-skills.ts	Adds projection generation and checking from canonical skill sources.
.github/workflows/test-build.yml	Adds the skill projection check to the build workflow.

_{Reviews (11): Last reviewed commit: "Merge remote-tracking branch 'origin/sta..." | Re-trigger Greptile}

…ing skills into .claude/commands

…ead of literal <scope>

TheodoreSpeaks · 2026-07-12T01:51:10Z

@greptile

TheodoreSpeaks · 2026-07-12T01:51:11Z

@cursor review

…rough convergence for ordered apply

TheodoreSpeaks · 2026-07-12T01:57:55Z

@greptile

TheodoreSpeaks · 2026-07-12T01:57:56Z

@cursor review

…e when a prior pass invalidated the snippet

TheodoreSpeaks · 2026-07-12T02:03:39Z

@greptile

TheodoreSpeaks · 2026-07-12T02:03:40Z

@cursor review

…three copies

TheodoreSpeaks · 2026-07-12T02:09:43Z

@greptile

TheodoreSpeaks · 2026-07-12T02:09:44Z

@cursor review

…mbiguate babysit /ship refs in claude copy

TheodoreSpeaks · 2026-07-12T02:25:16Z

@greptile

TheodoreSpeaks · 2026-07-12T02:25:17Z

@cursor review

TheodoreSpeaks · 2026-07-12T02:33:30Z

@cursor review

… .claude/.cursor projections Establish .agents/skills/<name>/SKILL.md as the single source of truth (latest content reconciled per skill from the three drifted copies), and generate the .claude/commands and .cursor/commands projections from it via scripts/sync-skills.ts. Adds skills:sync/skills:check, a CI gate, a pre-commit regen hook, and CONTRIBUTING docs. Structurally fixes prior drift (e.g. abbreviated .claude ship -> full ship).

…ck has no per-file target Removes stray </content>/</invoke> markup that leaked into add-block, add-connector, add-hosted-key canonical skills, and reword the cleanup skill's lint step to note bun run lint:check runs repo-wide via turbo (no per-path API). Projections regenerated via skills:sync. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QjefwescJoHZ6zcc3C17FR

TheodoreSpeaks · 2026-07-13T22:28:23Z

@greptile

TheodoreSpeaks · 2026-07-13T22:28:25Z

@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 dfb6c34. Configure here.}

Re-add the "if any tool outputs are still unknown, tell the user instead of guessing block outputs" step that was dropped when Final Validation step 5 became the BlockMeta template check. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QjefwescJoHZ6zcc3C17FR

TheodoreSpeaks · 2026-07-13T22:37:45Z

@greptile

TheodoreSpeaks · 2026-07-13T22:37:49Z

@cursor review

…nup-skill # Conflicts: # .claude/commands/cleanup.md # .claude/commands/ship.md

TheodoreSpeaks · 2026-07-13T22:41:50Z

@greptile

TheodoreSpeaks · 2026-07-13T22:41:51Z

@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 183a605. Configure here.}

TheodoreSpeaks · 2026-07-13T22:50:39Z

@greptile

TheodoreSpeaks · 2026-07-13T22:50:41Z

@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 183a605. Configure here.}

improvement(cleanup-skill): parallelize analysis, apply fixes sequent…

f3d764d

…ially

greptile-apps Bot reviewed Jul 12, 2026

View reviewed changes

Comment thread .claude/commands/cleanup.md

vercel Bot deployed to Preview July 12, 2026 00:24 View deployment

TheodoreSpeaks added 2 commits July 11, 2026 18:49

improvement(cleanup-skill): add comment-reduction pass; mirror 6 miss…

964f746

…ing skills into .claude/commands

fix(cleanup-skill): substitute parsed scope into analysis passes inst…

8dc169a

…ead of literal <scope>

cursor Bot reviewed Jul 12, 2026

View reviewed changes

Comment thread .claude/commands/cleanup.md

Comment thread .claude/commands/cleanup.md Outdated

vercel Bot deployed to Preview July 12, 2026 01:55 View deployment

fix(cleanup-skill): parse fix token anywhere; preserve pass labels th…

390a902

…rough convergence for ordered apply

cursor Bot reviewed Jul 12, 2026

View reviewed changes

Comment thread .claude/commands/cleanup.md Outdated

vercel Bot deployed to Preview July 12, 2026 02:02 View deployment

fix(cleanup-skill): apply Step 1 proposals content-anchored, re-deriv…

85a26fe

…e when a prior pass invalidated the snippet

cursor Bot reviewed Jul 12, 2026

View reviewed changes

Comment thread .claude/commands/babysit.md Outdated

vercel Bot deployed to Preview July 12, 2026 02:07 View deployment

fix(babysit-skill): correct garbled --reverse explanation across all …

b111671

…three copies

cursor Bot reviewed Jul 12, 2026

View reviewed changes

Comment thread .claude/commands/babysit.md

Comment thread .claude/commands/cleanup.md

vercel Bot deployed to Preview July 12, 2026 02:14 View deployment

fix(skills): propagate parallel cleanup to cursor/agents copies; disa…

d1b1040

…mbiguate babysit /ship refs in claude copy

cursor Bot reviewed Jul 12, 2026

View reviewed changes

Comment thread .agents/skills/cleanup/SKILL.md Outdated

vercel Bot deployed to Preview July 12, 2026 02:37 View deployment

TheodoreSpeaks requested a review from a team as a code owner July 13, 2026 18:55