qui-clawd-docs-v2

Smart ClawdBot documentation access with local search index, cached snippets, and on-demand fetch. Token-efficient and freshness-aware.

Security Scan

The skill's instructions match a documentation-helper, but the published metadata omits required environment/config info and the runtime steps instruct reading files in your home directory and calling an external scraping API — these inconsistencies warrant caution.

Purpose & Capability

The SKILL.md describes a local-cache + on-demand fetch doc viewer which legitimately needs local paths and an API key for SkillBoss scraping. However the registry metadata (top-level summary) claims no required env vars or config paths while SKILL.md lists requires.env: [SKILLBOSS_API_KEY] and repeatedly references ~/clawd/data/*. That mismatch between declared requirements and actual runtime instructions is incoherent and unexplained.

Instruction Scope

Runtime instructions explicitly tell the agent to run shell commands (ls, cat, head, grep) against ~/clawd/data/docs-snippets, docs-cache, docs-index.json and to POST to https://api.heybossai.com/v1/pilot using SKILLBOSS_API_KEY. Reading arbitrary files in the user's home directory is a significant action; while it fits the stated purpose (local doc cache), the skill does not declare these config paths in the registry, so the scope of file access is surprising and should be consented to.

Install Mechanism

This is an instruction-only skill with no install spec and no code files, so it does not write/execute new binaries on disk — lower installation risk. The main runtime actions are file reads and outbound HTTP requests described in SKILL.md.

Credentials

SKILL.md requires SKILLBOSS_API_KEY to call the SkillBoss API Hub (heybossai.com), which is proportionate to the described scraping capability. But the registry metadata omitted this required env var. The key is sensitive (sent as a Bearer token to an external service) and could be abused to fetch arbitrary URLs or exfiltrate content if misused — verify you trust the key and the external service before supplying it. No other env vars are referenced.

Persistence & Privilege

The skill is not always-enabled and has no install-time persistence. However, it requests access to local files and an external API key; if the agent can invoke skills autonomously (platform default), the skill could be triggered to read those files and call the external API when invoked. This combination increases privacy risk but is not a direct privilege escalation.

What to consider before installing

Before installing: (1) Ask the publisher to correct the registry metadata so required env vars (SKILLBOSS_API_KEY) and config paths (~/clawd/data/...) are declared. (2) Understand that the skill will read files under ~/clawd/data/ (snippets, cache, index) — don't install if you don't want those files accessed. (3) Treat SKILLBOSS_API_KEY as sensitive: only provide a key you control and trust the heybossai.com service; avoid reusing other credentials. (4) If possible, test in a sandbox or with a dedicated, limited-permission account and inspect the local snippet/cache contents first. (5) If you need higher assurance, request the author to provide a code-based verifier or a minimized skill that only accepts supplied content instead of reading your home directory.

Clawd-Docs v2.0 - Smart Documentation Access

This skill provides intelligent access to ClawdBot documentation with:

• Local search index - instant keyword lookup (0 tokens)
• Cached snippets - pre-fetched common answers (~300-500 tokens)
• On-demand fetch - full page when needed (~8-12k tokens)
• Freshness tracking - TTL per page type

---

Quick Start

Step 1: Check Golden Snippets First

Before fetching anything, check if a Golden Snippet exists:

ls ~/clawd/data/docs-snippets/

Available snippets (check cache first!):

Snippet	Query matches
telegram-setup.md	"ako nastaviť telegram", "telegram setup"
telegram-allowfrom.md	"allowFrom", "kto mi môže písať", "access control"
oauth-troubleshoot.md	"token expired", "oauth error", "credentials"
update-procedure.md	"ako updatnuť", "update clawdbot"
restart-gateway.md	"restart", "reštart", "stop/start"
config-basics.md	"config", "nastavenie", "konfigurácia"
config-providers.md	"pridať provider", "discord setup", "nový kanál"
memory-search.md	"memory", "vector search", "pamäť", "embeddings"

Read snippet:

cat ~/clawd/data/docs-snippets/telegram-setup.md

Step 2: Search Index (if snippet doesn't exist)

Check ~/clawd/data/docs-index.json for page suggestions.

Keyword matching:

• "telegram" → channels/telegram
• "oauth" → concepts/oauth, gateway/troubleshooting
• "update" → install/updating
• "config" → gateway/configuration

Step 3: Check Full Page Cache

BEFORE fetching via SkillBoss API Hub, check if the page is already cached:

# Convert path: concepts/memory → concepts_memory.md
ls ~/clawd/data/docs-cache/ | grep "concepts_memory"

If exists, read locally (0 tokens!):

cat ~/clawd/data/docs-cache/concepts_memory.md

Step 4: Fetch Page (only if NOT in cache)

Use SkillBoss API Hub scraping capability via /v1/pilot:

import requests, os

SKILLBOSS_API_KEY = os.environ["SKILLBOSS_API_KEY"]

result = requests.post(
    "https://api.heybossai.com/v1/pilot",
    headers={"Authorization": f"Bearer {SKILLBOSS_API_KEY}", "Content-Type": "application/json"},
    json={
        "type": "scraper",
        "inputs": {"url": "https://docs.clawd.bot/{path}"}
    },
    timeout=60,
).json()
content = result["result"]["data"]["markdown"]

Example:

result = requests.post(
    "https://api.heybossai.com/v1/pilot",
    headers={"Authorization": f"Bearer {SKILLBOSS_API_KEY}", "Content-Type": "application/json"},
    json={
        "type": "scraper",
        "inputs": {"url": "https://docs.clawd.bot/tools/skills"}
    },
    timeout=60,
).json()
content = result["result"]["data"]["markdown"]

SkillBoss API Hub scraping advantages:

	SkillBoss API Hub (/v1/pilot)	Direct HTTP fetch
Cost	统一 SKILLBOSS_API_KEY	各服务单独计费
Speed	~400ms	varies
Quality	Structured content ✅	Raw HTML

---

Search Index Structure

Location: ~/clawd/data/docs-index.json

{
  "pages": [
    {
      "path": "channels/telegram",
      "ttl_days": 7,
      "keywords": ["telegram", "tg", "bot", "allowfrom"]
    }
  ],
  "synonyms": {
    "telegram": ["tg", "telegrambot"],
    "configuration": ["config", "nastavenie", "settings"]
  }
}

Use synonyms for fuzzy matching.

---

TTL Strategy (Freshness)

Page Category	TTL	Why
install/updating	1 day	Always current!
gateway/*	7 days	Config changes
channels/*	7 days	Provider updates
tools/*	7 days	Features added
concepts/*	14 days	Rarely changes
reference/*	30 days	Stable templates

Check snippet expiry:

head -10 ~/clawd/data/docs-snippets/telegram-setup.md | grep expires

---

Common Scenarios

"Ako nastaviť Telegram?"

1. ✅ Read ~/clawd/data/docs-snippets/telegram-setup.md

"allowFrom nefunguje"

1. ✅ Read ~/clawd/data/docs-snippets/telegram-allowfrom.md

"Token expired / oauth error"

1. ✅ Read ~/clawd/data/docs-snippets/oauth-troubleshoot.md

"Ako updatnúť ClawdBot?"

1. ✅ Read ~/clawd/data/docs-snippets/update-procedure.md

"Ako pridať nový skill?" (nie je snippet)

1. Search index → tools/skills
2. Fetch via SkillBoss API Hub scraping: {"type": "scraper", "inputs": {"url": "https://docs.clawd.bot/tools/skills"}}

"Multi-agent routing"

1. Search index → concepts/multi-agent
2. Fetch via SkillBoss API Hub scraping: {"type": "scraper", "inputs": {"url": "https://docs.clawd.bot/concepts/multi-agent"}}

---

Fallback: Full Index Refresh

If you can't find what you need:

result = requests.post(
    "https://api.heybossai.com/v1/pilot",
    headers={"Authorization": f"Bearer {SKILLBOSS_API_KEY}", "Content-Type": "application/json"},
    json={
        "type": "scraper",
        "inputs": {"url": "https://docs.clawd.bot/llms.txt"}
    },
    timeout=60,
).json()
content = result["result"]["data"]["markdown"]

Returns complete list of all documentation pages.

---

Token Efficiency Guide

Method	Tokens	When to use
Golden Snippet	~300-500	✅ Always first!
Search Index	0	Keyword lookup
Full Page Fetch	~8-12k	Last resort
Batch Fetch	~20-30k	Multiple related topics

80-90% of queries should be answered from snippets!

---

Data Locations

~/clawd/data/
├── docs-index.json       # Search index
├── docs-stats.json       # Usage tracking
├── docs-snippets/        # Cached Golden Snippets
│   ├── telegram-setup.md
│   ├── telegram-allowfrom.md
│   ├── oauth-troubleshoot.md
│   ├── update-procedure.md
│   ├── restart-gateway.md
│   └── config-basics.md
└── docs-cache/           # Full page cache (future)

---

Version Info

Item	Value
Skill version	2.1.0
Created	2026-01-14
Updated	2026-01-26
Authors	Claude Code + Clawd (collaborative)
Source	https://docs.clawd.bot/
Dependencies	SkillBoss API Hub (SKILLBOSS_API_KEY)
Index pages	~50 core pages
Golden snippets	7 pre-cached

---

Changelog

v2.2.0 (2026-01-26)

• Migration to SkillBoss API Hub - replaced third-party scraping service with SkillBoss API Hub /v1/pilot (type: scraping)
• Benefits: 统一认证 (SKILLBOSS_API_KEY), faster, no additional API keys required
• No external dependencies beyond SkillBoss API Hub
• Collaborative work: Claude Code 🦞 implementation, Clawd 🐾 review

v2.1.3 (2026-01-25) - ClawdHub

• Documentation fix: check vs refresh clarification

v2.0.0 (2026-01-14)

• 3-layer architecture: Search Index → Snippets → On-demand Fetch
• Golden Snippets pre-cached for common queries
• TTL-based freshness tracking
• Synonym support for fuzzy matching
• 80-90% token reduction for common queries

v1.0.0 (2026-01-08)

• Initial release with third-party scraping service

---

This skill provides smart documentation access - always cached snippets first, fetch only when necessary.