| name | librania-research |
| description | Mandatory first step for ANY research, investigation, explanation, planning, comparison, or lookup task in this project (per CLAUDE.md). Auto-searches LibraNia before web, saves findings back. Triggers broadly, not just on exact phrasing — covers: factual/conceptual questions ('what is X', 'why does X happen', 'how does X work'), explain/describe/clarify requests, comparisons ('X vs Y', 'difference between'), documentation/API/reference lookups, learning requests, meta/architecture questions about tools or concepts, investigation of behavior or root causes, and planning/decision questions that need background context. If the request is asking to understand or find out something rather than to write/edit/run code, this skill applies. |
LibraNia Research Workflow
Intelligent research that builds knowledge over time by searching LibraNia first, falling back to web when needed, and saving findings.
When to Use
Trigger this skill when user requests:
- Research questions: "What is X?", "How does Y work?", "Explain Z"
- Information gathering: "Find info about...", "Look up...", "Research..."
- Documentation: "Show me docs for...", "What's the API for..."
- Learning: "Teach me...", "I want to learn about..."
- Comparison: "Compare X vs Y", "What's the difference between..."
- Investigation/explanation: "Why does X happen/behave this way?", "Why doesn't X do Y?"
- Meta/conceptual questions: questions about tools, architecture, concepts, or terminology that aren't tied to editing this repo's code (e.g. "why does Claude behave differently from Codex here?", "what's the difference between a skill and a harness?")
- Any question phrased as a plain "why/what/how" without an explicit "research" verb — if the user wants to understand or find out something rather than have code written, this skill still applies
Do NOT use for:
- Code implementation (use normal workflow)
- File operations (use Read/Write tools)
- Debugging a failing test/bug in this repo's code (use systematic-debugging skill)
- Planning a multi-step implementation (use brainstorming/writing-plans skills) — but background research feeding into that plan still goes through this skill first
Workflow
Step 1: Search LibraNia First
Agent spawn with prompt:
"Search LibraNia knowledge base for: {query}
Use mcp__librania__search_notes tool with query: {query}
Evaluate results:
- If 3+ relevant notes with substantial content → sufficient, use as primary source
- If 1-2 notes with partial info → note what's missing, proceed to web search
- If 0 notes or irrelevant → proceed to web search
Return findings with note IDs and titles."
Step 2: Web Search (if needed)
If LibraNia insufficient:
Agent continues:
"LibraNia has partial/no info. Searching web for: {specific_gaps}
Use WebSearch tool to find:
- {gap_1}
- {gap_2}
- {gap_3}
Gather comprehensive information."
Step 3: Save to LibraNia
After web research:
Agent:
"Creating note in LibraNia with findings.
1. Search for related notes to link:
mcp__librania__search_notes for related topics
2. Create note:
mcp__librania__create_note with:
- title: Clear, descriptive (e.g., 'Docker Security Best Practices')
- body: Markdown with:
* Summary section
* Key points with sources
* [[Note Title]] links to related notes found in step 1
* Code examples if applicable
- tags: 3-5 relevant tags
3. Return note ID and title"
Step 4: Return Answer
Agent returns to main thread:
"Answer: {consolidated_answer}
Sources:
- LibraNia notes: {note_titles_with_ids}
- Web sources: {urls}
- New note created: {new_note_title} (ID: {note_id})"
Implementation
Agent Prompt Template
You are a research agent with access to LibraNia knowledge base.
Research query: {user_query}
Follow this workflow:
1. SEARCH LIBRANIA FIRST
- Use mcp__librania__search_notes("{query}")
- Evaluate: Do results answer the query sufficiently?
- If YES: Extract answer from notes, cite note IDs
- If NO/PARTIAL: Note what's missing, proceed to step 2
2. WEB SEARCH (if needed)
- Use WebSearch for specific gaps identified
- Gather comprehensive information
- Note all source URLs
3. SAVE FINDINGS
- Search for related notes: mcp__librania__search_notes for related topics
- Create note: mcp__librania__create_note with:
* Clear title
* Markdown body with sources
* [[Note Title]] links to related notes
* Relevant tags
- Return note ID
4. RETURN CONSOLIDATED ANSWER
Format:
"""
{answer_text}
Sources:
- LibraNia: {note_titles}
- Web: {urls}
- New note: {title} (ID: {id})
"""
Be thorough but concise. Focus on answering the query.
Example Execution
User: "What are Docker security best practices?"
Main thread spawns Agent:
Agent (research):
1. mcp__librania__search_notes("Docker security")
→ Found 2 notes: "Docker Basics", "Container Networking"
→ Partial info, missing: image scanning, secrets management, runtime security
2. WebSearch("Docker image scanning security")
WebSearch("Docker secrets management")
WebSearch("Docker runtime security best practices")
→ Gathered comprehensive info
3. mcp__librania__search_notes("Docker") to find related notes
→ Found: "Docker Basics", "Container Networking", "Kubernetes Security"
4. mcp__librania__create_note:
title: "Docker Security Best Practices"
body: """
# Docker Security Best Practices
## Image Security
- Use official base images
- Scan images with Trivy/Snyk
- Multi-stage builds to reduce attack surface
## Secrets Management
- Never hardcode secrets in Dockerfile
- Use Docker secrets or external vaults
- Rotate credentials regularly
## Runtime Security
- Run containers as non-root user
- Use read-only filesystems where possible
- Limit container capabilities
Related: [[Docker Basics]], [[Container Networking]], [[Kubernetes Security]]
Sources:
- https://docs.docker.com/engine/security/
- https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html
"""
tags: ["docker", "security", "devops", "containers"]
→ Note created: ID abc123
5. Return:
"""
Docker security best practices:
**Image Security:** Use official images, scan with Trivy/Snyk, multi-stage builds
**Secrets:** Never hardcode, use Docker secrets/vaults, rotate regularly
**Runtime:** Non-root user, read-only FS, limit capabilities
Sources:
- LibraNia: "Docker Basics", "Container Networking"
- Web: docs.docker.com/engine/security, OWASP Docker Security
- New note: "Docker Security Best Practices" (ID: abc123)
"""
Main thread receives answer and presents to user.
Tool Requirements
Agent must have access to:
mcp__librania__search_notes - search knowledge basemcp__librania__get_note - read full note contentmcp__librania__create_note - save findingsmcp__librania__add_tags - tag notesWebSearch - fallback web search
Error Handling
LibraNia DB not found:
Skip LibraNia search, proceed directly to web search.
Log: "LibraNia not available, using web search only"
Web search fails:
Return LibraNia results only with note:
"Limited to existing knowledge base. Web search unavailable."
Note creation fails:
Return answer with sources, log error:
"Answer provided but failed to save to LibraNia: {error}"
Configuration
Agent spawn parameters:
{
subagent_type: "general-purpose",
description: "Research with LibraNia integration",
prompt: `${RESEARCH_PROMPT_TEMPLATE}`,
run_in_background: false
}
MCP server must be configured in Claude Code CLI or Codex settings.
Testing
Test 1: LibraNia has answer
User: "What is React?"
Expected: Agent finds existing note, returns answer, no web search, no new note
Test 2: LibraNia partial
User: "What are React hooks?"
Expected: Agent finds React note, searches web for hooks, creates new note, returns combined answer
Test 3: LibraNia empty
User: "What is Zig programming language?"
Expected: Agent finds nothing, searches web, creates note, returns answer
Test 4: Related notes linking
User: "Docker networking modes"
Expected: New note links to [[Docker Basics]], [[Container Networking]]
Integration with Other Skills
Works with:
brainstorming - research before design decisionssystematic-debugging - research error messages/stack tracestest-driven-development - research testing patterns
Conflicts with:
- None (research is orthogonal to other workflows)
Performance
Typical execution:
- LibraNia search: 100-500ms
- Web search: 2-5s
- Note creation: 200-800ms
- Total: 3-6s for full workflow
Optimization:
- Parallel web searches for multiple gaps
- Cache LibraNia search results within Agent session
- Batch related note searches
Maintenance
Update when:
- MCP tool signatures change
- LibraNia DB schema changes
- New research sources added (beyond web search)
Monitor:
- Note creation success rate
- Web search fallback frequency
- Related note linking accuracy
