Skip to content

Restructure saleor-paper-storefront skill v4.1#1176

Open
mariobrgomes wants to merge 2 commits intomainfrom
skill/expand-saleor-storefront-rules
Open

Restructure saleor-paper-storefront skill v4.1#1176
mariobrgomes wants to merge 2 commits intomainfrom
skill/expand-saleor-storefront-rules

Conversation

@mariobrgomes
Copy link
Copy Markdown

Summary

  • AGENTS.md made self-contained (334 lines) — works for any AI agent (Codex, Copilot, Cursor, Claude). Added architecture decisions, key file paths, anti-patterns, task routing table, code style, and testing guidance. Nothing removed from v1.
  • SKILL.md slimmed to 75-line skill-system wrapper (YAML frontmatter + rule index + pointer to AGENTS.md). Zero duplication.
  • Rules expanded from 11 to 16: added data-error-handling, data-auth-patterns, checkout-cart, webhook-handlers, dev-testing, dev-new-page. Merged checkout-components into checkout-management.
  • References restructured: deleted 5 narrow files that duplicated rule content, added saleor-domain-model.md (ER diagram, entity relationships) and saleor-glossary.md (13 non-obvious gotcha terms).
  • Deleted 2,468-line monolith (skills/.../AGENTS.md) — agents now load AGENTS.md (334 lines) + targeted rules instead.

Design decisions

  • AGENTS.md is the single source of truth — any agent reading only this file is productive
  • SKILL.md exists only for Claude's skill triggering system (agentskills.io frontmatter)
  • Rules are modular (~120-490 lines each) so agents load only what they need
  • References provide domain context (entity relationships, terminology) that rules cross-reference

Test plan

  • Verify AGENTS.md renders correctly on GitHub
  • Verify all rule file cross-references resolve (grep for broken links)
  • Confirm SKILL.md → AGENTS.md relative link works
  • Test skill triggering in Claude Code with prompts like "debug my checkout" or "add a webhook handler"

🤖 Generated with Claude Code

Major restructuring of the skill for open-standard compatibility:

AGENTS.md (334 lines) — self-contained for any AI agent:
- Added: architecture decisions, key file paths, anti-patterns, task routing
  table ("I Want To..."), code style, testing sections, dev commands
- Kept: env vars, common gotchas, caching strategy, project structure
- Updated: tech stack, rule reference (11 → 16 rules)
- Works for Codex, Copilot, Cursor, Claude — no tool-specific features

SKILL.md (75 lines) — thin skill-system wrapper:
- YAML frontmatter for Claude skill triggering
- Rule index + pointer to AGENTS.md
- Zero duplication with AGENTS.md

Rules expanded from 11 to 16:
- New: data-error-handling, data-auth-patterns, checkout-cart,
  webhook-handlers, dev-testing, dev-new-page
- Removed: checkout-components (merged into checkout-management)
- dev-investigation expanded with diagnostic queries

References restructured:
- Deleted 5 narrow files (duplicated rule content)
- Added: saleor-domain-model (ER diagram, entity relationships)
- Added: saleor-glossary (13 non-obvious gotcha terms)

Deleted 2,468-line monolith (skills/.../AGENTS.md).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@mariobrgomes mariobrgomes requested a review from a team as a code owner February 25, 2026 18:40
@vercel
Copy link
Copy Markdown
Contributor

vercel bot commented Feb 25, 2026

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

Project Deployment Actions Updated (UTC)
storefront Ready Ready Preview, Comment Feb 25, 2026 7:26pm

Request Review

- Generated skill AGENTS.md (4,931 lines) — compiled all 16 rules + 5
  references into one file for agents without skill support
- Restored variant-state-machine.md, variant-utils-reference.md, and
  saleor-key-directories.md reference files from main
- Restored and updated README.md reflecting v4.1 structure (16 rules,
  5 references)
- Updated SKILL.md and root AGENTS.md to reference all 5 reference files

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant