From 0d9a4cbef182e85a8f9192e0dcc41b05b451d490 Mon Sep 17 00:00:00 2001 From: Luke Date: Mon, 9 Feb 2026 03:31:03 +0000 Subject: [PATCH] chore: scaffold ai-coding-skills repository structure --- .claude-plugin/.gitkeep | 0 .codex/.gitkeep | 0 .opencode/plugins/.gitkeep | 0 README.md | 53 ++++++++++++++++++++++++++++++++++++ commands/.gitkeep | 0 docs/repository-structure.md | 31 +++++++++++++++++++++ docs/requirements-gate.md | 40 +++++++++++++++++++++++++++ hooks/.gitkeep | 0 skills/_template/SKILL.md | 36 ++++++++++++++++++++++++ tests/.gitkeep | 0 10 files changed, 160 insertions(+) create mode 100644 .claude-plugin/.gitkeep create mode 100644 .codex/.gitkeep create mode 100644 .opencode/plugins/.gitkeep create mode 100644 README.md create mode 100644 commands/.gitkeep create mode 100644 docs/repository-structure.md create mode 100644 docs/requirements-gate.md create mode 100644 hooks/.gitkeep create mode 100644 skills/_template/SKILL.md create mode 100644 tests/.gitkeep diff --git a/.claude-plugin/.gitkeep b/.claude-plugin/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.codex/.gitkeep b/.codex/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.opencode/plugins/.gitkeep b/.opencode/plugins/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/README.md b/README.md new file mode 100644 index 0000000..1d2ce44 --- /dev/null +++ b/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.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`. diff --git a/commands/.gitkeep b/commands/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/repository-structure.md b/docs/repository-structure.md new file mode 100644 index 0000000..2bd0c81 --- /dev/null +++ b/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 diff --git a/docs/requirements-gate.md b/docs/requirements-gate.md new file mode 100644 index 0000000..1dd420d --- /dev/null +++ b/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 yet. +Missing required Superpower skills: +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. diff --git a/hooks/.gitkeep b/hooks/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/_template/SKILL.md b/skills/_template/SKILL.md new file mode 100644 index 0000000..4075486 --- /dev/null +++ b/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: + +If prerequisites are missing, **stop** and show: + +```text +Cannot run your-skill-name yet. +Missing required Superpower skills: +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.) diff --git a/tests/.gitkeep b/tests/.gitkeep new file mode 100644 index 0000000..e69de29