Issue 05 | /caveman Core Skill — Powerful Compression Tool for Daily Development

🎯 Learning Objectives

Upon completing this issue, you will master:

1. Caveman's main Skill file structure and loading mechanism
2. 5 ways to trigger Caveman on different platforms
3. The core syntax of Caveman's answer pattern: [thing] [action] [reason]. [next step].
4. Three practical exercises for daily development scenarios

📖 Core Content

5.1 Skill File Structure

Caveman's core Skill is located in the repository's skills/caveman/ directory. As a Claude Code Skill, it is essentially a Markdown file (SKILL.md) containing complete behavioral instructions.

caveman/
├── skills/
│   ├── caveman/           ← Main Skill
│   │   └── SKILL.md       ← Core Rule Definition
│   ├── caveman-commit/    ← Git Commit Skill
│   │   └── SKILL.md
│   ├── caveman-review/    ← Code Review Skill
│   │   └── SKILL.md
│   ├── caveman-help/      ← Help Info Skill
│   │   └── SKILL.md
│   └── compress/          ← Compression Skill
│       └── SKILL.md
├── hooks/                 ← Hook Scripts
├── commands/              ← Command Definitions
└── plugins/caveman/       ← Plugin Packaging

When you type /caveman, the Agent loads the rules from SKILL.md and immediately applies them to the current session.

5.2 Caveman Core Instructions

The following core behavioral rules are defined in SKILL.md (simplified version):

## Caveman Communication Rules

1. **Terse like caveman** — Technical substance exact. Only fluff die.
2. **Drop** — articles, filler (just/really/basically), pleasantries, hedging
3. **Fragments OK** — Complete sentences not required
4. **Short synonyms** — Use shortest word that conveys same meaning
5. **Code unchanged** — Never compress code blocks, commands, or file paths
6. **Pattern** — [thing] [action] [reason]. [next step].
7. **Persistence** — ACTIVE EVERY RESPONSE. No revert after many turns.
8. **Exit** — "stop caveman" or "normal mode" to deactivate

💡 Important: Rule 5 is key to Caveman not compromising technical accuracy—all code, commands, and file paths remain unchanged; only natural language descriptions are compressed.

5.3 Five Trigger Methods

