USP

Offers 6 exceptionally deep, hand-maintained skills for critical fintech and platform integrations (Stripe, Supabase, Plaid, Expo), plus meta-tooling for Claude Code itself. Includes TOON compression commands to cut LLM input tokens by 40-…

Use cases

01Developing fintech applications with Stripe, Supabase, or Plaid integrations.
02Building mobile apps using Expo with Claude Code assistance.
03Optimizing LLM token usage by compressing JSON data with TOON.
04Creating custom Claude Code skills, commands, and hooks efficiently.
05Integrating Claude Code with external services via Model Context Protocol (MCP).

Detected files (8)

.agents/skills/anthropic/claude-command-builder/skill.mdskill

Show content (13016 bytes)

---
name: Codex-command-builder
description: Interactive slash command creator for Codex. Triggers when user mentions creating commands, slash commands, command templates, command arguments, or wants to build a new command workflow.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
---

# Codex Command Builder

## Purpose

Guide users through creating effective Codex slash commands with proper structure, argument handling, and workflow design. Auto-invokes when users want to create or modify custom commands.

## When to Use

Auto-invoke when users mention:
- **Creating commands** - "create command", "make command", "new slash command"
- **Command structure** - "command template", "command format", "command frontmatter"
- **Arguments** - "$ARGUMENTS", "$1", "$2", "command parameters", "positional args"
- **Workflows** - "command workflow", "command steps", "command process"
- **Bash execution** - "!`command`", "execute bash in command", "command with bash"

## Knowledge Base

- Official docs: `.Codex/skills/ai/Codex/docs/code_claude_com/docs_en_slash-commands.md`
- Project guide: `.Codex/docs/creating-components.md`
- Examples in repository: `.Codex/commands/`

## Process

### 1. Gather Requirements

Ask the user:

```
Let me help you create a Codex slash command! I need a few details:

1. **Command name** (lowercase-with-hyphens):
   Example: deploy, review-pr, commit, analyze-tokens
   This will be invoked as: /your-command-name

2. **What does this command do?**
   Describe the workflow in 1-2 sentences.

3. **Does it need arguments?**
   - None (simple prompt)
   - All arguments: $ARGUMENTS
   - Positional: $1, $2, $3, etc.

4. **Does it need bash execution?**
   Commands that run before the slash command (e.g., !`git status`)

5. **Scope:**
   - Personal (`~/.Codex/commands/`) - just for you
   - Project (`.Codex/commands/`) - shared with team

6. **Namespace/subdirectory?**
   Example: git/, deploy/, testing/
   Helps organize related commands
```

### 2. Validate Input

Check the command name:
- Must be valid filename (no spaces, special chars except hyphen)
- Descriptive and memorable
- Won't conflict with built-in commands
- Use hyphens (not underscores)

Validate arguments:
- Define expected arguments
- Provide defaults if needed
- Document argument order

### 3. Determine Command Type

**Simple Prompt (no frontmatter):**
```markdown
Analyze this code for performance issues and suggest optimizations.
```

**With Arguments:**
```markdown
---
argument-hint: [file-path]
description: Analyze file for performance issues
---

Analyze the file at $1 for performance issues and suggest optimizations.
```

**With Bash Execution:**
```markdown
---
allowed-tools: Bash(git status:*), Bash(git diff:*)
description: Create a git commit
---

## Current State

- Git status: !`git status`
- Staged changes: !`git diff --staged`
- Recent commits: !`git log --oneline -5`

## Your Task

Based on the above changes, create a git commit with a clear, conventional commit message.
```

**Full-Featured:**
```markdown
---
allowed-tools: Bash(npm run:*), Bash(git add:*), Bash(git commit:*)
argument-hint: [component-name]
description: Create a new React component with tests
model: sonnet
---

# Create React Component

Component name: $1

Execute the following workflow:

1. **Validate Input**
   !`test -n "$1" && echo "Creating component: $1" || echo "Error: Component name required"`

2. **Check Existing Files**
   !`ls src/components/$1.tsx 2>/dev/null || echo "Component does not exist"`

3. **Create Files**
   Create the following files:
   - `src/components/$1.tsx`
   - `src/components/$1.test.tsx`
   - `src/components/$1.module.css`

4. **Run Tests**
   After creation, run: !`npm run test -- $1`
```

### 4. Generate Command File

Create command structure based on complexity:

**Template for Simple Command:**
```markdown
Brief description of what the command does.

[Prompt instructions for Codex]
```

**Template for Command with Frontmatter:**
```markdown
---
argument-hint: [arg1] [arg2]
description: Brief description shown in /help
allowed-tools: Bash(command:*), Read, Write
model: sonnet
disable-model-invocation: false
---

# Command Name

Usage: /command-name [args]

[Detailed instructions]
```

### 5. Build Command Workflow

Structure the workflow with clear steps:

```markdown
Execute the following workflow:

1. **Step Name**
   ```bash
   # Bash command (if needed)
   command arg1 arg2
   ```
   - What this step does
   - Validation checks
   - Error handling

2. **Next Step**
   [Instructions for Codex]
   - What to check
   - How to proceed
   - What to output

3. **Final Step**
   - Summary of results
   - Next actions for user
   - Success criteria
```

### 6. Add Argument Handling

**All Arguments ($ARGUMENTS):**
```markdown
Fix issue #$ARGUMENTS following our coding standards.
```
User runs: `/fix-issue 123 high-priority`
Becomes: "Fix issue #123 high-priority following our coding standards."

**Positional Arguments ($1, $2, $3):**
```markdown
Review PR #$1 with priority $2 and assign to $3.
Focus on: $4
```
User runs: `/review-pr 456 high alice security`
Becomes individual parameters you can reference separately.

**With Defaults:**
```markdown
---
argument-hint: [environment] [branch]
---

Deploy to environment: ${1:-staging}
From branch: ${2:-main}
```

### 7. Add Bash Execution (if needed)

Use `!` prefix to execute commands before processing:

```markdown
---
allowed-tools: Bash(git:*)
---

## Context

- Current branch: !`git branch --show-current`
- Status: !`git status --short`
- Recent commits: !`git log --oneline -5`

## Your Task

[Instructions based on the above context]
```

**Important:**
- Must specify `allowed-tools` with specific Bash permissions
- Output is included in command context
- Commands run before Codex processes the prompt

### 8. Add File References

Use `@` prefix to reference files:

```markdown
Review the implementation in @src/utils/helpers.js

Compare @src/old-version.js with @src/new-version.js

Analyze all files in @src/components/
```

### 9. Configure Thinking Mode (if needed)

For complex problems, trigger extended thinking:

```markdown
Carefully analyze the following code and think through...

Let's approach this step by step...

Consider all edge cases before implementing...
```

These keywords can trigger extended thinking mode.

### 10. Create the File

Save to correct location:

**Personal command:**
```bash
~/.Codex/commands/command-name.md
~/.Codex/commands/category/command-name.md  # With namespace
```

**Project command:**
```bash
.Codex/commands/command-name.md
.Codex/commands/category/command-name.md  # With namespace
```

### 11. Test the Command

Provide testing instructions:

```
To test your command:
1. Restart Codex or start a new session
2. Type: /help
3. Find your command in the list
4. Try: /your-command-name [args]
5. Verify it behaves as expected
```

**Test cases:**
```bash
# No arguments
/your-command

# With arguments
/your-command arg1
/your-command arg1 arg2

# Edge cases
/your-command ""
/your-command "with spaces"
```

## Frontmatter Reference

Field| Purpose| Example
---|---|---
`argument-hint`| Show expected arguments in autocomplete| `[pr-number] [priority]`
`description`| Brief description for `/help` menu| `Review pull request`
`allowed-tools`| Tools command can use| `Bash(git:*), Read, Write`
`model`| Specific model to use| `Codex-sonnet-4-5-20250929`
`disable-model-invocation`| Prevent SlashCommand tool from calling this| `true`

## Bash Tool Permissions

When using `!` prefix or needing bash execution:

```markdown
---
allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git push:*)
---
```

**Permission patterns:**
- `Bash(git:*)` - All git commands
- `Bash(npm run:*)` - All npm run scripts
- `Bash(git add:*), Bash(git commit:*)` - Specific git commands

## Argument Patterns

### Pattern 1: All Arguments
```markdown
Run tests for: $ARGUMENTS
```
Usage: `/test users api database`
Becomes: "Run tests for: users api database"

### Pattern 2: Positional
```markdown
Deploy $1 to $2 environment with tag $3
```
Usage: `/deploy my-app staging v1.2.3`
Becomes: "Deploy my-app to staging environment with tag v1.2.3"

### Pattern 3: Mixed
```markdown
---
argument-hint: <file> [rest of args]
---

Analyze file $1 for: $ARGUMENTS
```
Usage: `/analyze src/app.js performance security`
Becomes: "Analyze file src/app.js for: src/app.js performance security"
Note: $ARGUMENTS includes all args, so $1 is duplicated

**Better approach:**
```markdown
Analyze file $1 for: ${2:+${@:2}}
```
This uses $1 separately and remaining args starting from $2

### Pattern 4: With Defaults
```markdown
Environment: ${1:-production}
Verbose: ${2:-false}
```

## Command Size Guidelines

- ✅ **Good:** < 100 lines
- ⚠️ **Warning:** 100-150 lines
- ❌ **Too large:** > 250 lines (must refactor)

**If too large:**
- Extract to external script
- Split into multiple commands
- Use sub-commands pattern

