Candlekeep

Writing Trigger Keywords (launch book-writer)

• Creation words: "write", "create", "author", "draft", "compose", "start writing"
• Book words: "book", "chapter", "section", "document", "manuscript"
• Editing words: "edit", "update", "revise", "modify", "change", "rewrite"
• Structure words: "add chapter", "new section", "reorganize", "restructure"

Marketplace Trigger Keywords (run ck marketplace browse directly)

• Browse words: "marketplace", "browse marketplace", "search marketplace", "browse books"
• Discovery words: "find books", "get books about", "discover books", "available books"
• Shopping words: "subscribe", "add from marketplace", "marketplace recommendations"

Research Trigger Patterns (launch item-reader)

• "What does X say about..."
• "Can you research..."
• "Look up Y in my documents"
• "Refer to my library for..."
• "Read about Z from my books"
• "Find information about..."
• "Check my documents for..."
• "According to my library..."
• "What do my books/PDFs/documents say about..."
• "Research X using my documents"
• "Is there anything in my library about..."
• "Consult my files about..."

Writing Trigger Patterns (launch book-writer)

• "Write a book about..."
• "Create a new document..."
• "Help me write..."
• "Add a chapter about..."
• "Edit my document..."
• "Update the chapter on..."
• "Start a new book..."
• "Draft a section about..."

When NOT to Trigger This Skill

Do not invoke CandleKeep when:

• The user is asking for web search or external research — not involving their personal library (e.g., "research the latest news on X")
• The user explicitly says they don't want CandleKeep (e.g., "don't check my library")
• Keywords like "read" or "write" refer to file I/O or code operations, not documents (e.g., "read the config file", "write a function")
• The request is about general knowledge the user doesn't expect to be in their library
• The user is asking Claude to search the web, use a search engine, or fetch a URL

Auto-Trigger Scenarios

Launch item-reader when:

1. User asks a factual question that could be in their documents
2. User mentions needing to "research", "read", or "refer" to something
3. User asks "what do my documents say about..."
4. User wants to "look up" or "find" information
5. User asks a question and has CandleKeep documents available
6. User mentions their "library", "books", "PDFs", or "documents" in a research context

Launch book-writer when:

1. User wants to "write", "create", or "author" a document
2. User mentions "book", "chapter", "section" in a writing context
3. User wants to "edit", "update", or "revise" document content
4. User asks to "add", "draft", or "compose" new content

CRITICAL: MANDATORY SUBAGENT USAGE

When answering questions that might be in the user's document library:

1. ALWAYS launch the item-reader subagent using the Task tool
2. NEVER run ck items read commands directly for research questions
3. The subagent handles the full research workflow with proper citations
4. ALSO launch the book-enricher subagent in parallel to opportunistically improve library metadata

Parallel Agent Launch

For research requests, spawn BOTH agents simultaneously in a single message:

Task tool calls (in parallel):
1. subagent_type: "candlekeep-cloud:item-reader"
   prompt: "Research the user's question: [question here]
   RESEARCH_INTENT: [insert the user's exact question here]"

2. subagent_type: "candlekeep-cloud:book-enricher"
   prompt: "Enrich any books in the library that need metadata improvements.
   IMPORTANT: Use --no-session on ALL ck commands to avoid interfering with any active research sessions."

The item-reader agent handles the user's research request while book-enricher opportunistically improves 1-2 books' metadata in the background.

Decision Tree

User request
    │
    ├── Contains RESEARCH keywords (research, read, refer, look up, find)
    │   └── Launch item-reader subagent (Task tool) - AUTOMATIC
    │
    ├── Contains WRITING keywords (write, create, edit, update, chapter, book)
    │   └── Launch book-writer subagent (Task tool) - AUTOMATIC
    │
    ├── Question that might be answered by documents
    │   └── Launch item-reader subagent (Task tool) - AUTOMATIC
    │
    ├── Contains MARKETPLACE keywords (marketplace, browse, find books, subscribe)
    │   └── Run: ck marketplace browse --search "<query>" --json
    │       └── Present results with subscribe commands
    │
    ├── Contains PLANNING keywords (plan, design, architect, strategy, how should I)
    │   └── Phase 1: Assess library (ck items list --json)
    │       └── Dispatch item-reader in background + continue planning
    │
    ├── "What documents do I have?" / "List my library"
    │   └── Run: ck items list
    │
    ├── "Add this PDF/markdown file to my library"
    │   └── Run: ck items add <path>
    │
    ├── "Remove document X"
    │   └── Run: ck items remove <id> --yes
    │
    └── "Check my CandleKeep auth status"
        └── Run: ck auth whoami

Launching Agents

For Research Questions

When RESEARCH trigger keywords or patterns are detected, launch the research agents:

Task tool calls (in a single message with multiple tool uses):

1. subagent_type: "candlekeep-cloud:item-reader"
   prompt: "Research the user's question: [question here]
   RESEARCH_INTENT: [insert the user's exact question here]"

2. subagent_type: "candlekeep-cloud:book-enricher"
   prompt: "Enrich any books in the library that need metadata improvements.
   IMPORTANT: Use --no-session on ALL ck commands to avoid interfering with any active research sessions."

DO NOT HESITATE - if the user's request contains research-related keywords, launch both subagents.

For Writing/Editing Tasks

When WRITING trigger keywords or patterns are detected, launch the book-writer agent:

Task tool call:

subagent_type: "candlekeep-cloud:book-writer"