graph TD
    A["How to trigger Caveman?"]
    
    A --> B["Slash Command
/caveman"]
    A --> C["Natural Language
'talk like caveman'"]
    A --> D["Keyword
'caveman mode'"]
    A --> E["Request Brevity
'less tokens please'"]
    A --> F["Auto-activation
SessionStart Hook"]
    
    B -->|"Claude Code / Gemini CLI"| G["✅ Immediate Effect"]
    C -->|"All Platforms"| G
    D -->|"All Platforms"| G
    E -->|"All Platforms"| G
    F -->|"Claude Code Exclusive"| G

💡 Codex Special Syntax: Codex uses $caveman instead of /caveman. The / slash is reserved for built-in commands in Codex.

💡 OpenCode Configuration: Add the Caveman always-on snippet in .config/opencode/AGENTS.md.

5.4 Answer Pattern Analysis

Caveman's answers follow a fixed pattern:

[thing] [action] [reason]. [next step].

Decomposition example:

Original Question: "Why did my Docker container exit immediately after starting?"

Caveman Answer:
"Container exit immediately.     ← [thing] [action]
 No foreground process.          ← [reason]
 Add CMD or ENTRYPOINT            ← [next step]
 that stays alive (e.g. tail -f /dev/null for debug)."

More pattern examples:

# Bug Diagnosis Pattern
[Component/Module] [What went wrong]. [Root cause]. [Fix].

# Concept Explanation Pattern
[Concept] = [One-sentence definition]. [Core mechanism]. [Example].

# Code Suggestion Pattern
[Problem]. [Solution]. [Code].

💻 Three Practical Scenarios

Scenario 1: Node.js Memory Leak Debugging

Your Question:

My Node.js Express server's memory increased from 100MB to 2GB after running for 48 hours. How do I troubleshoot this?

🗣️ Normal Claude Answer (~180 tokens):

This sounds like a classic memory leak issue in a Node.js application. 
Here are several approaches you can use to diagnose the problem:

1. First, I'd recommend using the built-in Node.js inspector with the 
   --inspect flag...
2. You could also try using the heapdump module to take heap snapshots...
3. Another useful tool is clinic.js which provides...
4. Make sure to check for common patterns that cause leaks...
   ...(continues with detailed explanations for each step)

🪨 Caveman Answer (~45 tokens):

Classic leak pattern. Debug steps:

1. `node --inspect server.js` → Chrome DevTools → Memory tab
2. Heap snapshot at start, snapshot at +2h, compare
3. Look for: growing arrays, unclosed event listeners, global caches

Common Express culprits:
- `app.use()` middleware storing req refs
- Session store without TTL
- Socket.io connections not cleaned on disconnect

Quick win: `process.memoryUsage()` logged every 5min → find growth rate.

Note: Code commands and technical terms are fully preserved; only narrative fluff is removed.

Scenario 2: TypeScript Generics Explanation

Your Question:

Explain Conditional Types in TypeScript

🪨 Caveman Answer:

Conditional Types = type-level ternary expression.

Syntax: `T extends U ? X : Y`

Practical example:
```typescript
type IsString<T> = T extends string ? "yes" : "no";

type A = IsString<"hello">;  // "yes"
type B = IsString<42>;       // "no"

Distributive behavior: union automatically expands.

type ToArray<T> = T extends any ? T[] : never;
type R = ToArray<string | number>;  // string[] | number[]

Built-in conditional types: Exclude<T,U>, Extract<T,U>, NonNullable<T>, ReturnType<T>.

### Scenario 3: Code Refactoring Suggestions

**Your Question:**

This function is too long, help me refactor it: function processOrder(order) { // Validate order... (20 lines) // Calculate price... (30 lines)
// Send notification... (15 lines) // Update database... (25 lines) }

**🪨 Caveman Answer:**

Split into 4 single-responsibility functions:

async function processOrder(order: Order): Promise<Result> {
  const validated = validateOrder(order);       // Validate
  const priced = calculatePrice(validated);     // Price
  await persistOrder(priced);                   // Persist
  await notifyStakeholders(priced);             // Notify
  return { success: true, orderId: priced.id };
}

Principle: Each function ≤ 20 lines, single responsibility, independently testable. Error handling: Each function throws independently, processOrder top-level try/catch.

---

## 📊 Five Platform Skill Loading Comparison

| Feature | Claude Code | Antigravity | Gemini CLI | Codex | OpenCode |
|---------|-------------|-------------|------------|-------|----------|
| **Skill File Location** | `.claude-plugin/` | `.agent/skills/` | Extension Directory | `.codex/` | `.config/opencode/` |
| **Loading Method** | Plugin + Hook | GEMINI.md Reference | Extension Auto | Plugin Marketplace | AGENTS.md Rules |
| **Slash Command** | `/caveman` | ❌ | `/caveman` | `$caveman` | ❌ |
| **Mode Switching** | `/caveman ultra` | Natural Language | `/caveman ultra` | `$caveman ultra` | Natural Language |
| **Always-on** | ✅ Hook Auto | ⚠️ Requires config | ✅ Auto | ⚠️ Requires hooks.json | ⚠️ Requires AGENTS.md |
| **Skill Hot Reload** | ✅ | ✅ | ✅ | ✅ | ✅ |

---

## 📝 Key Takeaways

1.  The Caveman main Skill is essentially a **SKILL.md** file, defining 8 core behavioral rules.
2.  **Code blocks, commands, and paths are never compressed**—this is a strict rule to ensure technical accuracy.
3.  The answer pattern follows the fixed structure: `[thing] [action] [reason]. [next step].`
4.  Among the 5 trigger methods, **natural language** is universally applicable across all platforms.
5.  Codex uses the `$caveman` syntax, and OpenCode requires configuration in AGENTS.md.

---

## 🔗 References

- [Caveman Skills Directory](https://github.com/JuliusBrussee/caveman/tree/main/skills)
- [Claude Code Skills Documentation](https://docs.anthropic.com/en/docs/claude-code/skills)
- [Codex Hooks Configuration](https://github.com/JuliusBrussee/caveman/tree/main/.codex)