## Common Command Types

### 1. Git Workflow
```markdown
---
allowed-tools: Bash(git:*)
description: Create conventional commit
---

## Context
- Status: !`git status --short`
- Diff: !`git diff HEAD`

Create a conventional commit message.
```

### 2. Code Generator
```markdown
---
argument-hint: [component-name]
description: Generate React component
---

Create a new React component named $1:
- Component file
- Test file
- Storybook story
```

### 3. Analysis Tool
```markdown
---
argument-hint: [file-path]
description: Analyze code complexity
---

Analyze @$1 for:
- Cyclomatic complexity
- Code smells
- Improvement suggestions
```

### 4. Deployment Helper
```markdown
---
allowed-tools: Bash(npm:*), Bash(git:*)
argument-hint: [environment]
description: Deploy to environment
---

Deploy to ${1:-staging}:
1. Run tests: !`npm test`
2. Build: !`npm run build`
3. Deploy: !`npm run deploy:$1`
```

### 5. Documentation Generator
```markdown
---
argument-hint: [file-pattern]
description: Generate API documentation
---

Generate documentation for: $1
Include:
- Function signatures
- Parameters
- Return types
- Examples
```

## Examples from TOON Formatter

**Simple version:**
```markdown
# Convert to TOON

Convert the specified JSON file to TOON v2.0 format with automatic optimization and show token savings.

Usage: /convert-to-toon <file>
```

**Advanced version with bash:**
```markdown
---
allowed-tools: Bash(jq:*), Bash(.Codex/skills/toon-formatter/bin/toon:*)
argument-hint: <file> [--delimiter comma|tab|pipe]
description: Convert JSON to TOON format
---

# Convert to TOON

File: $1
Delimiter: ${2:-comma}

1. **Validate**: !`test -f "$1" && jq empty "$1" 2>&1`
2. **Analyze**: !`jq 'if type == "array" then length else 0 end' "$1"`
3. **Convert**: !`.Codex/skills/toon-formatter/bin/toon encode "$1"`
4. Show savings comparison
```

## Troubleshooting

### Command Not Found

**Check:**
```bash
# List all commands
ls ~/.Codex/commands/*.md
ls .Codex/commands/*.md

# Verify filename
ls .Codex/commands/your-command.md
```

**Remember:**
- Filename (without `.md`) becomes command name
- Hyphens in filename become hyphens in command
- Case-sensitive on Linux/Mac

### Arguments Not Working

**Debug:**
```markdown
Debug: $ARGUMENTS
Debug $1: "$1"
Debug $2: "$2"
```

Run command and check output to see what's being passed.

### Bash Commands Not Executing

**Check:**
1. `allowed-tools` includes correct Bash permissions
2. Using `!` prefix: `!`command``
3. Backticks are correct: \`command\` not 'command'
4. Command is allowed by permissions

### Command Not in /help

**Possible reasons:**
- File not in correct location
- File doesn't have `.md` extension
- Syntax error in frontmatter
- Need to restart Codex

## Best Practices

### DO:
✅ Provide clear argument hints
✅ Include usage examples
✅ Handle errors gracefully
✅ Show progress for long operations
✅ Document expected behavior
✅ Test with various inputs
✅ Use descriptive command names

### DON'T:
❌ Make commands too complex (>250 lines)
❌ Forget to specify allowed-tools for Bash
❌ Use unclear argument names
❌ Skip error handling
❌ Hardcode values (use arguments)
❌ Forget to test edge cases

## Comparison: Commands vs Skills

**Use Commands when:**
- You want explicit control (manual invocation)
- Simple, repetitive prompts
- Specific workflow steps
- Frequently-used templates

**Use Skills when:**
- Codex should auto-detect need
- Complex, multi-file workflows
- Comprehensive domain knowledge
- Team needs standardized expertise

**Can use both:**
- Command invokes skill explicitly
- Skill activates automatically
- Command provides quick access
- Skill provides deep capability

## Resources

- **Official Command Docs:** `.Codex/skills/ai/Codex/docs/code_claude_com/docs_en_slash-commands.md`
- **Project Component Guide:** `.Codex/docs/creating-components.md`
- **Command Examples:** `.Codex/commands/` directory
- **Skills vs Commands:** Section in slash-commands.md

.agents/skills/anthropic/claude-hook-builder/skill.mdskill

Show content (17716 bytes)

---
name: Codex-hook-builder
description: Interactive hook creator for Codex. Triggers when user mentions creating hooks, PreToolUse, PostToolUse, hook validation, hook configuration, settings.json hooks, or wants to automate tool execution workflows.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
---

# Codex Hook Builder

## Purpose

Guide users through creating effective Codex hooks for tool validation, automation, and workflow enhancement. Auto-invokes when users want to create or configure hooks.

## When to Use

Auto-invoke when users mention:
- **Creating hooks** - "create hook", "make hook", "new hook", "add hook"
- **Hook events** - "PreToolUse", "PostToolUse", "UserPromptSubmit", "Stop", "SessionStart"
- **Validation** - "validate", "check", "prevent", "block", "approve"
- **Automation** - "auto-format", "auto-lint", "automatic", "trigger"
- **Hook configuration** - "settings.json hooks", "hook matcher", "hook command"

## Knowledge Base

- Official docs: `.Codex/skills/ai/Codex/docs/code_claude_com/docs_en_hooks.md`
- Hook guide: `.Codex/skills/ai/Codex/docs/code_claude_com/docs_en_hooks-guide.md`
- Project guide: `.Codex/docs/creating-components.md`

## Process

### 1. Gather Requirements

Ask the user:

```
Let me help you create a Codex hook! I need some details:

1. **What should this hook do?**
   Examples:
   - Auto-format code after editing files
   - Validate bash commands before execution
   - Add context when user submits prompts
   - Prevent access to sensitive files
   - Run tests after file changes

2. **When should it trigger?**
   - PreToolUse (before tool execution)
   - PostToolUse (after tool execution)
   - UserPromptSubmit (when user sends message)
   - Stop (when Codex finishes responding)
   - SubagentStop (when subagent finishes)
   - SessionStart (when session begins)
   - SessionEnd (when session ends)
   - Notification (when notification sent)
   - PermissionRequest (when permission requested)

3. **Which tools should it match?**
   - Specific tool (Write, Edit, Bash, Read, etc.)
   - Multiple tools (Write|Edit)
   - All tools (*)
   - MCP tools (mcp__server__tool)

4. **What should it return?**
   - Simple exit code (0 = success, 2 = block)
   - JSON with decision control
   - Additional context for Codex
   - Modified tool inputs

5. **Scope:**
   - User-level (`~/.Codex/settings.json`)
   - Project-level (`.Codex/settings.json`)
   - Local project (`.Codex/settings.local.json`)
```

### 2. Determine Hook Type

**Bash Command Hook:**
```json
{
  "type": "command",
  "command": "/path/to/script.sh"
}
```
- Runs a shell command
- Fast, deterministic
- Good for validation, formatting

**Prompt-based Hook:**
```json
{
  "type": "prompt",
  "prompt": "Evaluate if Codex should stop: $ARGUMENTS"
}
```
- Uses LLM for decision
- Context-aware, intelligent
- Good for complex decisions (Stop, SubagentStop)

### 3. Choose Hook Event

#### PreToolUse
Runs before tool executes.

**Use for:**
- Validate inputs
- Auto-approve safe operations
- Block dangerous commands
- Modify tool parameters

**JSON Output:**
```json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow" | "deny" | "ask",
    "permissionDecisionReason": "Why this decision",
    "updatedInput": {
      "field": "new value"
    }
  }
}
```

#### PostToolUse
Runs after tool completes.

**Use for:**
- Auto-format code
- Run linters
- Validate outputs
- Log operations

**JSON Output:**
```json
{
  "decision": "block" | undefined,
  "reason": "Why blocking",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Extra info for Codex"
  }
}
```

#### UserPromptSubmit
Runs when user submits prompt.

**Use for:**
- Add context automatically
- Validate prompts
- Block sensitive prompts
- Inject current time/date

**JSON Output:**
```json
{
  "decision": "block" | undefined,
  "reason": "Why blocking",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Extra context"
  }
}
```

#### Stop / SubagentStop
Runs when Codex/subagent finishes.

**Use for:**
- Verify tasks completed
- Continue if work remains
- Intelligent stoppage control

**JSON Output:**
```json
{
  "decision": "block" | undefined,
  "reason": "Why must continue"
}
```

#### SessionStart
Runs when session starts.

**Use for:**
- Load environment variables
- Set up development context
- Install dependencies
- Inject initial context

**JSON Output:**
```json
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Initial context"
  }
}
```

**Special:** Can persist environment variables:
```bash
#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
fi
```

#### SessionEnd
Runs when session ends.

**Use for:**
- Cleanup tasks
- Save session stats
- Log session data

### 4. Create Hook Script

For bash command hooks, create a script:

**Template:**
```bash
#!/usr/bin/env bash

# Read JSON input from stdin
INPUT=$(cat)

# Parse JSON (requires jq)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Your validation logic here
if [[ condition ]]; then
  echo "Error message" >&2
  exit 2  # Block operation
fi

# Success
exit 0
```

**Python Template:**
```python
#!/usr/bin/env python3
import json
import sys

# Read JSON input
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})

# Your logic here
if condition:
    # Block with error
    print("Error message", file=sys.stderr)
    sys.exit(2)

