skills: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository.

Repository Overview

A collection of portable skills for AI agents: one standalone writing skill and six Laravel engineering skills with 209 rules. The Laravel skills target Laravel ^12.0 || ^13.0 on PHP ^8.3.

This repo contains documentation, not application code. There is no PHP to run — the PHP in rule files is illustrative.

Layout

.claude-plugin/
  marketplace.json      marketplace "foysal50x"
  plugin.json           plugin "laravel-skill" (plugin installs prefix skills with it)
skills.sh.json          skills.sh grouping metadata
scripts/
  lib.mjs               shared parsing helpers
  build-agents.mjs      rules/*.md + _sections.md → AGENTS.md
  validate.mjs          structural validation
  lint-examples.mjs     cross-rule validation of every Correct example
  release.mjs           version bump → commit → tag → GitHub release
skills/{skill-name}/         laravel-async · laravel-eloquent · laravel-patterns · laravel-rest-api · laravel-testing
  SKILL.md              index (max 500 lines)
  AGENTS.md             generated — never edit by hand
  metadata.json
  README.md
  rules/_sections.md    section order, impact, filename prefix
  rules/_template.md
  rules/{prefix}-{slug}.md
  references/*.md       read-on-demand deep dives
  examples/             worked code (laravel-patterns only)

Commands

npm run build      # regenerate every skills/*/AGENTS.md
npm run validate   # structural checks; exits non-zero on error
npm run lint       # cross-rule checks on the code in every Correct example
npm run check      # all three
npm run release    # cut a release from main

Always run npm run check before committing. CI fails if AGENTS.md is stale.

Examples must obey the other rules

validate.mjs checks a rule's structure. lint-examples.mjs checks its content: it walks every fenced block in SKILL.md, rules/ and references/ plus every examples/**/*.php, classifies each block as correct or incorrect by the nearest **Correct / **Incorrect marker, and holds the correct ones to the rest of the rule set — no side effect dispatched inside DB::transaction(), no scope-prefixed methods, no serialize() in a cache key, no query construction inside a Controller, Job, Listener or Command, no driver-specific SQL outside an Expression class, no CRUD-shaped repository methods, one PHP type per example file, and php -l over the worked examples.