chore: scaffold ai-coding-skills repository structure

README.md

@@ -0,0 +1,53 @@
+# ai-coding-skills
+
+Cross-agent skill collection for **Codex**, **Claude Code**, and **OpenCode**.
+
+This repo is organized similarly to `obra/superpowers` and is designed to scale to many skills over time.
+
+## Goals
+
+- Keep skills portable across coding agents.
+- Keep each skill self-contained (`skills/<skill-name>/SKILL.md` + optional resources).
+- Enforce requirement checks for skills that depend on Superpower skills.
+
+## Repository Layout
+
+```text
+ai-coding-skills/
+├── README.md
+├── docs/
+│   ├── repository-structure.md
+│   └── requirements-gate.md
+├── skills/
+│   └── _template/
+│       └── SKILL.md
+├── .codex/
+├── .claude-plugin/
+├── .opencode/
+│   └── plugins/
+├── commands/
+├── hooks/
+└── tests/
+```
+
+## Skills
+
+| Skill | Purpose | Status |
+|---|---|---|
+| _TBD_ | Waiting for your custom skill content | Planned |
+
+## Requirement Gate (Superpowers dependency)
+
+If a skill depends on Superpower skills (`https://github.com/obra/superpowers`), it must include an explicit prerequisite block in `SKILL.md` and fail fast with clear instructions when requirements are missing.
+
+See: `docs/requirements-gate.md`
+
+## Compatibility Policy
+
+Each skill added to this repo should specify support status for:
+
+- Codex
+- Claude Code
+- OpenCode
+
+Use the template at `skills/_template/SKILL.md`.

docs/repository-structure.md

@@ -0,0 +1,31 @@
+# Repository Structure
+
+This repository follows a superpowers-style organization for long-term maintainability.
+
+## Top-level directories
+
+- `skills/` → All installable skills.
+- `docs/` → Repository-level guidance.
+- `.codex/` → Codex-specific integration/config notes.
+- `.claude-plugin/` → Claude Code plugin metadata/integration notes.
+- `.opencode/plugins/` → OpenCode plugin metadata/integration notes.
+- `commands/` → Optional command wrappers.
+- `hooks/` → Optional pre/post hooks.
+- `tests/` → Regression tests for triggering/behavior.
+
+## Skill Folder Contract
+
+Each skill folder should contain at minimum:
+
+- `SKILL.md` (required)
+
+Optional:
+
+- `scripts/` (deterministic execution)
+- `references/` (detailed docs)
+- `assets/` (templates/resources)
+
+## Naming
+
+- lowercase + hyphen only
+- one skill per folder

docs/requirements-gate.md

@@ -0,0 +1,40 @@
+# Requirements Gate
+
+For any skill that depends on external skill sets (e.g., Superpowers), enforce these rules:
+
+## Mandatory Prerequisite Section in SKILL.md
+
+Include a `Prerequisites` section that states:
+
+- required dependency repo
+- required skill names
+- what happens if requirements are missing
+- exact remediation steps
+
+## Runtime/Flow Behavior
+
+If requirements are missing:
+
+1. Stop execution.
+2. Return a concise blocking message.
+3. Provide exact install/setup steps.
+4. Ask for confirmation once requirements are installed.
+
+## Suggested Block Message
+
+```text
+Cannot run <skill-name> yet.
+Missing required Superpower skills: <list>
+Install from: https://github.com/obra/superpowers
+After installation, tell me "requirements ready" and I’ll continue.
+```
+
+## Compatibility Requirement
+
+Each skill must declare support for:
+
+- Codex
+- Claude Code
+- OpenCode
+
+If one platform is unsupported, state it explicitly.

skills/_template/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: your-skill-name
+description: Briefly describe what this skill does and when to use it.
+---
+
+# your-skill-name
+
+## Compatibility
+
+- Codex: ✅
+- Claude Code: ✅
+- OpenCode: ✅
+
+## Prerequisites
+
+This skill depends on Superpower skills.
+
+- Dependency repo: https://github.com/obra/superpowers
+- Required skills: <fill-required-skill-list>
+
+If prerequisites are missing, **stop** and show:
+
+```text
+Cannot run your-skill-name yet.
+Missing required Superpower skills: <list>
+Install from: https://github.com/obra/superpowers
+After installation, tell me "requirements ready" and I’ll continue.
+```
+
+## Workflow
+
+(Replace with actual workflow.)
+
+## Notes
+
+(Replace with skill-specific constraints.)