# Or return JSON for control
output = {
    "decision": "approve",
    "reason": "Auto-approved"
}
print(json.dumps(output))
sys.exit(0)
```

### 5. Configure in settings.json

Add hook configuration:

**Basic Hook:**
```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/format.sh"
          }
        ]
      }
    ]
  }
}
```

**Multiple Hooks:**
```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/format.sh",
            "timeout": 30
          },
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/lint.sh",
            "timeout": 60
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/validate-bash.py"
          }
        ]
      }
    ]
  }
}
```

**No Matcher (events without tools):**
```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/add-context.sh"
          }
        ]
      }
    ]
  }
}
```

### 6. Hook Input Reference

Each event receives JSON on stdin:

**Common fields:**
```json
{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/dir",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse"
}
```

**PreToolUse/PostToolUse:**
```json
{
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": { /* PostToolUse only */
    "success": true
  }
}
```

**UserPromptSubmit:**
```json
{
  "prompt": "User's submitted message"
}
```

**Stop/SubagentStop:**
```json
{
  "stop_hook_active": false
}
```

### 7. Exit Codes

- **0**: Success
  - stdout shown in verbose mode (Ctrl+O)
  - For UserPromptSubmit/SessionStart: stdout added to context
  - JSON parsed if present

- **2**: Blocking error
  - stderr shown to Codex
  - Operation blocked (behavior varies by event)
  - JSON in stdout ignored

- **Other**: Non-blocking warning
  - stderr shown in verbose mode
  - Execution continues

### 8. Test the Hook

**Test script directly:**
```bash
# Create test input
echo '{
  "tool_name": "Write",
  "tool_input": {
    "file_path": "test.txt",
    "content": "hello"
  }
}' | .Codex/hooks/your-hook.sh

# Check exit code
echo $?
```

**Test in Codex:**
```
1. Add hook to settings.json
2. Restart Codex
3. Run /hooks to verify it's loaded
4. Trigger the hook (e.g., write a file)
5. Check verbose mode (Ctrl+O) for output
```

**Debug mode:**
```bash
Codex --debug
# Shows hook execution details
```

### 9. Provide Configuration

Show the complete configuration:

```json
{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/script.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}
```

## Hook Examples

### Example 1: Auto-Format Python Files

**Hook script** (`.Codex/hooks/format-python.sh`):
```bash
#!/usr/bin/env bash
INPUT=$(cat)

# Get file path
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Only process .py files
if [[ "$FILE_PATH" == *.py ]]; then
  # Run black formatter
  python -m black "$FILE_PATH" 2>&1

  if [[ $? -eq 0 ]]; then
    echo "Formatted: $FILE_PATH" >&2
  fi
fi

exit 0
```

**Configuration:**
```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/format-python.sh"
          }
        ]
      }
    ]
  }
}
```

### Example 2: Validate Bash Commands

**Hook script** (`.Codex/hooks/validate-bash.py`):
```python
#!/usr/bin/env python3
import json
import sys
import re

# Dangerous patterns
DANGEROUS = [
    (r'\brm\s+-rf\s+/', 'Dangerous: rm -rf on root'),
    (r'>\s*/dev/sd[a-z]', 'Dangerous: writing to block device'),
    (r'\bcurl\s+.*\|\s*bash', 'Dangerous: piping curl to bash'),
]

try:
    data = json.load(sys.stdin)
except:
    sys.exit(1)

if data.get('tool_name') != 'Bash':
    sys.exit(0)

command = data.get('tool_input', {}).get('command', '')

# Check for dangerous patterns
for pattern, message in DANGEROUS:
    if re.search(pattern, command):
        print(f"⚠️  {message}", file=sys.stderr)
        print(f"Command: {command}", file=sys.stderr)
        sys.exit(2)  # Block

sys.exit(0)  # Allow
```

**Configuration:**
```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/validate-bash.py"
          }
        ]
      }
    ]
  }
}
```

### Example 3: Add Timestamp to Prompts

**Hook script** (`.Codex/hooks/add-timestamp.sh`):
```bash
#!/usr/bin/env bash

# Output current timestamp
echo "Current time: $(date '+%Y-%m-%d %H:%M:%S %Z')"

exit 0
```

**Configuration:**
```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/add-timestamp.sh"
          }
        ]
      }
    ]
  }
}
```

### Example 4: Auto-Approve Documentation Reads

**Hook script** (`.Codex/hooks/auto-approve-docs.py`):
```python
#!/usr/bin/env python3
import json
import sys

data = json.load(sys.stdin)

if data.get('tool_name') != 'Read':
    sys.exit(0)

file_path = data.get('tool_input', {}).get('file_path', '')

# Auto-approve docs
if any(file_path.endswith(ext) for ext in ['.md', '.txt', '.json', '.yaml']):
    output = {
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "allow",
            "permissionDecisionReason": "Documentation file auto-approved"
        },
        "suppressOutput": True
    }
    print(json.dumps(output))
    sys.exit(0)

sys.exit(0)
```

**Configuration:**
```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/auto-approve-docs.py"
          }
        ]
      }
    ]
  }
}
```

### Example 5: Prevent Sensitive File Access

**Hook script** (`.Codex/hooks/block-secrets.sh`):
```bash
#!/usr/bin/env bash
INPUT=$(cat)

FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Block sensitive files
if [[ "$FILE_PATH" =~ \.env ||
      "$FILE_PATH" =~ secrets/ ||
      "$FILE_PATH" =~ \.aws/ ]]; then
  echo "⛔ Access to sensitive file blocked: $FILE_PATH" >&2
  exit 2
fi

exit 0
```

**Configuration:**
```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/block-secrets.sh"
          }
        ]
      }
    ]
  }
}
```

### Example 6: Intelligent Stop Hook (Prompt-based)

**Configuration:**
```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate whether Codex should stop. Context: $ARGUMENTS\n\nCheck if:\n1. All tasks are complete\n2. Tests are passing\n3. No errors need addressing\n\nRespond with JSON: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}",
            "timeout": 30
          }
        ]
      }
    ]
  }
}
```

### Example 7: Session Setup Hook

**Hook script** (`.Codex/hooks/session-setup.sh`):
```bash
#!/usr/bin/env bash

# Set up environment for session
if [ -n "$CLAUDE_ENV_FILE" ]; then
  # Load nvm
  source ~/.nvm/nvm.sh
  nvm use 20

  # Capture environment changes
  export -p >> "$CLAUDE_ENV_FILE"

  # Add custom variables
  echo 'export NODE_ENV=development' >> "$CLAUDE_ENV_FILE"
fi

# Add context
echo "Development environment initialized"
echo "Node version: $(node --version)"

exit 0
```

**Configuration:**
```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/session-setup.sh"
          }
        ]
      }
    ]
  }
}
```

## Matcher Patterns

**Exact match:**
```json
"matcher": "Write"
```

**Multiple tools (regex):**
```json
"matcher": "Write|Edit|NotebookEdit"
```

**All tools:**
```json
"matcher": "*"
```
Or:
```json
"matcher": ""
```

**MCP tools:**
```json
"matcher": "mcp__github__.*"
"matcher": "mcp__.*__write.*"
```

**Event-specific matchers:**

Notification:
```json
"matcher": "permission_prompt"
"matcher": "idle_prompt"
```

PreCompact:
```json
"matcher": "manual"
"matcher": "auto"
```

SessionStart:
```json
"matcher": "startup"
"matcher": "resume"
"matcher": "clear"
```

## Environment Variables

Available in hook scripts:

- `$CLAUDE_PROJECT_DIR` - Absolute path to project root
- `$CLAUDE_CODE_REMOTE` - "true" if remote/web, empty if local
- `$CLAUDE_ENV_FILE` - (SessionStart only) File to persist env vars
- Standard environment variables

## Best Practices

### DO:
✅ Keep hooks fast (<100ms recommended)
✅ Provide clear error messages
✅ Use appropriate exit codes
✅ Quote variables in bash: `"$VAR"`
✅ Validate inputs before processing
✅ Test thoroughly before deploying
✅ Use `$CLAUDE_PROJECT_DIR` for portability
✅ Document what your hook does

### DON'T:
❌ Run slow operations (full test suites)
❌ Block legitimate operations unnecessarily
❌ Use hooks for everything (be selective)
❌ Forget to handle errors
❌ Skip input validation
❌ Hardcode absolute paths
❌ Leave debug output in production

## Security Considerations

**⚠️ USE AT YOUR OWN RISK**

Hooks execute arbitrary commands:
- Can modify/delete any files
- Can access sensitive data
- Can cause data loss
- Anthropic provides no warranty

**Best practices:**
- Validate and sanitize inputs
- Quote all variables
- Block path traversal (`..`)
- Use absolute paths
- Skip sensitive files
- Test in safe environment first

## Troubleshooting

### Hook Not Running

**Check:**
1. Hook is in `settings.json` correctly
2. Matcher pattern is correct (case-sensitive)
3. Script has execute permissions: `chmod +x script.sh`
4. Script shebang is correct: `#!/usr/bin/env bash`
5. Restart Codex after config changes

**Debug:**
```bash
# Run with debug mode
Codex --debug

# Check hook execution in output
# Shows: "Executing hooks for PostToolUse:Write"
```

### Hook Errors

**Check:**
1. Script runs standalone: `echo '{}' | ./script.sh`
2. Exit code is correct: `echo $?`
3. JSON output is valid: `./script.sh | jq .`
4. Timeout is sufficient (default: 60s)

