Best practices for creating, indexing, and managing Bluera Knowledge stores. Covers when to use clone vs crawl vs folder, naming conventions, indexing strategies, storage management, background job monitoring, and handling indexing failures.
/plugin marketplace add blueraai/bluera-knowledge/plugin install bluera-knowledge@blueraThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Master the lifecycle of knowledge stores from creation to deletion, including best practices for naming, indexing, and maintenance.
Bluera Knowledge supports three source types. Choose based on your content:
add-repo / create_store with git URL)✅ Use for:
Advantages:
git pull in repo directory)Example:
/bluera-knowledge:add-repo https://github.com/vuejs/core --name=vue
# Or via MCP:
create_store(
source='https://github.com/vuejs/core',
name='vue',
type='repo'
)
Best practices:
vue, fastapi, pydanticorg-project format: microsoft-typescript, vercel-nextvue-3.4, python-3.11add-folder)✅ Use for:
Advantages:
Example:
/bluera-knowledge:add-folder /path/to/my-project/api --name=my-api
# Or via MCP:
create_store(
source='/Users/me/projects/my-app/backend',
name='my-backend',
type='folder'
)
Best practices:
my-api, auth-service, shared-utils/bluera-knowledge:index my-apicrawl)✅ Use for:
Advantages:
Example:
/bluera-knowledge:crawl https://fastapi.tiangolo.com --name=fastapi-docs --max-pages=100
# Or via MCP:
create_store(
source='https://fastapi.tiangolo.com',
name='fastapi-docs',
type='web',
max_pages=100
)
Best practices:
-docs to library name: fastapi-docs, vue-docsmax-pages to avoid crawling entire internet--headless for JavaScript-heavy sitesGood names make stores easy to find and filter.
Library source code:
vue # Official package name
react
fastapi
pydantic
Documentation sites:
vue-docs
fastapi-docs
python-3.11-docs
Organization/project format:
microsoft-typescript
vercel-next
acme-payment-api # Your company's code
Versioned stores:
vue-3.4
python-3.11
react-18
Specialized content:
coding-standards # Company standards
api-spec-v2 # API specification
architecture-docs # Design docs
❌ Avoid:
docs, code, libraryfp, lib1, proj2024-01-15my-project-library-code✅ Prefer:
fastapi-docs, vue-sourcepydantic, lodashapi-spec-v2, coding-standardsWhen creating a store, indexing happens automatically in the background:
create_store(url, name)
→ Returns: job_id
→ Background: clone/download → analyze → index
→ Status: pending → running → completed
# Monitor progress
check_job_status(job_id)
→ Progress: 45% (processing src/core.ts)
→ Estimated: ~2 minutes remaining
Indexing time estimates:
When library code changes or you modify indexed content:
# For git repos: pull latest changes
cd .bluera/bluera-knowledge/repos/vue
git pull origin main
cd -
# Re-index
/bluera-knowledge:index vue
# Or via MCP:
index_store(store='vue')
→ Re-processes all files
→ Updates vector embeddings
→ Rebuilds search index
When to re-index:
Re-indexing is incremental - only changed files are re-processed.
For large repos, you might want to index specific directories:
# Clone full repo manually
git clone https://github.com/microsoft/vscode
cd vscode
# Index only specific dirs
/bluera-knowledge:add-folder ./src/vs/editor --name=vscode-editor
/bluera-knowledge:add-folder ./src/vs/workbench --name=vscode-workbench
# Result: Multiple focused stores instead of one massive store
Check what's using space:
list_stores()
→ vue: 487 files, 2.3 MB
→ react: 312 files, 1.8 MB
→ fastapi-docs: 156 pages, 0.9 MB
→ my-api: 89 files, 0.4 MB
Total storage: ~5.4 MB
# Detailed info
get_store_info('vue')
→ Location: .bluera/bluera-knowledge/repos/vue/
→ Indexed: 487 files
→ Size: 2.3 MB (source) + 4.1 MB (vectors)
→ Last indexed: 2 hours ago
✅ Delete when:
How to delete:
/bluera-knowledge:remove-store old-library
# Or via MCP:
delete_store(store='old-library')
→ Removes: source files, vector index, metadata
→ Frees: ~6-8 MB per store (varies by size)
⚠️ Cannot undo! Make sure you don't need the store before deleting.
All expensive operations run as background jobs: cloning, indexing, crawling.
1. create_store() or index_store() → Returns job_id
2. Job states:
- pending: In queue, not started
- running: Actively processing
- completed: Finished successfully
- failed: Error occurred
3. Monitor progress:
check_job_status(job_id)
→ Current state, percentage, current file
4. List all jobs:
list_jobs()
→ See pending, running, completed jobs
5. Cancel if needed:
cancel_job(job_id)
→ Stops running job, cleans up
Do poll, but not too frequently:
# ❌ Too frequent - wastes resources
while status != 'completed':
check_job_status(job_id) # Every second!
sleep(1)
# ✅ Reasonable polling interval
while status != 'completed':
check_job_status(job_id)
sleep(15) # Every 15 seconds is fine
Do handle failures gracefully:
status = check_job_status(job_id)
if status['state'] == 'failed':
error = status['error']
if 'auth' in error.lower():
print("Authentication required - try SSH URL or provide credentials")
elif 'not found' in error.lower():
print("Repository/URL not found - check the source")
elif 'disk' in error.lower():
print("Disk space issue - delete unused stores")
else:
print(f"Unexpected error: {error}")
Do list jobs to avoid duplicates:
# Before creating new store
jobs = list_jobs()
existing = [j for j in jobs if j['store'] == 'vue' and j['state'] in ['pending', 'running']]
if existing:
print(f"Job already running for 'vue': {existing[0]['id']}")
# Wait for it instead of creating duplicate
else:
create_store(...)
1. Authentication Required (Private Repos)
Error: "Authentication required"
Fix options:
- Use SSH URL: git@github.com:org/repo.git
- Use HTTPS with token: https://token@github.com/org/repo.git
- Make repo public (if appropriate)
2. Invalid URL/Path
Error: "Repository not found" or "Path does not exist"
Fix:
- Verify URL is correct (typos common!)
- Check path exists and is accessible
- Ensure network connectivity
3. Disk Space
Error: "No space left on device"
Fix:
- Check available space: df -h
- Delete unused stores: delete_store(old_store)
- Clear .bluera/bluera-knowledge/repos/ manually if needed
4. Network Timeout
Error: "Connection timeout" or "Failed to fetch"
Fix:
- Retry after checking network
- Use --shallow for large repos
- Clone manually then add-folder
5. Unsupported File Types
Warning: "Skipped 45 binary files"
This is normal!
- Binary files (images, compiled code) are skipped
- Only text files are indexed
- Check indexed count vs total to see ratio
1. Attempt fails:
create_store(url, name) → job fails
2. Check error:
job_status = check_job_status(job_id)
error_msg = job_status['error']
3. Determine fix based on error type (see above)
4. Retry with fix:
create_store(corrected_url, name)
5. Verify success:
check_job_status(new_job_id)
→ Status: completed
list_stores()
→ Store appears in list
6. Test search:
search(test_query, stores=[name], limit=3)
→ Returns results: ✅ Ready to use!
Creating a Store:
Maintaining a Store:
Deleting a Store:
# Create
/bluera-knowledge:add-repo <url> --name=<name>
/bluera-knowledge:add-folder <path> --name=<name>
/bluera-knowledge:crawl <url> --name=<name>
# Monitor
/bluera-knowledge:check-status <job-id>
# Maintain
/bluera-knowledge:index <name>
/bluera-knowledge:stores
# Remove
/bluera-knowledge:remove-store <name>
Master these lifecycle management practices to maintain a clean, efficient, and useful knowledge base.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.