---
name: ccref
description: "Bridge from Codex to the user's Claude Code skills + CLAUDE.md. Invoke on `$ccref <topic>`, when the user references a Claude skill as `/foo`, or when a request needs procedural guidance that lives in a Claude skill the user maintains but Codex has not ported. Scans ./.claude and ~/.claude for matching skill docs, reads them as reference, and adapts their Claude-only mechanics to Codex."
---

# ccref

Codex-native bridge to the user's Claude Code skills and instructions.

## Why

The user's primary agent is Claude Code; most of their procedural knowledge lives as Claude skills in `~/.claude/skills` (global) and `<repo>/.claude/skills` (project), plus `CLAUDE.md` instruction files. Codex has only a small ported subset. When a request leans on that knowledge, pull the relevant Claude skill in as REFERENCE and act on it here — don't reinvent it.

## When it fires

- The user types `$ccref`, optionally with a topic: `$ccref seo`, `$ccref css grid`.
- The user references a Claude skill directly as `/foo` (e.g. "do it like /css-wisdom") — treat `/foo` as "read the `foo` Claude skill".
- A request obviously maps to a topic the user has a Claude skill for (styling, testing, PRs, packaging, wisdom docs…) and Codex has no native port.

## What to read

Search both roots, **project first, then global** (project wins on conflict):

- `./.claude/skills/*/SKILL.md`
- `$HOME/.claude/skills/*/SKILL.md`

Plus the standing instructions: `./CLAUDE.md` and `$HOME/.claude/CLAUDE.md`.

## How

1. **Direct `/foo`.** Read `./.claude/skills/foo/SKILL.md`, else `$HOME/.claude/skills/foo/SKILL.md`, in full. Follow its bundled `references/`, `scripts/`, `assets/` as needed.
2. **Topic.** There are 100+ skills — don't read them all. Narrow by keyword, then read the best 1–3 in full:

   ```bash
   # matching skill files by topic keyword. Guard each root and let grep pick the
   # files (--include) — never a bare ./.claude/skills/*/SKILL.md glob: Codex runs
   # in interactive zsh, where that glob is a FATAL "no matches found" when the repo
   # has no project-level ./.claude (the common case), aborting before grep runs.
   for d in ./.claude/skills "$HOME/.claude/skills"; do
     [ -d "$d" ] && grep -rliE 'grid|flex|layout' --include=SKILL.md "$d" 2>/dev/null
   done
   # too broad or empty? index every name + description and pick by eye:
   for d in ./.claude/skills "$HOME/.claude/skills"; do
     [ -d "$d" ] && grep -rHiE '^(name|description):' --include=SKILL.md "$d" 2>/dev/null
   done
   ```

   Always also read the two `CLAUDE.md` files for standing rules that apply regardless of topic.
3. **Apply, don't transcribe.** These docs assume the Claude Code harness — translate as you use them:
   - Claude-only tooling (the `Skill` / `Task` tools, agent teams, `$ARGUMENTS`, `` !`cmd` `` templating, `allowed-tools` / hook frontmatter) has no Codex equivalent. Take the intent; run the shell / `gh` / edit steps directly, and use Codex `spawn_agent` workers where the skill fans out to subagents.
   - If a referenced Claude skill is one Codex already ports (`big-plan`, `x-as-pr`, `x-wt-teams`, `pr-revise`, `cleanup-resources`, `gh-fetch-issue`, `verify-ui`, `watch-ci`, `review-loop`, `codex-*`), prefer the Codex port and use the Claude source only for detail it omits.
   - Bundled `scripts/` are usually plain node/bash and run as-is.

## Output

State which skill(s) / CLAUDE.md you consulted (by name), then do the task using that guidance. If nothing matches the topic, say so plainly and proceed with general knowledge — never invent a skill that isn't there.