**View errors:**
- Verbose mode: Ctrl+O
- Debug mode: `Codex --debug`
- Check stderr output

### Permissions Issues

**Check:**
```bash
# Make script executable
chmod +x .Codex/hooks/script.sh

# Verify permissions
ls -la .Codex/hooks/
```

### JSON Parse Errors

**Validate JSON:**
```bash
# Test JSON output
echo '{}' | ./script.sh | jq .

# Common issues:
# - Missing quotes
# - Trailing commas
# - Single quotes instead of double
```

## Resources

- **Official Hook Docs:** `.Codex/skills/ai/Codex/docs/code_claude_com/docs_en_hooks.md`
- **Hook Guide:** `.Codex/skills/ai/Codex/docs/code_claude_com/docs_en_hooks-guide.md`
- **Settings Reference:** `.Codex/skills/ai/Codex/docs/code_claude_com/docs_en_settings.md`
- **Project Guide:** `.Codex/docs/creating-components.md`

.agents/skills/anthropic/claude-mcp-expert/SKILL.mdskill

Show content (8262 bytes)

---
name: Codex-mcp-expert
description: Model Context Protocol (MCP) expert for Codex. Install, configure, and troubleshoot MCP servers. Covers HTTP, SSE, and stdio transports, authentication, popular integrations (Sentry, GitHub, Jira, Notion, databases). Triggers on MCP, Model Context Protocol, MCP server, installing MCP, connecting tools, webhooks, remote server.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
license: MIT
metadata:
  author: raintree
  version: "1.0"
---

# Codex MCP Expert

Connect Codex to external tools, databases, and services using Model Context Protocol (MCP).

## When to Use

- User wants to connect external services (GitHub, Jira, Sentry)
- User needs database access (PostgreSQL, MongoDB)
- User asks about MCP configuration or `.mcp.json`
- User has MCP connection or authentication issues

## What is MCP?

**Model Context Protocol (MCP)** is an open standard that connects AI agents to:
- External APIs (GitHub, Jira, Notion, Slack)
- Databases (PostgreSQL, MongoDB, MySQL)
- File systems (local, Google Drive)
- Custom integrations

## Quick Start

```bash
# Add an HTTP server
Codex mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Add an SSE server
Codex mcp add --transport sse atlassian https://mcp.atlassian.com/v1/sse

# Add a stdio server (npm package)
Codex mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-github

# Manage servers interactively
/mcp
```

## Transport Types

### HTTP (Most Common)
For cloud services with REST-like endpoints.

```bash
Codex mcp add --transport http sentry https://mcp.sentry.dev/mcp
Codex mcp add --transport http github https://api.github.com/mcp
Codex mcp add --transport http notion https://mcp.notion.com/mcp
```

### SSE (Server-Sent Events)
For streaming services.

```bash
Codex mcp add --transport sse atlassian https://mcp.atlassian.com/v1/sse
Codex mcp add --transport sse asana https://mcp.asana.com/sse
```

### stdio (Local/NPM Packages)
For local tools or npm packages.

```bash
Codex mcp add --transport stdio postgres \
  --env POSTGRES_CONNECTION_STRING="postgresql://user:pass@localhost:5432/db" \
  -- npx -y @modelcontextprotocol/server-postgres

Codex mcp add --transport stdio filesystem \
  --env ALLOWED_DIRECTORIES="/path/to/dir" \
  -- npx -y @modelcontextprotocol/server-filesystem
```

## Popular Integrations

### Development Tools

| Service | Command |
|---------|---------|
| **Sentry** | `Codex mcp add --transport http sentry https://mcp.sentry.dev/mcp` |
| **GitHub** | `Codex mcp add --transport http github https://api.github.com/mcp` |
| **Socket** | `Codex mcp add --transport http socket https://mcp.socket.dev/` |

### Project Management

| Service | Command |
|---------|---------|
| **Jira** | `Codex mcp add --transport sse atlassian https://mcp.atlassian.com/v1/sse` |
| **Linear** | `Codex mcp add --transport http linear https://mcp.linear.app/mcp` |
| **Notion** | `Codex mcp add --transport http notion https://mcp.notion.com/mcp` |
| **Asana** | `Codex mcp add --transport sse asana https://mcp.asana.com/sse` |

### Databases

```bash
# PostgreSQL
Codex mcp add --transport stdio postgres \
  --env POSTGRES_CONNECTION_STRING="postgresql://localhost:5432/mydb" \
  -- npx -y @modelcontextprotocol/server-postgres

# MongoDB
Codex mcp add --transport stdio mongodb \
  --env MONGODB_URI="mongodb://localhost:27017/mydb" \
  -- npx -y @modelcontextprotocol/server-mongodb
```

### Communication

```bash
# Slack
Codex mcp add --transport stdio slack \
  --env SLACK_BOT_TOKEN=xoxb-your-token \
  --env SLACK_TEAM_ID=T1234567 \
  -- npx -y @modelcontextprotocol/server-slack

# Gmail
Codex mcp add --transport stdio gmail \
  -- npx -y @modelcontextprotocol/server-gmail
```

## Configuration Files

### .mcp.json Structure

```json
{
  "mcpServers": {
    "server-name": {
      "transport": "http",
      "url": "https://mcp.service.com/mcp"
    },
    "database": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://localhost/db"
      }
    }
  }
}
```

### Configuration Scopes

| Scope | Location | Use Case |
|-------|----------|----------|
| **User** | `~/.Codex/.mcp.json` | Personal tools, global |
| **Project** | `.Codex/.mcp.json` | Team-shared, git committed |
| **Local** | `.Codex/.mcp.local.json` | Personal overrides, not committed |

### Add with Scope

```bash
Codex mcp add --transport http sentry https://mcp.sentry.dev/mcp --user     # Global
Codex mcp add --transport http linear https://mcp.linear.app/mcp --project  # Team
Codex mcp add --transport http notion https://mcp.notion.com/mcp --local    # Personal override
```

## Authentication

### OAuth (Recommended)
```bash
# Install server
Codex mcp add --transport http github https://api.github.com/mcp

# Authenticate via /mcp command
/mcp
# Select: Authenticate with server
# Browser opens → authorize → done
```

### API Keys (Environment Variables)
```bash
Codex mcp add --transport stdio server-name \
  --env API_KEY=your_api_key \
  -- npx -y package-name
```

### Via settings.json
```json
{
  "env": {
    "GITHUB_TOKEN": "ghp_xxxxx",
    "SENTRY_AUTH_TOKEN": "sntrys_xxxxx"
  }
}
```

## Using MCP Features

### MCP Tools
Once connected, use naturally:
```
"Check Sentry for errors in the last 24 hours"
"Create a PR for this feature on GitHub"
"List my assigned Jira tickets"
"Query the users table for active accounts"
```

### MCP Resources
Reference MCP-provided files:
```
Review @mcp://github/README.md and suggest improvements
```

### MCP Prompts as Commands
MCP prompts become slash commands:
```
/mcp__github__create_issue "Bug in login" high
/mcp__jira__update_status PROJ-123 "In Progress"
```

## Managing Servers

### Interactive Management
```bash
/mcp
# Options:
# - View all servers
# - Add new server
# - Remove server
# - Authenticate
# - View tools/prompts/resources
```

### Command Line
```bash
Codex mcp list                    # List servers
Codex mcp add ...                 # Add server
Codex mcp remove server-name      # Remove server
```

## Troubleshooting

### Server Not Connecting

1. **Verify URL/command** - check for typos
2. **Check auth** - run `/mcp` → Authenticate
3. **Test network** - can you reach the URL?
4. **Debug mode** - run `Codex --debug`

### Authentication Failing

1. Re-authenticate: `/mcp` → Clear auth → Re-authenticate
2. Check API key validity
3. Verify OAuth tokens not expired
4. Check permissions/scopes

### stdio Server Errors

```bash
# Test command manually
npx -y @modelcontextprotocol/server-postgres

# Check environment variables are set
echo $POSTGRES_CONNECTION_STRING

# Verify npm package exists
npm info @modelcontextprotocol/server-postgres
```

### Tools Not Available

1. Confirm server is connected: `/mcp`
2. Check authentication completed
3. Restart Codex
4. Verify server provides expected tools

## Security Best Practices

**DO:**
- Use OAuth when available
- Store secrets in settings.json, not .mcp.json
- Use project scope for team configs
- Review server permissions regularly

**DON'T:**
- Commit API keys to git
- Install untrusted servers
- Share OAuth tokens
- Use broad permissions unnecessarily

## Example Workflows

### Issue to PR
```bash
# Setup
Codex mcp add --transport http github https://api.github.com/mcp
Codex mcp add --transport sse atlassian https://mcp.atlassian.com/v1/sse

# Usage
"Read JIRA ticket ENG-123, implement the feature, and create a PR on GitHub"
```

### Error Investigation
```bash
# Setup
Codex mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Usage
"Check Sentry for errors in the last hour and fix them"
```

### Database Query to Report
```bash
# Setup
Codex mcp add --transport stdio postgres \
  --env POSTGRES_CONNECTION_STRING="postgresql://localhost/analytics" \
  -- npx -y @modelcontextprotocol/server-postgres

# Usage
"Find users who signed up this month and summarize their activity"
```

## Resources

- **MCP Website:** https://modelcontextprotocol.io/
- **MCP Servers List:** https://github.com/modelcontextprotocol/servers
- **Codex MCP Docs:** https://docs.anthropic.com/en/docs/Codex/mcp

