nextjs-skills: Instructions file for Codex

Agent Instructions

Rules for contributing to this repository. The same rules apply to every AI assistant editing the repo — Claude, Kiro, Cursor, and any others. CLAUDE.md simply points here.

Repository layout

skills/
├── nextjs-cache-architecture/
│   ├── SKILL.md            # Always-loaded core.
│   ├── overlay.yaml        # Optional routing manifest. Update when triggering signals change.
│   ├── references/         # Deep-dive markdown the agent loads on demand.
│   ├── assets/             # Drop-in source files copied verbatim into user repos.
│   ├── scripts/            # Executable verifiers / generators with no external deps.
│   └── evals/              # Test cases for the skill.
├── next-action-handler/
│   ├── SKILL.md
│   └── references/         # Optional, depends on the skill
└── [otherSkill]/            # Follows the same structure where applicable
src/                         # Shared runtime code used by skills

Top-level docs (README.md, AGENTS.md, CLAUDE.md) describe the repo and its contribution rules — not the skill's content.

Style guidelines

• No emojis in any markdown file or code comment.
• Use Yes/No in tables instead of checkmarks.
• Use // Good: and // Bad: comments in code examples — never // WRONG, // CORRECT, or other variants.
• Keep examples focused on one concept at a time.
• Placeholders use [PascalCase] for types and components, [camelCase] for functions, variables, and tag strings.
• Every code snippet should compile if pasted into a real project — include the imports it depends on.
• Bad examples come after the good pattern they contrast with, never alone. The reader should always see the right answer first.

SKILL.md authoring rules

SKILL.md must:

• Open with a YAML frontmatter block that parses cleanly.
  • Required keys: name, description. Optional: metadata (with version, author).
  • Anything else is silently ignored by harnesses — typos become invisible bugs.
  • description should explicitly list trigger phrases. Agents tend to under-trigger skills, so be slightly assertive about when to use it.
  • Bump metadata.version when the skill structure or rules change.
• Stay under ~500 lines. If you approach the limit, push detail down a layer — into references/, assets/, or scripts/ — with clear pointers to the new location.
• Explain the why before any code. Lean on theory of mind instead of blanket MUST / NEVER. Today's models are smart enough to act on reasoning, and reasoning generalizes; rigid rules don't.