Initial commit

skills/document-sync/SKILL.md

@@ -0,0 +1,143 @@
+---
+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`