.agents/skills/anthropic/skill.mdskill

Show content (4392 bytes)

---
name: anthropic-expert
description: Expert on Anthropic Codex API, models, prompt engineering, function calling, vision, and best practices. Triggers on anthropic, Codex, api, prompt, function calling, vision, messages api, embeddings
allowed-tools: Read, Grep, Glob
model: sonnet
---

# Anthropic API Expert

## Purpose

Provide expert guidance on Anthropic's Codex API, including prompt engineering, function calling, vision capabilities, and best practices based on official Anthropic documentation.

## When to Use

Auto-invoke when users mention:
- **Anthropic** - company, API, platform
- **Codex** - models (Opus, Sonnet, Haiku), capabilities
- **API** - Messages API, streaming, embeddings
- **Features** - function calling, vision, extended context, prompt caching
- **Integration** - SDKs (Python, TypeScript), REST API

## Knowledge Base

**Full access to official Anthropic documentation (when available):**
- **Location:** `docs/`
- **Files:** 199 markdown files
- **Format:** `.md` files

**Note:** Documentation must be pulled separately:
```bash
pipx install docpull
docpull https://docs.anthropic.com -o .Codex/skills/anthropic/docs
```

## Process

When a user asks about Anthropic/Codex:

### 1. Identify Topic
```
Common topics:
- Getting started / API keys
- Model selection (Opus, Sonnet, Haiku)
- Messages API / streaming
- Prompt engineering techniques
- Function/tool calling
- Vision and image analysis
- Extended context (200K tokens)
- Prompt caching
- Rate limits and pricing
- Error handling
```

### 2. Search Documentation

Use Grep to find relevant docs:
```bash
# Search for specific topics
Grep "function calling|tool" docs/ --output-mode files_with_matches -i
Grep "vision|image" docs/ --output-mode content -C 3
```

Check the INDEX.md for navigation:
```bash
Read docs/INDEX.md
```

### 3. Read Relevant Files

Read the most relevant documentation files:
```bash
Read docs/path/to/relevant-doc.md
```

### 4. Provide Answer

Structure your response:
- **Direct answer** - solve the user's problem first
- **Code examples** - show API calls with proper formatting
- **Best practices** - mention Codex-specific patterns
- **Model selection** - recommend appropriate model (Opus/Sonnet/Haiku)
- **References** - cite specific docs for deeper reading
- **Cost optimization** - mention prompt caching, model choice

## Example Workflows

### Example 1: Function Calling
```
User: "How do I implement function calling with Codex?"

1. Search: Grep "function calling|tool" docs/
2. Read: Function calling documentation
3. Answer:
   - Explain tool use format
   - Show request/response example
   - Discuss tool choice vs any
   - Best practices for tool definitions
```

### Example 2: Vision Capabilities
```
User: "Can Codex analyze images?"

1. Search: Grep "vision|image" docs/ -i
2. Read: Vision API documentation
3. Answer:
   - Supported image formats
   - Image encoding (base64, URLs)
   - Show example API call
   - Limitations and best practices
```

### Example 3: Prompt Engineering
```
User: "How do I write better prompts for Codex?"

1. Search: Grep "prompt|engineering" docs/
2. Read: Prompt engineering guide
3. Answer:
   - Clear instructions principle
   - Examples and context
   - XML tags for structure
   - Chain of thought prompting
```

## Key Concepts to Reference

**Models:**
- Codex 3.5 Opus - most capable
- Codex 3.5 Sonnet - balanced (recommended for most use cases)
- Codex 3.5 Haiku - fast and economical

**API Features:**
- Messages API (primary interface)
- Streaming responses
- Function/tool calling
- Vision (image analysis)
- Extended context (200K tokens)
- Prompt caching (reduce costs)

**Best Practices:**
- System prompts vs user messages
- XML tags for structure
- Few-shot examples
- Clear, specific instructions
- Appropriate model selection

**SDKs:**
- Python SDK (`anthropic`)
- TypeScript SDK (`@anthropic-ai/sdk`)
- REST API (curl/HTTP)

## Response Style

- **Clear** - API developers want precise answers
- **Code-first** - show working examples
- **Model-aware** - recommend appropriate Codex model
- **Cost-conscious** - mention caching, model choice
- **Cite sources** - reference specific doc sections

## Follow-up Suggestions

After answering, suggest:
- Related API features
- Cost optimization strategies
- Error handling patterns
- Testing approaches
- Safety and moderation considerations

.agents/skills/anthropic/claude-code/skill.mdskill

Show content (4856 bytes)

---
name: Codex-expert
description: Expert on Codex CLI, skills, commands, hooks, plugins, MCP, settings, and workflows. Triggers on Codex, cli, skill, command, hook, plugin, mcp, slash command, settings
allowed-tools: Read, Grep, Glob
model: sonnet
---

# Codex Expert

## Purpose

Provide expert guidance on Codex CLI features, including skills, commands, hooks, plugins, MCP integration, and configuration based on official Codex documentation.

## When to Use

Auto-invoke when users mention:
- **Codex** - CLI tool, features, usage
- **Skills** - creating, using, configuring skills
- **Commands** - slash commands, custom commands
- **Hooks** - pre/post tool use hooks, validation
- **Plugins** - MCP plugins, plugin system
- **Configuration** - settings.json, AGENTS.md, customization
- **Features** - agents, memory, sandboxing, headless mode

## Knowledge Base

Documentation is stored in Markdown format (multiple languages):
- **Location:** `docs/`
- **Index:** `docs/INDEX.md`
- **Format:** `.md` files
- **Note:** English docs have `_en` suffix, e.g., `docs_en_skills.md`

## Process

When a user asks about Codex:

### 1. Identify Topic
```
Common topics:
- Getting started / installation
- Creating skills
- Writing slash commands
- Implementing hooks
- Using MCP plugins
- Configuration (settings.json, AGENTS.md)
- Agents and sub-agents
- Memory and context management
- Sandboxing and security
- Headless/CI mode
- IDE integration (VS Code, JetBrains)
```

### 2. Search Documentation

Use Grep to find relevant English docs:
```bash
# Search for specific topics (focus on English docs)
Grep "skill" docs/ --output-mode files_with_matches --glob "*_en_*.md"
Grep "hook|validation" docs/ --output-mode content -C 3 --glob "*_en_*.md"
```

Check the INDEX.md for navigation:
```bash
Read docs/INDEX.md
```

### 3. Read Relevant Files

Read the most relevant English documentation files:
```bash
# Prefer English (_en) versions
Read docs/code_claude_com/docs_en_skills.md
Read docs/code_claude_com/docs_en_slash-commands.md
```

### 4. Provide Answer

Structure your response:
- **Direct answer** - solve the user's problem first
- **File examples** - show skill.md, command.md structure
- **Configuration** - show settings.json snippets
- **Best practices** - mention Codex-specific patterns
- **References** - cite specific docs (prefer English versions)
- **File paths** - use proper `.Codex/` directory structure

## Example Workflows

### Example 1: Creating a Skill
```
User: "How do I create a skill in Codex?"

1. Search: Grep "skill" docs/ --glob "*_en_*.md"
2. Read: docs_en_skills.md
3. Answer:
   - Explain skill.md frontmatter format
   - Show directory structure
   - Provide skill template
   - Explain trigger keywords
   - Mention allowed-tools
```

### Example 2: Writing Hooks
```
User: "How do I create a post-edit hook?"

1. Search: Grep "hook|PostToolUse" docs/ --glob "*_en_*.md"
2. Read: docs_en_hooks.md, docs_en_hooks-guide.md
3. Answer:
   - Explain hook types (PostToolUse, etc.)
   - Show hook file structure
   - Demonstrate settings.json configuration
   - Provide validation example
```

### Example 3: MCP Integration
```
User: "How do I use MCP plugins with Codex?"

1. Search: Grep "mcp|plugin" docs/ --glob "*_en_*.md"
2. Read: docs_en_mcp.md, docs_en_plugins.md
3. Answer:
   - Explain MCP (Model Context Protocol)
   - Show plugin installation
   - Demonstrate configuration
   - List available plugins
```

## Key Concepts to Reference

**Core Components:**
- Skills (auto-invoked knowledge domains)
- Commands (slash commands, manual workflows)
- Hooks (validation, automation)
- Plugins (MCP extensions)
- AGENTS.md (project instructions)
- settings.json (configuration)

**Features:**
- Agents and sub-agents
- Memory system
- Sandboxing (Docker, Podman)
- Headless mode (CI/CD)
- IDE integration (VS Code, JetBrains)
- Third-party integrations

**Directory Structure:**
```
.Codex/
├── skills/           # Auto-invoked skills
├── commands/         # Slash commands
├── hooks/            # Validation hooks
├── docs/             # Documentation
└── settings.json     # Configuration
```

**Configuration Files:**
- `.Codex/settings.json` - Codex settings
- `AGENTS.md` - Project-specific instructions
- `skill.md` - Skill definition (with frontmatter)
- `command-name.md` - Command workflow

## Response Style

- **Practical** - developers want working examples
- **File-structure focused** - show exact file locations
- **Configuration-clear** - precise JSON/YAML examples
- **English-first** - reference `_en` docs when available
- **Cite sources** - reference specific doc files

## Follow-up Suggestions

After answering, suggest:
- Related Codex features
- Configuration best practices
- Testing and debugging approaches
- Community resources
- Advanced workflows

