refactor: consolidate agent rules into sanity-best-practices skill

[joneidejohnsen]

Summary

• Migrates all 21 .mdc agent rules from rules/ into the sanity-best-practices skill as the single source of truth
• Renames rules/ → references/ per the agentskills.io specification
• Adds compiled AGENTS.md inside the skill (Vercel pattern) with all 26 atomic rules
• Rewrites SKILL.md with a comprehensive Quick Reference index
• Updates root AGENTS.md Knowledge Router to point to new locations
• Deletes all old rules/sanity-*.mdc files (clean break, no stubs)

What changed

Before	After
rules/sanity-nextjs.mdc	skills/sanity-best-practices/references/nextjs.md
rules/sanity-schema.mdc	skills/sanity-best-practices/references/schema.md
skills/.../rules/groq-*.md	skills/.../references/groq-*.md
Cursor-specific .mdc frontmatter	Standard .md frontmatter with title/tags
Two parallel rule systems	Single source of truth in skill

MCP impact

• The MCP server's list_sanity_rules/get_sanity_rules reads from the skill's references directory — will need to be updated to read from references/ instead of rules/
• "Get started with Sanity" flow continues to work (loaded via MCP, not hardcoded path)

Test plan

• All 4 skills pass npm run validate
• Zero .mdc files remaining
• Zero stale rules/sanity- references in any .md or .json file
• 48 files in references/ (21 guides + 26 atomic rules + _sections.md)
• Verify MCP list_sanity_rules still works after server-side update

🤖 Generated with Claude Code

[runeb]

Review from Claude Code

---

Review: consolidate agent rules into sanity-best-practices skill

Summary

The amended PR addresses the concerns from the initial review. This is a clean consolidation — good to go.

What it does

Merges the 26 atomic rule files and 21 guide/integration files into 22 unified reference files under skills/sanity-best-practices/references/. Deletes the top-level rules/ directory, the rules/ and references/ split inside the skill, the compiled AGENTS.md inside the skill, and _sections.md. Strips globs/tags from frontmatter. Updates the root AGENTS.md Knowledge Router and README to point to the new paths.

What's good

• Single canonical location for all content — no more duplication across rules/*.mdc, skills/.../rules/, and a compiled AGENTS.md
• Spec-aligned with agentskills.io (references/ is the standard directory; rules/ was not in the spec)
• Clean frontmatter — just title and description, no dead metadata
• README documents the MCP relationship — makes it clear that references/ is the canonical source for list_sanity_rules / get_sanity_rules
• SKILL.md is focused — clean Quick Reference index at 75 lines
• Validation passes

Delivery channels all accounted for

• MCP tools (list_sanity_rules / get_sanity_rules): server-side update in progress to read from references/
• MCP prompts: SKILL.md still works, now with a cleaner index
• Cursor plugin: discovers the skill via skills/
• Claude Code plugin: discovers the skill via skills/
• npx skills add: installs skill per agentskills.io spec
• Root AGENTS.md: Knowledge Router updated to point to references/ paths
• Manual install: copy skills/sanity-best-practices/ to your project

[joneidejohnsen]

Review from Claude Code

Review: consolidate agent rules into sanity-best-practices skill

The good

The consolidation direction is right — one canonical location instead of parallel directories. The rules/ -> references/ rename aligns with the agentskills.io spec. The .mdc -> .md conversion drops Cursor-specific coupling. SKILL.md is well-structured with a good Quick Reference index. Validation passes.

Main concern: this content has ~8 distribution channels

This repo serves the same content through many paths: MCP tools (list_sanity_rules/get_sanity_rules), MCP resources, MCP prompts, Claude Code plugin, Cursor plugin (with globs-based auto-attachment), npx skills add, the root AGENTS.md, and manual copy to .cursor/rules/. Several of these have hard dependencies on rules/*.mdc existing — the MCP tools, MCP resources, and Cursor plugin all break when that directory is deleted.

The PR acknowledges the MCP impact as a follow-up checkbox, but given how many channels are affected, it would be worth documenting which channels need updating and coordinating those changes. A section in the README mapping "canonical content lives in skills/.../references/, here's how each channel accesses it" would also help prevent future breakage.

Other observations

• AGENTS.md inside the skill: Not part of the agentskills.io spec (spec only recognizes SKILL.md + references/ + scripts/ + assets/). At 48KB of fully inlined content, it also runs counter to Vercel's eval findings that a compressed ~8KB index outperforms full docs. The SKILL.md Quick Reference is already that index — it just needs to be more accessible.
• Content duplication: Every atomic rule is duplicated verbatim in AGENTS.md with no build step to keep them in sync.
• globs in frontmatter: Currently consumed by Cursor plugin for auto-attachment. After this move to references/*.md, it's unclear whether Cursor still discovers these. Worth clarifying.
• MCP skill prompts: SKILL.md now references references/ files that aren't reachable via MCP. Agents connected only through MCP can't follow those pointers.
• _sections.md: Duplicates what's in SKILL.md's Quick Reference.

Fixed in #24

[runeb]

Looks good — concerns from the initial review have been addressed.