Skip to content

Commit af4ba50

Browse files
wcyganwcygan
committed
skills
1 parent 7bc5d1a commit af4ba50

14 files changed

Lines changed: 742 additions & 0 deletions

File tree

‎config/claude/skills/teach/SKILL.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
description: Socratic teaching loop for any Claude Code session — quiz yourself on what actually happened, confirm mastery item by item, and don't finish until everything's locked in
3+
---
4+
5+
> **Credit:** Original "Learn Quiz" prompt by **Suzanne** (Anthropic), shared by [@trq212](https://x.com/trq212/status/2061545633560010826). Wrapped here with session sourcing, checklist tracking, and incremental mastery confirmation.
6+
7+
# /teach
8+
9+
You are a wise and incredibly effective teacher. Your goal is to make sure the human deeply understands the session — not just what happened, but why, what decisions were made, and what the broader implications are.
10+
11+
Work incrementally. Confirm mastery of each concept before moving on. Update the checklist file after every confirmed item.
12+
13+
## Usage
14+
15+
```
16+
/teach <topic keywords> → search sessions by topic, solo mode
17+
/teach <path/to/file> → direct file, solo mode
18+
/teach <topic> --student <name> → teaching mode (help you teach someone else)
19+
```
20+
21+
**No argument:** List 10 most recent sessions and ask which one to teach.
22+
23+
## Step 1: Source Resolution
24+
25+
### Topic mode (no file path given)
26+
1. Search session JSONL files for the topic using grep across `~/.claude/projects/`
27+
2. Rank by recency (most recently modified first)
28+
3. Extract the key narrative:
29+
- Pull assistant messages that describe findings, decisions, conclusions
30+
- Pull user messages that give direction or confirm outcomes
31+
- Skip tool call noise and internal scaffolding
32+
4. If multiple strong matches: show top 3 with one-line summaries, ask to confirm
33+
5. Synthesize a readable session narrative (500–1000 words) as the teaching source
34+
35+
### File path mode
36+
Read the file directly. Supports: JSONL (session transcript), `.md` (meeting notes, processed session export).
37+
38+
## Step 2: Setup
39+
40+
1. Derive a slug from the topic or filename
41+
2. Get current date: `TZ="America/New_York" date +"%Y-%m-%d"` (adjust for your timezone)
42+
3. Create the checklist file at a location that makes sense for your project:
43+
`sessions/teaching/YYYY-MM-DD-<slug>.md`
44+
4. Populate it (see Checklist Structure below)
45+
5. Commit and push: `git add <file> && git commit -m "data(teaching): add <slug> teaching checklist" && git push`
46+
6. Post the file path, then begin the teaching loop
47+
48+
## Checklist Structure
49+
50+
Extract specific, concrete items from the session — not generic placeholders.
51+
52+
```markdown
53+
---
54+
mode: solo | teaching
55+
student: <name, if teaching mode>
56+
source: <topic or file path>
57+
started: <ISO date>
58+
---
59+
60+
# Teaching: <session title>
61+
62+
## Progress: 0/<total> concepts confirmed
63+
64+
### The Problem
65+
- [ ] <specific item>
66+
- [ ] <why the problem existed>
67+
- [ ] <alternatives or branches considered>
68+
69+
### The Solution
70+
- [ ] <how it was resolved>
71+
- [ ] <why this approach over others>
72+
- [ ] <key design decisions>
73+
- [ ] <edge cases handled>
74+
75+
### Broader Context
76+
- [ ] <what this change impacts>
77+
- [ ] <why it matters in the larger picture>
78+
- [ ] <what to watch for going forward>
79+
80+
---
81+
*Last updated: <timestamp>*
82+
```
83+
84+
## Solo Mode Loop (default)
85+
86+
**Before each exchange**, re-read the checklist file to know current state.
87+
88+
**Opening move:** Ask the user to restate their understanding of the session in their own words. Calibrate from there — fill gaps, don't re-cover what they already have.
89+
90+
**Loop:**
91+
1. Pick the next unconfirmed item
92+
2. Ask a targeted question — open-ended or multiple choice
93+
3. For multiple choice: vary the correct answer position; don't reveal until after they respond
94+
4. If correct: mark `[x]` in the file immediately, note progress inline (`5/11 confirmed`), move on
95+
5. If missed: explain, then re-ask in a different form before marking confirmed
96+
6. Every 3–4 exchanges: show the current checklist progress
97+
98+
**Drill into WHY.** Surface the motivation behind decisions, not just what was done. Ask follow-up whys before moving to the next item.
99+
100+
**Completion gate:** Only surface "session complete" when all items are `[x]`. Final output: the completed checklist. Offer to save a summary note.
101+
102+
## Teaching Mode Loop (`--student <name>`)
103+
104+
Instead of quizzing the user, help them structure a walk-through for someone else:
105+
106+
1. Same checklist, framed as a teaching guide
107+
2. For each section, suggest how to explain it and what questions to ask the student
108+
3. Progress tracks what the user has explicitly covered + confirmed the student understood
109+
110+
## Rules
111+
112+
- **One question at a time.** No multi-part questions.
113+
- **Update the checklist file after every confirmed item** — don't batch.
114+
- **Never offer to wrap up** until the checklist is 100% complete.
115+
- **Keep responses concise** — aim for under 2000 chars per exchange.
116+
- **Responses can be eli5, eli14, or intern-level** if asked.
117+
- **Source synthesis is internal** — don't narrate the grep/extract process. Just start teaching.

‎config/codex/skills/openai-codex-python-sdk/SKILL.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
name: openai-codex-python-sdk
3+
description: Use when building, reviewing, debugging, or documenting Python applications that use the OpenAI Codex Python SDK, especially the openai-codex package, openai_codex imports, Codex or AsyncCodex clients, threads, turns, streaming, login flows, sandbox access, SDK examples, or the openai-codex-cli-bin runtime package. Use this skill for Codex Python SDK questions even when the user only says "Codex SDK" in a Python context.
4+
---
5+
6+
# OpenAI Codex Python SDK
7+
8+
Use this skill for Python work against the public beta OpenAI Codex SDK. Keep exact API claims source-backed because the SDK is beta and may change before 1.0.
9+
10+
## Workflow
11+
12+
1. Identify the task surface: install/auth/runtime, threads and turns, streaming or turn controls, async parity, multimodal or structured input, examples, or troubleshooting.
13+
2. Read the smallest relevant reference file from the map below.
14+
3. Verify current details before precise API, install, or version claims:
15+
- Prefer a local `openai/codex` checkout when the user is working inside one.
16+
- Otherwise fetch the official GitHub sources listed in `references/doc-map.md`.
17+
4. Inspect the target application code before editing. Match its Python package manager, async style, logging style, and test pattern.
18+
5. Use public SDK exports from `openai_codex` and `openai_codex.types`. Avoid private modules unless the task is explicitly about SDK internals.
19+
6. Choose the client deliberately: `Codex` for sync programs and `AsyncCodex` with `async with` for async programs.
20+
7. Choose the turn primitive deliberately: `thread.run(...)` for common cases and `thread.turn(...)` when streaming, steering, interrupting, or custom event handling is needed.
21+
8. Set `sandbox=` intentionally on thread starts and sensitive turns. Do not assume filesystem access from examples.
22+
9. Keep secrets out of code, docs, tests, shell history, and committed config. Prefer existing Codex auth or user-managed environment variables for API keys.
23+
24+
## Reference Map
25+
26+
- `references/doc-map.md`: official source links, strict `sdk/python` file list, and verification rules.
27+
- `references/install-auth-runtime.md`: package install, Python requirement, login flows, and runtime package behavior.
28+
- `references/threads-turns-sandbox.md`: clients, thread lifecycle, turns, streaming, result fields, kwargs, and sandbox presets.
29+
- `references/examples-patterns.md`: official example folders and when to copy each pattern.
30+
- `references/troubleshooting.md`: beta caveats, migration notes, constructor failures, hanging turns, retries, and runtime mismatch checks.
31+
32+
## Quality Rules
33+
34+
- Treat the SDK as beta. Re-check the source before encoding exact signatures or long-lived guidance.
35+
- Prefer the official checked-in examples over invented minimal snippets when implementing real workflows.
36+
- Distinguish conversation state from execution: a `Thread` holds state; a turn is one model execution inside that thread.
37+
- Prefer `run()` unless the application genuinely needs event-by-event behavior.
38+
- Use `stream()` only when the app will keep consuming notifications until the matching turn completes.
39+
- Do not retry all failures. Retry only transient overload failures with the SDK-supported retry helper or an equivalent bounded policy.
40+
- Keep public keyword arguments in Python `snake_case`; the SDK maps wire-level names internally.
41+
42+
## Fast Commands
43+
44+
```sh
45+
python -m pip install openai-codex
46+
python -m pydoc openai_codex
47+
python -m pydoc openai_codex.Codex
48+
```

‎config/codex/skills/openai-codex-python-sdk/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "OpenAI Codex Python SDK"
3+
short_description: "Build with the openai-codex Python SDK"
4+
default_prompt: "Use $openai-codex-python-sdk to build or debug this Python Codex SDK workflow."

‎config/codex/skills/openai-codex-python-sdk/references/doc-map.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
canonical_url: https://github.com/openai/codex/tree/main/sdk/python
3+
last_verified: 2026-06-05
4+
---
5+
6+
# Codex Python SDK Documentation Map
7+
8+
Use the official OpenAI `openai/codex` repository as the source of truth for the Python SDK.
9+
10+
## Strict SDK Sources
11+
12+
These files were present under `sdk/python` when checked on 2026-06-05:
13+
14+
- README: https://github.com/openai/codex/blob/main/sdk/python/README.md
15+
- Getting started: https://github.com/openai/codex/blob/main/sdk/python/docs/getting-started.md
16+
- API reference: https://github.com/openai/codex/blob/main/sdk/python/docs/api-reference.md
17+
- FAQ: https://github.com/openai/codex/blob/main/sdk/python/docs/faq.md
18+
- Examples index: https://github.com/openai/codex/blob/main/sdk/python/examples/README.md
19+
20+
## Adjacent Runtime Source
21+
22+
- Python runtime package: https://github.com/openai/codex/blob/main/sdk/python-runtime/README.md
23+
24+
Treat `sdk/python-runtime` as adjacent packaging context. It explains the runtime dependency used by the Python SDK, but it is not part of the strict `sdk/python` docs tree.
25+
26+
## Reading Order
27+
28+
1. Start with the README for the package purpose, install command, quickstart, auth entry points, and built-in help.
29+
2. Read Getting Started for a runnable multi-turn flow, sandbox presets, thread continuation, and async usage.
30+
3. Read the API reference before naming exact classes, methods, keyword arguments, result fields, or imported types.
31+
4. Read the FAQ for stability, runtime-package, retry, migration, and common failure behavior.
32+
5. Read the Examples index before writing sample code or selecting a pattern for a real app.
33+
34+
## Verification Rules
35+
36+
- If the user needs exact current behavior, fetch the linked source before answering.
37+
- If a local `openai/codex` checkout is available, inspect its `sdk/python` files instead of relying on this map.
38+
- If GitHub docs and installed package behavior conflict, verify the installed `openai_codex.__version__`, package metadata, and the runtime package version before changing application code.

‎config/codex/skills/openai-codex-python-sdk/references/examples-patterns.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
canonical_url: https://github.com/openai/codex/blob/main/sdk/python/examples/README.md
3+
last_verified: 2026-06-05
4+
---
5+
6+
# Examples and Patterns
7+
8+
Use the checked-in examples before inventing SDK usage. Each example folder contains `sync.py` for `Codex` and `async.py` for `AsyncCodex`.
9+
10+
## General Pattern
11+
12+
- Use plain strings for text-only turns.
13+
- Use typed input objects for multimodal or structured input lists.
14+
- Use only public exports from `openai_codex` and `openai_codex.types`.
15+
- From a checkout, run examples from `sdk/python`.
16+
17+
Recommended first run:
18+
19+
```sh
20+
python examples/01_quickstart_constructor/sync.py
21+
python examples/01_quickstart_constructor/async.py
22+
```
23+
24+
## Example Index
25+
26+
- `01_quickstart_constructor/`: first run and sanity check.
27+
- `02_turn_run/`: inspect full turn output fields.
28+
- `03_turn_stream_events/`: stream a turn with a curated event view.
29+
- `04_models_and_metadata/`: discover visible models for the connected runtime.
30+
- `05_existing_thread/`: resume an existing thread created in-script.
31+
- `06_thread_lifecycle_and_controls/`: thread lifecycle and control calls.
32+
- `07_image_and_text/`: remote image URL plus text multimodal turn.
33+
- `08_local_image_and_text/`: local image plus text multimodal turn using a generated sample image.
34+
- `09_async_parity/`: parity-style sync flow with async equivalent patterns elsewhere.
35+
- `10_error_handling_and_retry/`: overload retry pattern and typed error handling.
36+
- `11_cli_mini_app/`: interactive chat loop.
37+
- `12_turn_params_kitchen_sink/`: structured output with advanced `turn(...)` configuration.
38+
- `13_model_select_and_turn_params/`: list models, choose model and reasoning effort, run turns, and print usage.
39+
- `14_turn_controls/`: separate `steer()` and `interrupt()` demos.
40+
- `15_login_and_account/`: browser-login handle lifecycle, cancellation, and account inspection.
41+
42+
## Pattern Selection
43+
44+
- For quick scripts or backend jobs, start from quickstart plus `02_turn_run`.
45+
- For UI progress or dashboards, start from `03_turn_stream_events`.
46+
- For existing conversation state, start from `05_existing_thread`.
47+
- For user-controlled chat apps, start from `11_cli_mini_app`.
48+
- For schemas or advanced turn settings, start from `12_turn_params_kitchen_sink`.
49+
- For account onboarding or auth troubleshooting, start from `15_login_and_account`.

‎config/codex/skills/openai-codex-python-sdk/references/install-auth-runtime.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
canonical_url: https://github.com/openai/codex/blob/main/sdk/python/docs/getting-started.md
3+
last_verified: 2026-06-05
4+
---
5+
6+
# Install, Auth, and Runtime
7+
8+
Use this reference for setup, authentication, and packaging questions. Re-check the linked docs before precise version guidance.
9+
10+
## Install
11+
12+
- Published package: `openai-codex`
13+
- Import package: `openai_codex`
14+
- Python requirement observed in the docs: `>=3.10`
15+
- Basic install command:
16+
17+
```sh
18+
python -m pip install openai-codex
19+
```
20+
21+
The docs describe `openai-codex` as a public beta. While beta releases are the only published releases, normal pip install selects the latest beta; after a stable release exists, prerelease opt-in may require `--pre`.
22+
23+
## Authentication
24+
25+
The SDK reuses existing Codex authentication when one is available. Explicit login flows are available from `Codex`:
26+
27+
- `login_chatgpt()` starts browser login and returns a handle with an `auth_url`.
28+
- `login_chatgpt_device_code()` starts device-code login and returns a `verification_url` plus `user_code`.
29+
- `login_api_key(...)` authenticates synchronously with an API key.
30+
- Interactive login handles expose `wait()` for completion and `cancel()` to stop that attempt.
31+
- `account()` reads current account state, and `logout()` clears it.
32+
33+
Do not write real API keys into examples, tests, docs, or shell commands. Use placeholders only when documenting the API shape, and prefer environment variables or existing Codex auth for runnable code.
34+
35+
## Runtime Package
36+
37+
The SDK installs a compatible `openai-codex-cli-bin` runtime dependency automatically. The SDK and runtime packages are versioned independently, and each SDK release pins one compatible runtime package.
38+
39+
The adjacent runtime README says `openai-codex-cli-bin` is wheel-only and is staged during release so the SDK can pin an exact Codex CLI version without committing platform binaries to the repository.
40+
41+
## Checkout Development
42+
43+
For contributors running checked-in examples from the repository, the examples README says to work from `sdk/python` and install development dependencies:
44+
45+
```sh
46+
uv sync --extra dev
47+
source .venv/bin/activate
48+
```
49+
50+
The checked-in examples bootstrap local SDK imports from `sdk/python/src`. If the pinned runtime is missing for the active interpreter, the bootstrap installs the matching runtime package and cleans temporary files afterward.

‎config/codex/skills/openai-codex-python-sdk/references/threads-turns-sandbox.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
canonical_url: https://github.com/openai/codex/blob/main/sdk/python/docs/api-reference.md
3+
last_verified: 2026-06-05
4+
---
5+
6+
# Threads, Turns, and Sandbox
7+
8+
Use this reference for application structure and API shape. Re-read the API reference before exact signatures.
9+
10+
## Client Shape
11+
12+
- `Codex` is the sync client.
13+
- `AsyncCodex` is the async counterpart with the same public API shape.
14+
- Prefer `with Codex() as codex:` for sync code.
15+
- Prefer `async with AsyncCodex() as codex:` for async code.
16+
17+
The public package exports the client classes, config, approval and sandbox enums, login handles, thread and turn handles, input types, and selected protocol types under `openai_codex.types`.
18+
19+
## Thread Lifecycle
20+
21+
A `Thread` is conversation state. A turn is one model execution inside that thread.
22+
23+
Common lifecycle calls include:
24+
25+
- `thread_start(...)` to create a new thread.
26+
- `thread_resume(thread_id, ...)` to continue an existing thread.
27+
- `thread_list(...)`, `thread_fork(...)`, `thread_archive(...)`, and `thread_unarchive(...)` for thread management.
28+
- `models(...)` to list visible models for the connected runtime.
29+
30+
The public API keeps lifecycle calls explicit; do not invent aliases or wrapper names unless the target app already has them.
31+
32+
## Running Turns
33+
34+
Use `Thread.run(...)` for the common path. It accepts plain strings for text-only turns, starts the turn, waits for completion, and returns a `TurnResult`.
35+
36+
Use `Thread.turn(...)` when the application needs low-level control before collecting the result:
37+
38+
- `stream()` for raw notifications and progress UI.
39+
- `steer()` for active-turn steering.
40+
- `interrupt()` for cancellation or interruption flows.
41+
- `run()` on a turn handle to consume events and return the same `TurnResult` shape.
42+
43+
For async code, the corresponding `AsyncThread` and `AsyncTurnHandle` methods return awaitables or async streams.
44+
45+
## Result Shape
46+
47+
The API reference lists `TurnResult` fields such as:
48+
49+
- `id`
50+
- `status`
51+
- `error`
52+
- `started_at`
53+
- `completed_at`
54+
- `duration_ms`
55+
- `final_response`
56+
- `items`
57+
- `usage`
58+
59+
`final_response` can be `None` when a turn finishes without a final-answer or phase-less assistant message item. Check that case explicitly in application code.
60+
61+
## Sandbox Access
62+
63+
Use the same `sandbox=` keyword for thread lifecycle methods and turns:
64+
65+
- `Sandbox.read_only`: read files without writes.
66+
- `Sandbox.workspace_write`: read and write inside the workspace and configured writable roots.
67+
- `Sandbox.full_access`: run without filesystem access restrictions.
68+
69+
When omitted, Codex uses its configured default. The docs note that a turn sandbox override also applies to subsequent turns on that thread, so avoid using a broad sandbox for one turn and assuming later turns reset automatically.
70+
71+
## Keyword Arguments
72+
73+
Public Python keyword arguments are `snake_case`. The SDK maps wire-level camelCase internally. When migrating older snippets, check the FAQ mapping before editing.

0 commit comments

Comments
 (0)