.agents/skills/anthropic/claude-settings-expert/skill.mdskill

Show content (14918 bytes)

---
name: Codex-settings-expert
description: Expert on Codex settings.json configuration, permissions, sandbox, environment variables, and settings hierarchy. Triggers when user mentions settings.json, permissions, allow rules, deny rules, sandbox, hooks configuration, or settings precedence.
allowed-tools: Read, Write, Edit, Grep, Glob
model: sonnet
---

# Codex Settings Expert

## Purpose

Provide expert guidance on configuring Codex through settings.json, including permissions, hooks, sandbox configuration, environment variables, and settings hierarchy. Auto-invokes when users need help with settings.

## When to Use

Auto-invoke when users mention:
- **Settings files** - "settings.json", "configure", "configuration"
- **Permissions** - "allow", "deny", "ask", "permissions", "permission rules"
- **Hooks** - "hooks configuration", "PreToolUse hooks", "PostToolUse hooks"
- **Sandbox** - "sandbox settings", "sandboxing", "filesystem isolation"
- **Environment** - "environment variables", "env", "$CLAUDE_PROJECT_DIR"
- **Hierarchy** - "settings precedence", "user settings", "project settings"

## Knowledge Base

- Official docs: `.Codex/skills/ai/Codex/docs/code_claude_com/docs_en_settings.md`
- IAM docs: Look for IAM/permissions documentation
- Hooks docs: `.Codex/skills/ai/Codex/docs/code_claude_com/docs_en_hooks.md`

## Settings File Locations

### Hierarchy (highest to lowest precedence)

1. **Enterprise managed policies**
   - macOS: `/Library/Application Support/Codex/managed-settings.json`
   - Linux/WSL: `/etc/Codex/managed-settings.json`
   - Windows: `C:\ProgramData\Codex\managed-settings.json`
   - Cannot be overridden by users

2. **Command line arguments**
   - Temporary overrides for specific session
   - Example: `Codex --dangerously-skip-permissions`

3. **Local project settings**
   - `.Codex/settings.local.json`
   - Personal project settings (not committed)
   - Git-ignored automatically

4. **Shared project settings**
   - `.Codex/settings.json`
   - Team-shared settings in source control
   - Committed to repository

5. **User settings**
   - `~/.Codex/settings.json`
   - Personal global settings
   - Apply to all projects

### When to Use Each

**User settings** (`~/.Codex/settings.json`):
- Personal preferences across all projects
- Personal API keys
- Personal slash commands
- Personal output style

**Project settings** (`.Codex/settings.json`):
- Team permissions
- Project-specific hooks
- Required plugins/marketplaces
- Team workflow configuration

**Local project** (`.Codex/settings.local.json`):
- Personal project overrides
- Experimental settings
- Local-only preferences
- Not shared with team

## Process

### 1. Identify Need

Ask clarifying questions:

```
What would you like to configure?

1. **Permissions** - Allow/deny specific tools or commands
2. **Hooks** - Automate tool execution workflows
3. **Sandbox** - Enable filesystem/network isolation
4. **Environment** - Set environment variables
5. **Plugins** - Configure plugins and marketplaces
6. **Model** - Override default model
7. **Other** - Company announcements, cleanup, etc.
```

### 2. Determine Scope

Ask about scope:

```
Where should this configuration apply?

- **User-level** (`~/.Codex/settings.json`) - All your projects
- **Project-level** (`.Codex/settings.json`) - This project, shared with team
- **Local** (`.Codex/settings.local.json`) - This project, just you
```

### 3. Build Configuration

Based on needs, construct the appropriate JSON:

## Permission Configuration

### Structure

```json
{
  "permissions": {
    "allow": ["permission-rule"],
    "ask": ["permission-rule"],
    "deny": ["permission-rule"],
    "additionalDirectories": ["../path"],
    "defaultMode": "default" | "plan" | "acceptEdits" | "bypassPermissions",
    "disableBypassPermissionsMode": "disable"
  }
}
```

### Permission Rules

**Tool-specific:**
```json
{
  "permissions": {
    "allow": [
      "Read(~/.zshrc)",
      "Bash(git diff:*)",
      "Bash(npm run lint:*)",
      "Bash(npm run test:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl:*)",
      "WebFetch",
      "WebSearch"
    ]
  }
}
```

**Bash permissions:**
- Use prefix matching (not regex)
- `Bash(git:*)` - All git commands
- `Bash(git diff:*)` - Only git diff commands
- Can be bypassed (not for security, use sandbox for that)

**Read/Write permissions:**
- `Read(./secrets/**)` - Recursive pattern
- `Read(./.env)` - Specific file
- `Write(./dist/**)` - Allow writes to dist

**Permission modes:**
- `default` - Ask for permission
- `plan` - Plan mode (no execution without approval)
- `acceptEdits` - Auto-approve edits only
- `bypassPermissions` - Approve all (dangerous)

### Example: Secure Development

```json
{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npm run lint:*)",
      "Bash(npm run test:*)",
      "Read(~/.gitconfig)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(rm -rf:*)",
      "WebFetch",
      "WebSearch"
    ],
    "defaultMode": "default"
  }
}
```

## Hooks Configuration

### Structure

```json
{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command" | "prompt",
            "command": "bash command",
            "prompt": "LLM prompt with $ARGUMENTS",
            "timeout": 60
          }
        ]
      }
    ]
  },
  "disableAllHooks": false
}
```

