# CSO Guide - Claude Search Optimization

Treat the examples below as editorial heuristics, not controlled evidence of model behavior. Include both what the skill does and when to use it. Discovery, metadata injection, context costs, naming preferences, and @ syntax depend on the host; test the actual integration.

Advanced techniques for making skills discoverable by agents.

## The Discovery Problem

You have 100+ skills. Agent receives a task. How does it find the RIGHT skill?

**Answer**: The `description` field.

## Describe the capability and use conditions

### The Trap

When description summarizes workflow, agents take a shortcut.

**Real example that failed**:

```yaml
# Agent did ONE review instead of TWO
description: Code review between tasks

# Skill body had flowchart showing TWO reviews:
# 1. Spec compliance
# 2. Code quality
```

**Why it failed**: Agent read description, thought "code review between tasks means one review", never read the flowchart.

**Fix**:

```yaml
# Agent now reads full skill and follows flowchart
description: Use when executing implementation plans with independent tasks
```

### The Pattern

```yaml
# ❌ BAD: Workflow summary
description: Analyzes git diff, generates commit message in conventional format

# ✅ GOOD: Trigger conditions only
description: Use when generating commit messages or reviewing staged changes
```

## Token Efficiency Critical for Skills

**Problem**: Frequently-loaded skills consume tokens in EVERY conversation.

**Target word counts**:

- Frequently-loaded skills: <200 words total
- Other skills: <500 words

### Techniques

**1. Move details to tool help**:

```bash
# ❌ BAD: Document all flags in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# ✅ GOOD: Reference --help
search-conversations supports multiple modes. Run --help for details.
```

**2. Use cross-references**:

```markdown
# ❌ BAD: Repeat workflow

When searching, dispatch agent with template...
[20 lines of repeated instructions]

# ✅ GOOD: Reference other skill

Use subagents for searches. See [delegating-to-subagents] for workflow.
```

**3. Compress examples**:

```markdown
# ❌ BAD: Verbose (42 words)

Partner: "How did we handle auth errors in React Router?"
You: I'll search past conversations for patterns.
[Dispatch subagent with query: "React Router authentication error handling 401"]

# ✅ GOOD: Minimal (20 words)

Partner: "Auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]
```

## Keyword Strategy

### Error Messages

Include EXACT error text users will see:

- "Hook timed out after 5000ms"
- "ENOTEMPTY: directory not empty"
- "jest --watch is not responding"

### Symptoms

Use words users naturally say:

- "flaky", "hangs", "zombie process"
- "slow", "timeout", "race condition"
- "cleanup failed", "pollution"

### Tools & Commands

Actual names, not descriptions:

- "pytest", not "Python testing"
- "git rebase", not "rebasing"
- ".docx files", not "Word documents"

### Synonyms

Cover multiple ways to describe same thing:

- timeout/hang/freeze
- cleanup/teardown/after Each
- mock/stub/fake

## Naming Conventions

### Gerunds (-ing) for Processes

✅ `creating-skills`, `debugging-with-logs`, `testing-async-code`

### Verb-first for Actions

✅ `flatten-with-flags`, `reduce-complexity`, `trace-root-cause`

### ❌ Avoid

- `skill-creation` (passive, less searchable)
- `async-test-helpers` (too generic)
- `debugging-techniques` (vague)

## Description Template

```yaml
description: "Use when [SPECIFIC TRIGGER]."
metadata:
  triggers: [error1], [symptom2], [tool3]
```

**Examples**:

```yaml
# Technique skill
description: "Use when tests have race conditions, timing dependencies, or pass/fail inconsistently."
metadata:
  triggers: flaky tests, timeout, race condition

# Pattern skill
description: "Use when complex data structures make code hard to follow."
metadata:
  triggers: nested loops, multiple flags, confusing state

# Reference skill
description: "Use when working with React Router and authentication."
metadata:
  triggers: 401 redirect, login flow, protected routes

# Discipline skill
description: "Use when implementing any feature or bugfix, before writing implementation code."
metadata:
  triggers: new feature, bug fix, code change
```

## Third Person Rule

Metadata loading depends on the host. Keep descriptions clear and consistent; no wording guarantees discovery.

```yaml
# ❌ BAD: First person
description: "I can help you with async tests"

# ❌ BAD: Second person
description: "You can use this for race conditions"

# ✅ GOOD: Third person
description: "Handles async tests with race conditions"
```

## Cross-Referencing Other Skills

**When documenting a skill that references other skills**:

Use skill name only, with explicit requirement markers:

```markdown
# ✅ GOOD: Clear requirement

**REQUIRED BACKGROUND**: You MUST understand test-driven-development before using this skill.

**REQUIRED SUB-SKILL**: Use defensive-programming for error handling.

# ❌ BAD: Unclear if required

See test-driven-development skill for context.

# ❌ NEVER: Force-loads (burns context)

@skills/testing/test-driven-development/SKILL.md
```

**Why prefer Markdown links**: `@` interpretation depends on the host and may eagerly load files. Markdown links are more portable.

## Verification Checklist

Before deploying:

- [ ] Description starts with "Use when..."?
- [ ] Description is <500 characters?
- [ ] Description states the capability and specific use conditions without replacing the full workflow?
- [ ] Includes 3+ keywords (errors/symptoms/tools)?
- [ ] Third person throughout?
- [ ] Name uses gerund or verb-first format?
- [ ] Name has only letters, numbers, hyphens?
- [ ] No @ syntax for cross-references?
- [ ] Word count <200 (frequent) or <500 (other)?

## Real-World Examples

### Before/After: TDD Skill

❌ **Before** (workflow in description):

```yaml
description: Write test first, watch it fail, write minimal code, refactor
```

Result: Agents followed description, skipped reading full skill.

✅ **After** (triggers only):

```yaml
description: Use when implementing any feature or bugfix, before writing implementation code
```

Result: Agents read full skill, followed complete TDD cycle.

### Before/After: BigQuery Skill

❌ **Before** (too vague):

```yaml
description: Helps with database queries
```

Result: Never loaded (too generic, agents couldn't identify relevance).

✅ **After** (specific triggers):

```yaml
description: Use when analyzing BigQuery data. Triggers: revenue metrics, pipeline data, API usage, campaign attribution.
```

Result: Loads for relevant queries, includes domain keywords.