Add all custom Hermes skills from general profile (33 skills)
agent-workflows: workspace-context-organization autonomous-ai-agents: hermes-agent computer-use devops: hermes-config-bulk-update, hermes-profile-management, holographic-memory, telegram-integration, webhook-subscriptions email: himalaya mcp: native-mcp, searxng-smart-search media: voice-systems, youtube-content mlops: local-vector-memory, qdrant-collection-management productivity: maps, notion, ocr-and-documents project-knowledge-base research: arxiv, blogwatcher, ecosystem-surveillance save-agents-md social-media: social-media-scraping, xurl software-development: agent-self-audit, simplify-code, spike, subagent-driven-development, systematic-debugging, test-driven-development, writing-plans user-response-style
This commit is contained in:
Hermes Agent
191
project-knowledge-base/SKILL.md
Normal file
191
project-knowledge-base/SKILL.md
Normal file
@@ -0,0 +1,191 @@
|
||||
---
|
||||
name: project-knowledge-base
|
||||
description: "Seed and maintain a project-scoped Qdrant knowledge base from web research so a future agent (or audit) can review a software project's setup against authoritative external docs. Covers workspace scoping, multi-source ingestion, issues+resolutions extraction, and audit-query patterns."
|
||||
version: 1.0.0
|
||||
category: research
|
||||
author: hermes
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [knowledge-base, qdrant, rag, project-audit, setup-review, research, web-search]
|
||||
category: research
|
||||
related_skills:
|
||||
- local-vector-memory
|
||||
- ecosystem-surveillance
|
||||
- searxng-smart-search
|
||||
- llm-wiki
|
||||
- obsidian
|
||||
---
|
||||
|
||||
# Project Knowledge Base (Qdrant + Web Research)
|
||||
|
||||
Build a **queryable, project-scoped knowledge base in Qdrant** for a specific software project — populated from authoritative web sources — so that a future session can audit the project's setup against current best practices, debug recurring issues with known resolutions, or onboard a new agent quickly.
|
||||
|
||||
## When to Use
|
||||
|
||||
Trigger this skill when the user says any of:
|
||||
- "do multiple deep web searches to add more details about X" (where X is a software project, framework, or tool the user is running)
|
||||
- "later I want to review our setup using this KB"
|
||||
- "build a knowledge base for project X"
|
||||
- "find known issues and fixes for X"
|
||||
- "so we can audit our X setup later"
|
||||
|
||||
**Not for:**
|
||||
- Generic fact-gathering about a non-software topic (use `ecosystem-surveillance`)
|
||||
- Markdown-only notes (use `llm-wiki`)
|
||||
- Setting up the Qdrant stack itself (use `local-vector-memory` first)
|
||||
- Single-file Q&A (use `web_search` directly)
|
||||
|
||||
## The Core Distinction from Related Skills
|
||||
|
||||
| Skill | Output | Intent | Scope |
|
||||
|---|---|---|---|
|
||||
| `ecosystem-surveillance` | Single markdown research artifact | "What's the current state of X?" | Broad, time-bounded |
|
||||
| `llm-wiki` | Interlinked markdown files | Personal/team knowledge compilation | Whole domain |
|
||||
| `local-vector-memory` | Qdrant collection + tooling | Storage infrastructure | Generic |
|
||||
| **`project-knowledge-base`** | **Qdrant collection of structured docs** | **"Audit my project against authoritative sources"** | **One project, persistent** |
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Scope and Scaffolding
|
||||
|
||||
1. **Confirm the project name and target collection.** Default convention: `<project>_kb` (matches existing pattern: `hermes_kb`, `comfyui_kb`, `nuntius_kb`).
|
||||
2. **Check the collection doesn't already exist or already has data:**
|
||||
```python
|
||||
# Via mcp_better_qdrant tools
|
||||
mcp_better_qdrant_list_collections()
|
||||
mcp_better_qdrant_search(query="<project>", collection="<project>_kb", embeddingService="ollama", limit=5)
|
||||
```
|
||||
If existing data is junk or off-topic, ask user before deleting. Never silently overwrite.
|
||||
3. **Verify collection dimensions match the active Ollama embedder** (this stack: `snowflake-arctic-embed2:latest` = 1024-dim). See `local-vector-memory` "Critical pitfall — vector size hardcode" — the `better-qdrant-mcp-server` auto-creates at 768-dim if collection is missing.
|
||||
|
||||
### Phase 2: Topic Decomposition (todo list before searching)
|
||||
|
||||
Before running any searches, write a `todo` list of topic areas. The user is not going to read the whole result — they want a **structured KB that covers the project end-to-end**, not a freeform dump. Typical topic set for a software project:
|
||||
|
||||
1. Architecture / system overview / directory structure
|
||||
2. Configuration reference (config.yaml, env vars, settings)
|
||||
3. Core feature deep-dive (memory, skills, plugins, etc. — one doc per major feature)
|
||||
4. Integration / API docs (MCP, providers, external services)
|
||||
5. CLI / slash command reference
|
||||
6. Security / approval model
|
||||
7. Operational patterns (cron, delegation, multi-agent, etc.)
|
||||
8. FAQ / troubleshooting / known issues + resolutions ← **REQUIRED, not optional**
|
||||
9. Index / overview doc with cross-references
|
||||
|
||||
The user often says "include all issues and resolutions" — that means **every doc must end with a "Common Issues + Resolutions" section**, and there should be a dedicated FAQ/troubleshooting doc as topic #8.
|
||||
|
||||
### Phase 3: Multi-Source Research Pattern
|
||||
|
||||
For each topic, layer the sources:
|
||||
|
||||
1. **Official docs first** (highest authority). For Hermes Agent, that's `hermes-agent.nousresearch.com/docs/...`. Get the full page with `mcp_searxng_web_url_read` — these are the canonical statements.
|
||||
2. **DeepWiki / official repo docs** for architecture and code-level detail.
|
||||
3. **Community deep-dives** (Rost Glukhov, Petronella, Blake Crosley, MACGPU blog, NxCode, etc.) for production experience, gotchas, and 2026-current context.
|
||||
4. **Reddit / forum threads** for known issues and "what works in practice."
|
||||
5. **GitHub releases / issues** for breaking changes and version-specific gotchas.
|
||||
|
||||
Run **3-8 searches per topic** in parallel batches (don't go serially — `mcp_searxng_searxng_web_search` supports parallel calls). Use `searxng-smart-search` defaults: tech/code = `it,science` + `time_range=month` + `min_score=0.2`.
|
||||
|
||||
For each topic, **fetch 1-3 full pages** with `mcp_searxng_web_url_read` rather than relying on snippets. Snippets miss the structure (command syntax, table values, pitfall callouts).
|
||||
|
||||
### Phase 4: Write Structured Documents to Staging
|
||||
|
||||
Don't write to the Qdrant collection directly. Stage first:
|
||||
|
||||
1. `mkdir -p /tmp/<project>_kb_staging`
|
||||
2. Write one markdown doc per topic, numbered `NN_<topic>.md`, with frontmatter:
|
||||
```yaml
|
||||
---
|
||||
title: <Project> — <Topic>
|
||||
source: <primary URL>
|
||||
retrieved: YYYY-MM-DD
|
||||
type: official-docs | community | deep-dive | index
|
||||
---
|
||||
```
|
||||
3. Number `00_index.md` is always the index — built last, references every other doc.
|
||||
4. Each doc should be **self-contained for one topic** but end with a "Where to look for related issues" pointer to other docs.
|
||||
5. Each doc must end with **"Common Issues + Resolutions"** with the format:
|
||||
```
|
||||
### <Symptom>
|
||||
**Cause:** <root cause>
|
||||
**Fix:** <resolution steps>
|
||||
```
|
||||
The user explicitly asks for issues + resolutions — this is not optional, it's the audit hook.
|
||||
|
||||
### Phase 5: Parallel Index to Qdrant
|
||||
|
||||
Once all docs are staged, **parallel-batch** the `mcp_better_qdrant_add_documents` calls — don't serialize. With 12-15 docs, this is 1 turn instead of 12-15.
|
||||
|
||||
```python
|
||||
# Pseudocode for the agent's call pattern
|
||||
parallel_for doc in staging_docs:
|
||||
mcp_better_qdrant_add_documents(
|
||||
filePath=doc,
|
||||
collection=f"{project}_kb",
|
||||
embeddingService="ollama"
|
||||
)
|
||||
```
|
||||
|
||||
### Phase 6: Verify Queryability
|
||||
|
||||
Run 3-5 **targeted test queries** that should hit specific docs. This is not optional — without verification, you have no evidence the KB is queryable:
|
||||
|
||||
```python
|
||||
queries = [
|
||||
"<symptom 1 from FAQ>",
|
||||
"<key feature name>",
|
||||
"<provider-specific error>",
|
||||
"<known gotcha>"
|
||||
]
|
||||
for q in queries:
|
||||
mcp_better_qdrant_search(query=q, collection=f"{project}_kb", embeddingService="ollama", limit=3)
|
||||
```
|
||||
|
||||
Check the relevance scores — values 0.4+ usually mean the doc is retrievable; below 0.4 means chunking or query is off. The agent should report scores back to the user so they know the audit will work.
|
||||
|
||||
### Phase 7: Report
|
||||
|
||||
Final report structure (terse, per user style — "1-3 sentences, actionable answer first, no padding"):
|
||||
|
||||
- **Total docs / chunks indexed** (the count that landed in Qdrant)
|
||||
- **Coverage summary** (one line per doc, the topic)
|
||||
- **Verification evidence** (test queries with scores)
|
||||
- **What's in the KB** (index of doc titles so the user can `mcp_better_qdrant_search` for any)
|
||||
- **Suggested next step** ("Ready for the audit — point me at what you want to review first")
|
||||
|
||||
## Pitfalls
|
||||
|
||||
1. **Don't search for things the user already told you.** If the user says "we have RTX 4090," don't search "does RTX 4090 exist?" — search for what's relevant to the project they're running on it. The KB's value is depth, not breadth.
|
||||
2. **SearXNG rate-limits after 4-6 queries in quick succession.** If `mcp_searxng_searxng_web_search` returns empty or fails, **switch to `web_search`/`web_extract`** as fallback, or pause and retry. Don't bang on a dead endpoint.
|
||||
3. **Snippets lie.** The model often hallucinates a useful-looking snippet that isn't actually in the page. Always `mcp_searxng_web_url_read` for the full content of top 1-3 sources per topic before writing the doc.
|
||||
4. **Authoritative sources > quantity.** 1-2 great sources (official docs, deep-dive blog) per topic beats 10 thin sources. Better to write 12 well-sourced docs than 30 with redundant or low-quality content.
|
||||
5. **"Common Issues + Resolutions" is required, not optional.** The user explicitly asks for this — it's the audit hook. Every doc must end with that section, and there must be a dedicated FAQ/troubleshooting doc.
|
||||
6. **Include source provenance in frontmatter.** Every doc must have `source: <primary URL>` and `retrieved: <date>` in the YAML. Future audits need to know when the info was current and where it came from.
|
||||
7. **Verify before reporting.** Always run test queries after indexing. A "successfully added" response doesn't mean the chunks are retrievable — relevance scores vary, and bad queries can return junk.
|
||||
8. **Existing collection != good collection.** Check what's already there before adding. If the existing content is low-quality scraped SEO pages (typical for unscoped research), the new docs will be drowned in noise. Ask the user before nuking.
|
||||
9. **Don't index the index doc twice.** The `00_index.md` references the others but is itself useful content — index it, but don't waste chunks on it being mostly pointers. Keep it tight.
|
||||
10. **The user wants depth in work, brevity in delivery.** Final report should be 5-15 lines max — not a per-doc walkthrough. The user reads the KB via search, not your summary.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- **Single mega-doc.** Don't dump everything into one file. The Qdrant chunker will produce incoherent chunks, and the user can't selectively search.
|
||||
- **Skipping verification.** "Successfully added" is not the same as "queryable." Always test.
|
||||
- **Padding the index doc.** The index is a navigation aid, not a re-summary. One line per doc with a one-sentence description.
|
||||
- **Including environment-dependent failures as "issues."** If `uv` isn't installed on the user's box, that's a setup fact, not a KB issue. Only include real product bugs, version-specific gotchas, or design gotchas (like the memory frozen-snapshot pattern).
|
||||
- **Hallucinated fixes.** If you didn't see a fix in a real source, don't write one. "Common Issues + Resolutions" should be sourced from the docs you actually read. Unsourced fixes rot.
|
||||
|
||||
## Output Structure (what the user sees at the end)
|
||||
|
||||
```
|
||||
Done. <project>_kb has N docs (M chunks) covering: [topic list].
|
||||
Verified queryable: [test query] → [score], [test query] → [score].
|
||||
Each doc has a "Common Issues + Resolutions" section. Ready for audit — point me at what to review.
|
||||
```
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `local-vector-memory` — load first; this skill assumes the Qdrant stack is set up
|
||||
- `searxng-smart-search` — the search layer; provides defaults
|
||||
- `ecosystem-surveillance` — sibling pattern for time-bounded research, not project audit
|
||||
- `llm-wiki` — markdown-first alternative when Qdrant isn't desired
|
||||
- `obsidian` — if the user also wants to browse the KB in an Obsidian vault (would need parallel markdown export)
|
||||
Reference in New Issue
Block a user