### Example: Auto-Format and Validate

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/format.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/validate-bash.py"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/add-context.sh"
          }
        ]
      }
    ]
  }
}
```

## Sandbox Configuration

### Structure

```json
{
  "sandbox": {
    "enabled": true | false,
    "autoAllowBashIfSandboxed": true | false,
    "excludedCommands": ["git", "docker"],
    "allowUnsandboxedCommands": true | false,
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true | false,
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    },
    "enableWeakerNestedSandbox": false
  }
}
```

### Example: Strict Sandbox

```json
{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "allowUnsandboxedCommands": false,
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "Read(.envrc)",
      "Read(~/.aws/**)",
      "Read(./secrets/**)"
    ]
  }
}
```

**Notes:**
- Filesystem access via Read/Write/Edit deny rules
- Network access via WebFetch allow/deny rules
- macOS/Linux only (not Windows)

## Environment Variables

### Structure

```json
{
  "env": {
    "KEY": "value",
    "NODE_ENV": "production",
    "API_URL": "https://api.example.com"
  }
}
```

### Common Variables

```json
{
  "env": {
    "ANTHROPIC_MODEL": "Codex-sonnet-4-5-20250929",
    "DISABLE_TELEMETRY": "1",
    "DISABLE_AUTOUPDATER": "1",
    "DISABLE_PROMPT_CACHING": "0",
    "MAX_THINKING_TOKENS": "10000",
    "BASH_DEFAULT_TIMEOUT_MS": "120000"
  }
}
```

## Plugin Configuration

### Structure

```json
{
  "enabledPlugins": {
    "plugin-name@marketplace-name": true | false
  },
  "extraKnownMarketplaces": {
    "marketplace-name": {
      "source": {
        "source": "github" | "git" | "directory",
        "repo": "org/repo",
        "url": "https://git.example.com/repo.git",
        "path": "/local/path"
      }
    }
  }
}
```

### Example: Team Plugins

```json
{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment@company-tools": true,
    "security-scanner@company-tools": false
  },
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "company/Codex-plugins"
      }
    }
  }
}
```

## Other Settings

### Model Override

```json
{
  "model": "Codex-sonnet-4-5-20250929"
}
```

### Cleanup Period

```json
{
  "cleanupPeriodDays": 20
}
```

### Company Announcements

```json
{
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs"
  ]
}
```

### Force Login Method

```json
{
  "forceLoginMethod": "console",
  "forceLoginOrgUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

### API Key Helper

```json
{
  "apiKeyHelper": "/bin/generate_temp_api_key.sh"
}
```

### Disable Co-Authored-By

```json
{
  "includeCoAuthoredBy": false
}
```

### Status Line

```json
{
  "statusLine": {
    "type": "command",
    "command": "~/.Codex/statusline.sh"
  }
}
```

### Output Style

```json
{
  "outputStyle": "Explanatory"
}
```

## Complete Example: Enterprise Project

```json
{
  "permissions": {
    "allow": [
      "Bash(npm run:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(docker ps:*)",
      "Bash(kubectl get:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/production.json)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(git push:*)",
      "WebFetch",
      "WebSearch"
    ],
    "ask": [
      "Bash(git add:*)",
      "Bash(git commit:*)",
      "Write(./src/**)"
    ],
    "defaultMode": "default",
    "disableBypassPermissionsMode": "disable"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/lint-and-format.sh",
            "timeout": 60
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.Codex/hooks/validate-bash.py"
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker", "kubectl"],
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  },
  "env": {
    "NODE_ENV": "development",
    "DISABLE_TELEMETRY": "1"
  },
  "enabledPlugins": {
    "security-scanner@company-tools": true,
    "code-quality@company-tools": true
  },
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "company/Codex-plugins"
      }
    }
  },
  "companyAnnouncements": [
    "Welcome to Company Dev! See docs.company.com for coding standards",
    "Reminder: All PRs require security scan approval"
  ],
  "model": "Codex-sonnet-4-5-20250929",
  "cleanupPeriodDays": 20,
  "includeCoAuthoredBy": true
}
```

## Validation

### Check JSON Syntax

```bash
# Validate JSON
cat .Codex/settings.json | jq .

# Pretty-print
cat .Codex/settings.json | jq . > temp.json && mv temp.json .Codex/settings.json
```

### Test Configuration

```bash
# Start Codex with debug
Codex --debug

# Check settings loaded
# Look for: "Loading settings from..."
```

### Verify Permissions

```bash
# Run /permissions in Codex
/permissions

# Check what's allowed/denied
```

## Troubleshooting

### Settings Not Applied

**Check:**
1. JSON syntax is valid (`jq` validation)
2. File location is correct
3. Restart Codex after changes
4. Check precedence (higher-level settings override)

### Permission Rules Not Working

**Check:**
1. Rule syntax: `Tool(pattern)`
2. Case-sensitive tool names
3. Bash uses prefix matching (not regex)
4. Precedence: deny > ask > allow

### Hooks Not Running

**Check:**
1. `disableAllHooks` is not `true`
2. Hook configuration is valid
3. Script has execute permissions
4. Restart Codex
5. Use `/hooks` to verify loaded

### Sandbox Issues

**Check:**
1. macOS/Linux only (not Windows)
2. Docker/Podman installed
3. Permissions for Docker socket
4. Check `excludedCommands` for needed tools

## Best Practices

### DO:
✅ Use project settings for team configuration
✅ Use local settings for personal overrides
✅ Validate JSON syntax before committing
✅ Document why rules exist (comments via tools)
✅ Test settings before sharing with team
✅ Use specific permission rules
✅ Set appropriate timeouts for hooks
✅ Use `$CLAUDE_PROJECT_DIR` in hooks

### DON'T:
❌ Commit sensitive data to project settings
❌ Use `bypassPermissions` mode in shared config
❌ Make permission rules too broad
❌ Forget to restart after changes
❌ Use hardcoded paths in hooks
❌ Disable all hooks globally without reason
❌ Override enterprise managed settings (you can't)

## Sensitive Files

### Exclude from Codex

```json
{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./.envrc)",
      "Read(./secrets/**)",
      "Read(./.aws/**)",
      "Read(./config/credentials.json)",
      "Read(./config/production.json)",
      "Read(./.ssh/**)",
      "Read(./build/**)",
      "Read(./dist/**)",
      "Read(./node_modules/**)"
    ]
  }
}
```

## Settings Merging

Settings from different levels are merged:

**Example:**

User settings:
```json
{
  "permissions": {
    "allow": ["Read(~/.gitconfig)"]
  }
}
```

Project settings:
```json
{
  "permissions": {
    "deny": ["Read(./.env)"]
  }
}
```

**Merged result:**
```json
{
  "permissions": {
    "allow": ["Read(~/.gitconfig)"],
    "deny": ["Read(./.env)"]
  }
}
```

Arrays are concatenated, objects are merged.

## Interactive Configuration

Offer to create/update settings:

```
I can help you configure this. Would you like me to:

1. Create a new settings.json file
2. Update existing settings.json
3. Show you what to add manually

Where should I make these changes?
- User settings (~/.Codex/settings.json)
- Project settings (.Codex/settings.json)
- Local settings (.Codex/settings.local.json)
```

## Resources

- **Official Settings Docs:** `.Codex/skills/ai/Codex/docs/code_claude_com/docs_en_settings.md`
- **Hooks Reference:** `.Codex/skills/ai/Codex/docs/code_claude_com/docs_en_hooks.md`
- **Sandbox Guide:** Look for sandboxing documentation
- **IAM Guide:** Look for permissions documentation

.agents/skills/anthropic/claude-skill-builder/SKILL.mdskill

Show content (7094 bytes)

---
name: Codex-skill-builder
description: Interactive skill creator for Codex and Agent Skills ecosystem. Build SKILL.md files with proper frontmatter, triggers, and structure. Triggers on creating skills, building skills, skill templates, skill frontmatter, allowed-tools, npx add-skill, agent skills.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
license: MIT
metadata:
  author: raintree
  version: "1.0"
---

# Codex Skill Builder

Create well-structured skills compatible with Codex and the Agent Skills specification (used by `npx add-skill`).

## When to Use

- User wants to create a new skill
- User needs help with skill structure or frontmatter
- User asks about trigger keywords or descriptions
- User wants to publish skills for `npx add-skill`

## Skill Structure

### Minimal Skill (Single File)

```
skill-name/
└── SKILL.md
```

### Full Skill (With References)

```
skill-name/
├── SKILL.md           # Main skill file (required)
├── references/        # Additional documentation
│   └── api-guide.md
├── scripts/           # Helper scripts
│   └── helper.py
└── assets/            # Templates, examples
    └── template.txt
```

## SKILL.md Template

```markdown
---
name: my-skill-name
description: Clear description of what this skill does. Include trigger keywords like keyword1, keyword2, keyword3 so the agent knows when to activate this skill.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
license: MIT
metadata:
  author: your-name
  version: "1.0"
---

# Skill Title

## Purpose
Brief explanation of what this skill provides.

## When to Use
- Scenario 1 (include keywords)
- Scenario 2 (include keywords)
- Scenario 3 (include keywords)

## Process

### 1. Understand the Request
How to analyze what the user needs.

### 2. Gather Context
What information to collect.

### 3. Provide Solution
Step-by-step approach.

## Examples

### Example 1: Basic Usage
**Request:** "Help me with X"
**Response:** [How skill handles it]

## Best Practices
- Practice 1
- Practice 2

## Common Pitfalls
- Avoid X, do Y instead
```

## Frontmatter Reference

### Required Fields

| Field | Description | Example |
|-------|-------------|---------|
| `name` | Lowercase with hyphens, max 64 chars | `nextjs-expert` |
| `description` | What + When + Keywords, max 1024 chars | See below |

### Optional Fields

| Field | Description | Values |
|-------|-------------|--------|
| `allowed-tools` | Tools skill can use | `Read, Write, Edit, Grep, Glob, Bash` |
| `model` | AI model preference | `haiku`, `sonnet`, `opus` |
| `license` | License type | `MIT`, `Apache-2.0` |
| `metadata.author` | Skill author | Your name |
| `metadata.version` | Semantic version | `"1.0"` |

### Writing Effective Descriptions

**Good description (includes what, when, keywords):**
```yaml
description: Expert in Next.js App Router, server components, and React Server Components. Use when user mentions Next.js, RSC, App Router, server actions, or React server-side patterns.
```

**Bad description (too vague):**
```yaml
description: Helps with Next.js
```

## Skill Types

### 1. Framework/API Expert
**Purpose:** Deep knowledge of specific technology
**Triggers:** Framework name, features, patterns
**Tools:** `Read, Grep, Glob`

```yaml
name: fastapi-expert
description: FastAPI web framework expert covering routing, dependencies, Pydantic models, async endpoints, and OpenAPI generation. Triggers on FastAPI, Python API, Pydantic, async web.
```

### 2. Code Generator
**Purpose:** Create boilerplate or scaffolding
**Triggers:** "generate", "create", "scaffold"
**Tools:** `Write, Read, Grep, Glob`

```yaml
name: component-generator
description: Generate React components with TypeScript, tests, and stories. Triggers on generate component, create component, scaffold component.
```

### 3. Code Analyzer
**Purpose:** Review and analyze code
**Triggers:** "review", "analyze", "audit"
**Tools:** `Read, Grep, Glob`

```yaml
name: security-auditor
description: Security code review for common vulnerabilities including XSS, SQL injection, and OWASP Top 10. Triggers on security review, audit code, find vulnerabilities.
```

### 4. Workflow Automator
**Purpose:** Automate development tasks
**Triggers:** Task-specific keywords
**Tools:** `Read, Write, Edit, Bash`

```yaml
name: release-helper
description: Automate release workflows including changelog generation, version bumping, and git tagging. Triggers on release, changelog, version bump, tag release.
```

### 5. Data Processor
**Purpose:** Transform or analyze data
**Triggers:** Format names, transformation keywords
**Tools:** `Read, Write, Edit, Grep`

```yaml
name: csv-processor
description: Parse, transform, and analyze CSV files. Convert between CSV, JSON, and other formats. Triggers on CSV, parse CSV, convert CSV.
```

## Publishing for npx add-skill

Skills following this format work with `npx add-skill` from any Git repository.

### Repository Structure

```
your-repo/
├── skills/
│   ├── skill-one/
│   │   └── SKILL.md
│   └── skill-two/
│       └── SKILL.md
└── README.md
```

### Installation Commands

```bash
# Users install from your repo
npx add-skill your-username/your-repo

# List available skills
npx add-skill your-username/your-repo --list

# Install specific skill
npx add-skill your-username/your-repo --skill my-skill

# Direct link to skill
npx add-skill https://github.com/user/repo/tree/main/skills/my-skill
```

### Installation Locations

| Scope | Path | Use Case |
|-------|------|----------|
| Personal | `~/.Codex/skills/` | Your own tools |
| Project | `.Codex/skills/` | Team-shared skills |

## Interactive Skill Creation

When helping users create skills, gather:

1. **Skill name** - lowercase-with-hyphens
2. **What it does** - 1-2 sentence description
3. **When to activate** - trigger keywords
4. **Tools needed** - Read, Write, Edit, Grep, Glob, Bash
5. **Scope** - personal or project

Then generate the SKILL.md with proper structure.

## Validation Checklist

Before publishing:

- [ ] Name is lowercase with hyphens only
- [ ] Description includes trigger keywords
- [ ] Description explains both WHAT and WHEN
- [ ] SKILL.md filename is uppercase
- [ ] YAML frontmatter is valid (no tabs)
- [ ] Only necessary tools are requested
- [ ] Examples are included
- [ ] Under 500 lines (move details to references/)

## Troubleshooting

### Skill Not Activating

1. Check description has specific keywords
2. Verify file is named `SKILL.md` (uppercase)
3. Confirm path: `~/.Codex/skills/name/SKILL.md` or `.Codex/skills/name/SKILL.md`
4. Validate YAML syntax (no tabs, proper indentation)
5. Restart Codex

### Skill Conflicts

Multiple skills with similar triggers:
- Make descriptions more specific
- Use distinct keywords
- Consider combining into one skill

## Resources

- **Agent Skills Spec:** https://agentskills.io
- **Codex Docs:** https://docs.anthropic.com/en/docs/Codex
- **npx add-skill:** https://github.com/vercel-labs/add-skill

.claude-plugin/marketplace.jsonmarketplace

Show content (3636 bytes)

{
  "name": "claude-starter-complete",
  "version": "2.0.0",
  "description": "Complete collection of 40+ production-ready skills including Stripe, Supabase, Expo, Plaid, Aptos, and more. Plus meta-commands, orchestration, and workflows.",
  "owner": {
    "name": "Raintree Technology",
    "url": "https://github.com/raintree-technology"
  },
  "repository": "https://github.com/raintree-technology/claude-starter",
  "plugins": [
    {
      "name": "ai-skills",
      "source": "./templates/.claude/skills/anthropic",
      "description": "Claude Code expertise: skills, commands, hooks, MCP, settings (7 skills)",
      "category": "ai"
    },
    {
      "name": "stripe-payments",
      "source": "./templates/.claude/skills/stripe",
      "description": "Complete Stripe API integration (payments, subscriptions, webhooks)",
      "category": "api"
    },
    {
      "name": "supabase-backend",
      "source": "./templates/.claude/skills/supabase",
      "description": "Supabase backend (PostgreSQL, Auth, Storage, Edge Functions)",
      "category": "backend"
    },
    {
      "name": "plaid-banking",
      "source": "./templates/.claude/skills/plaid",
      "description": "Plaid banking API (Auth, Transactions, Identity, Accounts - 5 skills)",
      "category": "api"
    },
    {
      "name": "expo-mobile",
      "source": "./templates/.claude/skills/expo",
      "description": "Expo/React Native mobile development (EAS Build, Update, Router - 4 skills)",
      "category": "mobile"
    },
    {
      "name": "aptos-blockchain",
      "source": "./templates/.claude/skills/aptos",
      "description": "Aptos blockchain development (Move language, Shelby Protocol, Decibel - 17 skills)",
      "category": "blockchain"
    },
    {
      "name": "shopify-ecommerce",
      "source": "./templates/.claude/skills/shopify",
      "description": "Shopify e-commerce platform integration",
      "category": "ecommerce"
    },
    {
      "name": "whop-platform",
      "source": "./templates/.claude/skills/whop",
      "description": "Whop digital products and memberships platform",
      "category": "ecommerce"
    },
    {
      "name": "ios-development",
      "source": "./templates/.claude/skills/ios",
      "description": "iOS/Swift development",
      "category": "mobile"
    },
    {
      "name": "toon-formatter",
      "source": "./templates/.claude/skills/toon-formatter",
      "description": "TOON format for 30-60% token savings on tabular data",
      "category": "optimization"
    },
    {
      "name": "meta-commands",
      "source": "./templates/.claude/commands/meta",
      "description": "Meta-commands for creating custom commands from templates",
      "category": "automation"
    },
    {
      "name": "debug-tools",
      "source": "./templates/.claude/commands/debug",
      "description": "Debugging tools (skill-graph, explain-ranking, workflow-debug, command-validate)",
      "category": "development"
    },
    {
      "name": "workflows",
      "source": "./templates/.claude/workflows",
      "description": "YAML workflow automation (production-release, ci-pipeline, daily-maintenance, hotfix)",
      "category": "automation"
    },
    {
      "name": "orchestration",
      "source": "./templates/.claude/orchestration",
      "description": "Skill orchestration engine for multi-skill collaboration",
      "category": "automation"
    }
  ],
  "keywords": [
    "stripe",
    "supabase",
    "plaid",
    "expo",
    "aptos",
    "blockchain",
    "payments",
    "backend",
    "mobile",
    "workflows",
    "orchestration",
    "meta-commands",
    "toon"
  ]
}

README

claude-starter

An opinionated Claude Code skill pack for fintech devs and Anthropic power-users. Six deep, handwritten skills plus a thin CLI for TOON — a JSON compression format that typically cuts input tokens 40–60% on tabular data.

No orchestration framework. No aspirational YAML. Just skills that activate when you need them.

What you get

6 top-level skills — auto-activate on keywords:

Skill	Covers
stripe	Checkout, Payment Intents, subscriptions, Connect/marketplace, Terminal, Radar, Treasury, Issuing, webhooks (signature + idempotency) — 2,100+ lines of real patterns
supabase	Postgres + RLS, Auth (OAuth + SSR cookies), Realtime, Storage, Edge Functions, pgvector
plaid	Link flow, Auth (ACH routing/account numbers), Transactions sync, Identity (KYC), Accounts + balance
expo	EAS Build (`eas.json`, credentials, CI), EAS Update (OTA, channels, staged rollouts), Expo Router (file-based routing, dynamic segments, layout groups)
anthropic	Anthropic Claude API — Messages API, prompt caching, tool use, vision, model migration. Includes 6 Claude Code meta-tooling sub-skills: skill-builder, command-builder, hook-builder, mcp-expert, settings-expert, claude-code
toon-formatter	When TOON helps, when it doesn't, how to wire the commands

5 slash commands for TOON:

/convert-to-toon <file> — encode + report measured savings
/analyze-tokens <file> — compare JSON vs TOON token counts without writing a file
/toon-encode <file>, /toon-decode <file>, /toon-validate <file>

All TOON commands shell out to the canonical @toon-format/toon npm library via a 90-line wrapper at .claude/utils/toon/cli.mjs, and use gpt-tokenizer for real token counts (OpenAI BPE — directionally accurate proxy for Claude; for exact counts use Anthropic's /v1/messages/count_tokens endpoint).

Install

# Into current project
npx create-claude-starter@latest

# Into a specific dir, no prompts
npx create-claude-starter@latest ./my-app --yes

For TOON commands, add the runtime deps to your project:

npm i @toon-format/toon gpt-tokenizer

Use

Skills auto-activate on context:

User: How do I verify a Stripe webhook signature?
Claude: [stripe-expert activates] Use stripe.webhooks.constructEvent...

User: Convert api-response.json to TOON
Claude: [runs /convert-to-toon api-response.json]
  ✓ Wrote api-response.toon
  Tokenizer: gpt-tokenizer (OpenAI BPE — approximate proxy for Claude)
  JSON:      4,587 tokens (12,840 bytes)
  TOON:      2,759 tokens (7,128 bytes)
  Saved:     1,828 tokens (39.8%)

Why this exists

The Claude Code skill market is fragmented: Anthropic ships 17 general-purpose skills and nothing for fintech or platform integrations. Community mega-packs (awesome-claude-code-toolkit, antigravity-awesome-skills) compete on volume — 1,400+ skills with razor-thin depth.

This pack goes the other way: 6 skills, hand-maintained, each genuinely better than what's out there. The Stripe skill alone is 2,100+ lines of tested integration patterns. If you're building a fintech app or extending Claude itself, this is the starting point.

Not in this repo (and why)

Orchestration / semantic matching / multi-skill workflows — removed. Claude Code selects skills natively via frontmatter description; the previous TypeScript orchestration engine was placeholder code.
YAML workflow engine — removed. Out of scope for a skill pack.
Meta-commands / command registry / validators — removed. Claude Code's built-in /skill and plugin system handle this.
Native Zig TOON binary — removed. The canonical @toon-format/toon npm package (1.8M downloads/month) ships pure JS, cross-platform.
Blockchain / iOS / Shopify / Whop skills — removed. Niche or thin; if you need them, spin a focused pack.
Duplicated code-quality skills — removed. Anthropic already ships cleanup-unused, cleanup-slop, etc. natively.

Structure

.claude/
├── skills/
│   ├── stripe/        # 2,100+ lines
│   ├── supabase/
│   ├── plaid/         # consolidated: Link + Auth + Transactions + Identity + Accounts
│   ├── expo/          # consolidated: core + EAS Build + EAS Update + Expo Router
│   ├── anthropic/     # 1 main skill + 6 Claude Code meta-tooling sub-skills
│   └── toon-formatter/
├── commands/
│   ├── convert-to-toon.md
│   ├── analyze-tokens.md
│   ├── toon-{encode,decode,validate}.md
│   └── {discover,install}-skills.md
└── utils/toon/cli.mjs # 90-line wrapper around @toon-format/toon + gpt-tokenizer

Benchmarks

Real measured token counts for a handful of representative workloads are in bench/. Numbers use gpt-tokenizer, not a claimed heuristic.

Requirements

Node.js ≥ 18
Claude Code ≥ 1.0
(Optional) @toon-format/toon and gpt-tokenizer in your project for TOON commands

License

MIT. Not affiliated with Stripe, Supabase, Plaid, Expo, or Anthropic.