rag-content-writer

name	rag-content-writer
description	RAG-based content writing with knowledge retrieval and claim verification. Use when creating fact-based content (articles, docs, blogs, whitepapers) that requires citations from a knowledge base. Supports structured briefs, hybrid search retrieval, context packet assembly, and claim-to-citation verification to reduce hallucinations.

RAG Content Writer

Grounded content generation with retrieval-augmented generation (RAG) and claim verification.

When to Use

Use this skill when:

1. Creating content that must be factually accurate and cited
2. Writing from a knowledge base (docs, wiki, Notion, etc.)
3. Need to verify claims against sources
4. Want to reduce hallucinations in generated content
5. Working with structured content briefs

Architecture

Two-layer system:

A) Knowledge Layer (scripts/kb_manager.py)

• Document ingestion and chunking
• Hybrid search (full-text + metadata filters)
• Source metadata tracking (freshness, canonical, permissions)

B) Writing Layer (scripts/workflow.py)

• Brief parsing and query generation
• Context packet assembly
• Draft generation with citations
• Claim verification

Quick Start

1. Ingest Knowledge

python3 scripts/kb_manager.py \
  --ingest \
  --source-id "api-docs-v2.3" \
  --content-file ./api-docs.md \
  --metadata '{"product_area": "api", "doc_type": "spec", "canonical": true}'

2. Run Writing Workflow

python3 scripts/workflow.py \
  --skill-dir . \
  --brief "Topic: API Rate Limiting
Audience: developers
Type: article

Must include:
- Rate limits prevent abuse
- Exponential backoff recommended" \
  --output result.json

3. Check KB Stats

python3 scripts/kb_manager.py --stats

Brief Format

See references/brief-format.md for full specification.

Quick format:

Topic: [subject]
Audience: [target readers]
Type: [article/blog/doc/faq/whitepaper]

Must include:
- [claim 1]
- [claim 2]

Must not include:
- [forbidden claim 1]

Context Packet

The context packet is the bridge between knowledge and writing.

Sections:

• Key Facts (with citations)
• Definitions & Terminology
• Product Positioning
• Constraints & Disclaimers
• Relevant Examples
• Detected Contradictions

See references/context-packet.md for format details.

Writing Workflow

6-step process:

1. Parse Brief → Structured brief object
2. Generate Queries → 3-8 targeted search queries
3. Retrieve Context → Hybrid search + dedupe
4. Build Context Packet → Categorize and format
5. Draft Content → Generate with citations
6. Verify Claims → Ensure every claim is supported

See references/workflow.md for detailed guide.

Scripts

kb_manager.py

Knowledge base management.

# Ingest document
python3 scripts/kb_manager.py --ingest \
  --source-id "unique-id" \
  --content "document text" \
  --metadata '{"key": "value"}'

# Search
python3 scripts/kb_manager.py --search "query" \
  --filters '{"product_area": "api"}' \
  --top-k 10

# Stats
python3 scripts/kb_manager.py --stats

build_context.py

Build context packet from chunks.

python3 scripts/build_context.py \
  --chunks '[{...}, {...}]' \
  --brief '{...}' \
  --format prompt  # or json

workflow.py

Full writing workflow orchestration.

python3 scripts/workflow.py \
  --skill-dir /path/to/skill \
  --brief "brief text" \
  --output result.json

Metadata Schema

Store these metadata fields on every chunk:

Field	Description
product_area	Product/domain tag
doc_type	FAQ, spec, blog, etc.
audience	dev, PM, exec, etc.
updated_at	ISO timestamp
canonical	Boolean, source of truth
scope	Permissions/access level

Claim Verification

The most important anti-hallucination mechanism.

Rules:

• Every claim must have [Source: X] citation
• Unsupported claims are flagged
• Contradictions are surfaced

Output format:

{
  "verified": false,
  "unsupported_claims": [...],
  "assumptions": [...]
}

Best Practices

1. Mark canonical docs - Give higher weight to source-of-truth
2. Track freshness - Prefer newer docs for volatile topics
3. Small chunks - 200-600 tokens for precise citation
4. Cache retrieval - Cache context packets per topic
5. Eval first - Test retrieval before tuning prompts

Storage

Knowledge base stored at ~/.rag-content-writer/kb/:

• chunks.jsonl - All document chunks
• index.json - Search index (optional)

Limitations

• Simple full-text search (no embeddings yet)
• Basic contradiction detection
• No automatic re-ingestion
• Sequential by default (parallel on request)

Future Enhancements

• Vector embeddings for semantic search
• Automatic source re-ingestion
• Multi-modal content support
• Real-time knowledge updates