Skip to content

README.codex.md

Latest commit

 

History

History
85 lines (54 loc) · 2.54 KB

README.codex.md

File metadata and controls

85 lines (54 loc) · 2.54 KB
Raw

Superpowers DL for Codex

Guide for using the deep learning research fork of Superpowers with OpenAI Codex in a single project.

Quick Install

Tell Codex:

From this project root, fetch and follow instructions from https://raw.githubusercontent.com/ShunyangLiu/superpowers_DL/refs/heads/main/.codex/INSTALL.md, and add the recommended project-level rule to this project's AGENTS.md.

Manual Installation

Prerequisites

  • OpenAI Codex CLI
  • Git

Steps

  1. Clone the repo into the current project:

    mkdir -p .agents
git clone https://github.com/ShunyangLiu/superpowers_DL.git .agents/superpowers

  2. Create the project skills symlink:

    mkdir -p .agents/skills
ln -s ../superpowers/skills .agents/skills/superpowers

  3. Add this project-level rule to AGENTS.md:

    When deep learning research work involves experiment design, execution, training debugging, result analysis, or reproducibility checks, prefer the project Superpowers DL skills from `.agents/skills/superpowers`.

  4. Restart Codex from this project.

How It Works

Codex scans repo-scoped .agents/skills/ at startup. Superpowers exposes its skills through one project symlink:

<project>/.agents/skills/superpowers/ -> <project>/.agents/superpowers/skills/

The using-superpowers skill handles skill-first behavior for research work in this fork, and the project AGENTS.md rule makes that preference explicit for this repo only.

Hooks

This Codex install path uses repo-scoped skills and a project AGENTS.md rule. It does not require the Claude Code plugin hooks in hooks/, so moving the Codex install from global to project-scoped does not disable those hooks. They are only relevant when this repository is packaged and loaded as a Claude Code/Cursor-style plugin.

Usage

Typical prompts that should trigger a skill:

  • "I want to try rotary embeddings in this model"
  • "Training goes to NaN after warmup"
  • "Compare these ablations and tell me what to run next"
  • "Can you help me reproduce this paper fairly?"

You can also mention a skill directly, for example:

  • use experiment-design
  • use training-debugging

Updating

cd .agents/superpowers && git pull

Troubleshooting

Skills not showing up

  1. Verify the symlink from the project root: ls -la .agents/skills/superpowers
  2. Check skills exist: find .agents/superpowers/skills -name SKILL.md
  3. Check this project's AGENTS.md contains the project-level Superpowers DL rule
  4. Restart Codex from this project