chore: add Axis Codex skills tooling

[phuongnse]

Summary

This PR adds repo-scoped Codex skills for the recurring Axis workflows and trims the root agent docs so detailed procedures live in focused skills. It also adds a repo-native check codex-skills policy guard, policy tests, and local-dev dependency documentation so skill metadata stays enforceable instead of becoming prose-only guidance.

Linked spec

N/A - repo-scoped Codex skills and agent tooling; no product use-case spec.

Requirements & rules followed

• Spec -> code - N/A - repo tooling/docs only; no use-case ACs.
• Ready review - changed paths are skills, docs, and repo policy tooling; no behavior AC map triggered.
• Path coverage matrix - N/A - no runtime implementation surface.
• Verification gate - N/A - local full verify timed out after 5m on .NET format/build; targeted triggered checks passed and CI should run the full gate.
• Docs review - AGENTS.md, agent checklist, design gate, scripts docs, local-dev docs, and REVIEW_FINDINGS.md updated.
• Retrospective review - REVIEW_FINDINGS.md records Codex skill metadata drift as an enforced class.
• Workarounds - this PR does not introduce or resolve a P0/P1 workaround.
• No new TODO / FIXME / NotImplementedException / placeholder / stub under src/, tests/, frontend/src/.

Summary by CodeRabbit

• Documentation

  • Added eight new agent skills defining workflows for API contracts, cross-module integration, design gate reviews, frontend features, readiness reviews, review feedback, use-case implementation, and visual artifacts.
  • Updated development workflow guidance to reference the new agent skills and streamlined playbook instructions.

• Tests

  • Added validation suite for agent skill metadata and Python package detection.

• Chores

  • Enhanced verification tooling to enforce agent skill documentation standards.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 6f710b6d-3d06-4370-81a3-a9374b291955

📥 Commits

Reviewing files that changed from the base of the PR and between 5508be7 and e8567e3.

📒 Files selected for processing (24)

• .agents/skills/axis-api-contract/SKILL.md
• .agents/skills/axis-api-contract/agents/openai.yaml
• .agents/skills/axis-cross-module-contract/SKILL.md
• .agents/skills/axis-cross-module-contract/agents/openai.yaml
• .agents/skills/axis-design-gate/SKILL.md
• .agents/skills/axis-design-gate/agents/openai.yaml
• .agents/skills/axis-frontend-feature/SKILL.md
• .agents/skills/axis-frontend-feature/agents/openai.yaml
• .agents/skills/axis-ready-review/SKILL.md
• .agents/skills/axis-ready-review/agents/openai.yaml
• .agents/skills/axis-review-feedback/SKILL.md
• .agents/skills/axis-review-feedback/agents/openai.yaml
• .agents/skills/axis-use-case-implementation/SKILL.md
• .agents/skills/axis-use-case-implementation/agents/openai.yaml
• .agents/skills/axis-visual-artifact/SKILL.md
• .agents/skills/axis-visual-artifact/agents/openai.yaml
• AGENTS.md
• docs/REVIEW_FINDINGS.md
• docs/playbooks/agent-checklist.md
• docs/playbooks/design-gate.md
• docs/playbooks/local-dev.md
• docs/playbooks/scripts.md
• scripts/axis.py
• scripts/tests/test_policy_gates.py

---

📝 Walkthrough

Walkthrough

Eight agent skill documents are added under .agents/skills/, each with a SKILL.md workflow definition and an openai.yaml interface block. scripts/axis.py gains a check_codex_skills validation suite that enforces skill structure, frontmatter, chaining references, and UI metadata. Tests cover all rejection and acceptance paths. Playbooks and AGENTS.md are updated to reference the new skills and CI gate.

Changes

Codex Agent Skills Infrastructure

Layer / File(s)	Summary
Codex skills validation engine and tests scripts/axis.py, scripts/tests/test_policy_gates.py	Adds rel_from, codex_skill_issues, check_codex_skills, and _python_module_version to scripts/axis.py. Registers check codex-skills as a CLI subcommand and extends doctor with a PyYAML probe. TestCodexSkillsGate and TestDoctorPythonPackageChecks cover all acceptance and rejection paths.
Eight agent skill definitions .agents/skills/axis-design-gate/*, .agents/skills/axis-api-contract/*, .agents/skills/axis-cross-module-contract/*, .agents/skills/axis-frontend-feature/*, .agents/skills/axis-ready-review/*, .agents/skills/axis-review-feedback/*, .agents/skills/axis-use-case-implementation/*, .agents/skills/axis-visual-artifact/*	Adds a SKILL.md procedural guide and a four-line agents/openai.yaml interface block for each of the eight new agent skills.
AGENTS.md, playbooks, and enforcement ledger AGENTS.md, docs/playbooks/agent-checklist.md, docs/playbooks/design-gate.md, docs/playbooks/scripts.md, docs/playbooks/local-dev.md, docs/REVIEW_FINDINGS.md	Updates AGENTS.md design-gate and dev-rules sections to reference skill macros. Rewrites agent-checklist.md workflow/verification guidance. Tightens design-gate.md headings. Adds check codex-skills to scripts.md command list and rules. Adds PyYAML prerequisite to local-dev.md. Records the new gate as Enforced in REVIEW_FINDINGS.md.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• phuongnse/axis#159: Both PRs modify docs/playbooks/agent-checklist.md to adjust agent readiness and gate checklist guidance.
• phuongnse/axis#180: Both PRs add check subcommands and gate tests to the same scripts/axis.py and scripts/tests/test_policy_gates.py files.
• phuongnse/axis#189: Both PRs extend the axis doctor command in scripts/axis.py; this PR adds PyYAML probing on top of the doctor flow introduced in #189.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/axis-codex-skills

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}