Knowledge Skill

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Find and retrieve knowledge from past work.

Execution Steps

Given /knowledge <query>:

Step 1: Search with ao CLI (if available)

ao search "<query>" --limit 10 2>/dev/null

If results found, read the relevant files.

Step 2: Search .agents/ Directory

# Search learnings
grep -r "<query>" .agents/learnings/ 2>/dev/null | head -10

# Search patterns
grep -r "<query>" .agents/patterns/ 2>/dev/null | head -10

# Search research
grep -r "<query>" .agents/research/ 2>/dev/null | head -10

# Search retros
grep -r "<query>" .agents/retros/ 2>/dev/null | head -10

Step 3: Search Plans

# Local plans
grep -r "<query>" .agents/plans/ 2>/dev/null | head -10

# Global plans
grep -r "<query>" ~/.claude/plans/ 2>/dev/null | head -10

Step 3.5: Search Global Patterns

# Global patterns (cross-repo knowledge)
grep -r "<query>" ~/.claude/patterns/ 2>/dev/null | head -10

Global patterns contain knowledge promoted from any repository via /learn --global. These are high-confidence, cross-project learnings.

Step 3.6: Search Global Learnings

# Global learnings (cross-repo abstracted knowledge)
grep -r "<query>" ~/.agents/learnings/ 2>/dev/null | head -10

Global learnings are abstracted, transferable insights promoted from repo-specific learnings via /learn --promote or classified as cross-cutting by /retro.

Step 3.7: Search Global Patterns (new location)

# Global patterns (new location, cross-repo)
grep -r "<query>" ~/.agents/patterns/ 2>/dev/null | head -10

Step 4: Use Semantic Search (if MCP available)

Tool: mcp__smart-connections-work__lookup
Parameters:
  query: "<query>"
  limit: 10

Step 5: Read Relevant Files

For each match found, use the Read tool to get full content.

Step 6: Synthesize Results

Combine findings into a coherent response:

• What do we know about this topic?
• What learnings are relevant?
• What patterns apply?
• What past decisions were made?

Step 7: Report to User

Present the knowledge found:

1. Summary of findings
2. Key learnings (with IDs)
3. Relevant patterns
4. Links to source files
5. Confidence level (how much we know)

Knowledge Locations

Key Rules

• Search multiple locations - knowledge may be scattered
• Use ao CLI first - semantic search is better
• Fall back to grep - if ao not available
• Read full files - don't just report matches
• Synthesize - combine findings into useful answer

Example Queries

/knowledge authentication    # Find auth-related learnings
/knowledge "rate limiting"   # Find rate limit patterns
/knowledge kubernetes        # Find K8s knowledge
/knowledge "what do we know about caching"

Examples

Finding Past Learnings

User says: /knowledge "error handling patterns"

What happens:

1. Agent tries ao search "error handling patterns", finds 3 matches
2. Agent searches .agents/learnings/ with grep, finds 5 additional matches
3. Agent searches .agents/patterns/ for related patterns, finds 2 matches
4. Agent reads all matched files using Read tool
5. Agent synthesizes findings into coherent response
6. Agent reports: "We have 5 learnings about error handling: L1 (always wrap errors), L3 (use typed errors), L12 (log before returning), L15 (context propagation), L22 (retry with backoff)"
7. Agent provides links to source files and confidence level: high (multiple confirmations)

Result: Complete knowledge synthesis with 5 specific learnings and 2 related patterns, all with source citations.

Querying Without ao CLI

User says: /knowledge "database migrations"

What happens:

1. Agent tries ao search, command not found
2. Agent falls back to grep search across .agents/ directories
3. Agent finds 2 matches in learnings, 1 in research, 0 in patterns
4. Agent reads matched files
5. Agent synthesizes: "Limited knowledge found. L8 recommends using transaction-wrapped migrations. Research doc from 2026-01-20 analyzed migration tools."
6. Agent reports medium confidence (only 2 sources)

Result: Knowledge found despite missing ao CLI, with appropriate confidence level based on source count.

Troubleshooting