144 lines
4.2 KiB
Markdown
144 lines
4.2 KiB
Markdown
---
|
|
name: document-sync
|
|
description: Document management system for storing, querying, and retrieving documents across Claude Code sessions. Use this to maintain knowledge bases, share documents between agent. Whenever you encounter a <document id=*> in a session, use this skill to retrieve its content.
|
|
---
|
|
|
|
# Document Sync Skill
|
|
|
|
## What & When
|
|
|
|
**What**: Commands for uploading, downloading, querying, and deleting documents with metadata and tags through a centralized document server.
|
|
|
|
**When to use**:
|
|
- Store important documents for retrieval in future sessions
|
|
- Build a knowledge base of project documentation
|
|
- Share architecture, API specs, or design documents across different work sessions
|
|
- Query documents by tags to find relevant information
|
|
|
|
**Key Benefits**:
|
|
- Cross-session persistence
|
|
- Tag-based organization with AND logic
|
|
- Simple JSON output
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
**CRITICAL**: Always use absolute paths - NEVER use `cd`:
|
|
|
|
### `doc-push` - Upload Documents
|
|
```bash
|
|
uv run <skill-root>/commands/doc-push <file> [--tags TEXT] [--description TEXT]
|
|
# Example: uv run <skill-root>/commands/doc-push specs.md --tags "api,v2"
|
|
```
|
|
**Use when**: Store a document for future reference.
|
|
|
|
### `doc-query` - Search Documents
|
|
```bash
|
|
uv run <skill-root>/commands/doc-query [--tags TEXT] [--name TEXT]
|
|
# Example: uv run <skill-root>/commands/doc-query --tags "api,v2"
|
|
```
|
|
**Use when**: Find documents by tags (AND logic) or name patterns.
|
|
|
|
### `doc-info` - Get Document Metadata
|
|
```bash
|
|
uv run <skill-root>/commands/doc-info <document-id>
|
|
# Example: uv run <skill-root>/commands/doc-info doc_abc123
|
|
```
|
|
**Use when**: View metadata for a specific document without downloading it.
|
|
|
|
### `doc-read` - Read Text Documents
|
|
```bash
|
|
uv run <skill-root>/commands/doc-read <document-id>
|
|
# Example: uv run <skill-root>/commands/doc-read doc_abc123
|
|
```
|
|
**Use when**: Output text document content directly to stdout (text files only).
|
|
|
|
### `doc-pull` - Download Documents
|
|
```bash
|
|
uv run <skill-root>/commands/doc-pull <document-id> [-o PATH]
|
|
# Example: uv run <skill-root>/commands/doc-pull doc_abc123 -o specs.md
|
|
```
|
|
**Use when**: Retrieve a document by its ID.
|
|
|
|
### `doc-delete` - Remove Documents
|
|
```bash
|
|
uv run <skill-root>/commands/doc-delete <document-id>
|
|
# Example: uv run <skill-root>/commands/doc-delete doc_abc123
|
|
```
|
|
**Use when**: Permanently remove a document.
|
|
|
|
---
|
|
|
|
## Typical Workflows
|
|
|
|
### Store and Retrieve
|
|
```bash
|
|
# Upload with tags
|
|
uv run <skill-root>/commands/doc-push specs.md --tags "api,v2"
|
|
|
|
# Find it later
|
|
uv run <skill-root>/commands/doc-query --tags "api,v2"
|
|
|
|
# Download it
|
|
uv run <skill-root>/commands/doc-pull doc_abc123
|
|
```
|
|
|
|
### Build Knowledge Base
|
|
```bash
|
|
# Upload multiple documents with consistent tags
|
|
uv run <skill-root>/commands/doc-push architecture.md --tags "design,mvp"
|
|
uv run <skill-root>/commands/doc-push api-spec.md --tags "api,mvp"
|
|
|
|
# Query by project phase
|
|
uv run <skill-root>/commands/doc-query --tags "mvp"
|
|
```
|
|
|
|
---
|
|
|
|
## Key Concepts
|
|
|
|
### Tag AND Logic
|
|
**IMPORTANT**: Multiple tags means ALL must match:
|
|
- `--tags "python,api"` → Document must have BOTH tags
|
|
- `--tags "v2,design,spec"` → Document must have ALL THREE tags
|
|
|
|
### Output Format
|
|
All commands output JSON. Save document IDs from upload for later retrieval/deletion.
|
|
|
|
---
|
|
|
|
## Notes for AI Assistants
|
|
|
|
1. **Tag AND logic** - Multiple tags = ALL must match
|
|
2. **Save document IDs** - From upload output for future operations
|
|
3. **Check server running** - Handle connection errors gracefully
|
|
4. **Parse JSON output** - All commands return JSON
|
|
5. **Tags are lowercase** - Use consistent tag naming (`python` not `Python`)
|
|
|
|
---
|
|
|
|
## Quick Decision Tree
|
|
|
|
**Store document?** → `doc-push <file> --tags "tag1,tag2"`
|
|
|
|
**Find documents?** → `doc-query --tags "tag1,tag2"` (AND logic)
|
|
|
|
**Check metadata?** → `doc-info <doc-id>` (metadata only)
|
|
|
|
**Read text file?** → `doc-read <doc-id>` (text files to stdout)
|
|
|
|
**Download document?** → `doc-pull <doc-id>` (ID from query)
|
|
|
|
**Remove document?** → `doc-delete <doc-id>` (permanent)
|
|
|
|
**List all?** → `doc-query` (no args)
|
|
|
|
---
|
|
|
|
## Additional Resources
|
|
|
|
- **Detailed Command Reference**: See `references/COMMANDS.md`
|
|
- **Configuration Options**: See `references/CONFIGURATION.md`
|
|
- **Error Handling**: See `references/TROUBLESHOOTING.md`
|