--- name: neotex description: Use when working in projects with .neotex/ directory to retrieve organizational knowledge, search for patterns/guidelines/decisions, store learnings, or manage reference assets like images and files. --- # Neotex Knowledge Integration ## Overview Neotex is an agent-first knowledge system for storing and retrieving organizational knowledge and assets. This skill integrates Claude Code with neotex via CLI commands. ## Conversation Start: Auto-Check At conversation start, check if neotex is initialized: ```bash ls .neotex/index.json 2>/dev/null ``` - **If exists**: Note available knowledge (scan summaries, don't fetch all) - **If missing but .neotex/ exists**: Suggest `neotex pull` - **If no .neotex/**: Skip neotex workflow unless user wants to initialize ## When to Search Search neotex when user asks about: - Organizational conventions, standards, guidelines - "How we do X here" or past decisions - Patterns or templates for common tasks - Reference images, mockups, or design files ```bash neotex search "" --limit 5 neotex search "type:guideline status:active path:backend " --mode hybrid neotex search "" --source asset --mode lexical neotex search "" --exact neotex get --search-id # fetch if score > 0.7 neotex asset get --search-id ``` - Use `--mode lexical` for exact terms, filenames, or code identifiers - Use `--exact` to disable query expansion - Pass `--search-id` to help the system learn which results were selected ## Precise Content Retrieval (VFS) For large documents or when you need specific sections: ```bash # Open with line range (like head/tail) neotex context open --lines 0:100 --max-chars 4000 # Open specific chunk from search result neotex context open --chunk # List items matching filters (like ls) neotex context list --path /docs --type guideline --source knowledge ``` - Search results include `chunk_id` for precise retrieval - Use `--max-chars` to limit response size (default 4000) - Prefer chunk retrieval over full document when search provides chunk_id ## When to Store Knowledge After completing significant work, evaluate: - Non-obvious solution others would benefit from? - Decision with tradeoffs worth documenting? - Reusable pattern or template? If yes, ask user before storing: > "This involved [description]. Save to neotex as [type]: [title]?" ```bash # Single item echo '{"type":"learning","title":"...","body_md":"# Title\n\n## Context\n..."}' | neotex add # Batch from JSON array echo '[{"type":"guideline","title":"A","body_md":"..."},{"type":"learning","title":"B","body_md":"..."}]' | neotex add --batch # Streaming batch from JSONL (one JSON per line, memory-efficient) cat items.jsonl | neotex add --batch --format jsonl --stream ``` **JSONL format** (one JSON object per line): ``` {"type":"guideline","title":"Item 1","body_md":"..."} {"type":"learning","title":"Item 2","body_md":"..."} ``` Use `--format jsonl --stream` for large imports to process items one at a time. ## When to Store Assets **IMPORTANT**: When users upload reference files, proactively offer to save them to neotex. Save assets when user provides: - Reference images (mockups, screenshots, diagrams) - Design files (logos, icons, UI specs) - Documentation PDFs - Configuration files for reference - Any file they want the team/AI to access later **Prompt user:** > "You uploaded [filename]. Save to neotex for future reference? I can add keywords and description for searchability." ```bash # Upload from file path neotex asset add --description "..." --keywords "ui,mockup,login" # Upload from base64 (useful for API-received content) neotex asset add --base64 "" --filename "image.png" --description "..." # Upload from stdin (raw binary) cat image.png | neotex asset add --stdin --filename "image.png" --keywords "..." # Upload from stdin with base64 encoding echo "" | neotex asset add --stdin --encoding base64 --filename "doc.pdf" # Retrieve an asset neotex asset get -o ``` **Flags for non-file uploads:** - `--base64` - Direct base64-encoded content - `--stdin` - Read from stdin - `--encoding` - Stdin encoding: `raw` (default) or `base64` - `--filename` - Required with `--base64` or `--stdin` - `--mime-type` - Optional, auto-detected from filename ## Asset Best Practices 1. **Always ask before saving** - User may not want file persisted 2. **Add descriptive keywords** - Makes assets searchable (e.g., "login, mockup, mobile, v2") 3. **Include context in description** - Why this file matters, what it shows 4. **Link to knowledge when relevant** - Associate asset with related documentation 5. **Retrieve before recreating** - Search for existing assets before generating new ones ## Knowledge Types | Type | Use For | |------|---------| | guideline | Rules to follow | | learning | Insights from experience | | decision | Architectural choices | | template | Reusable structures | | checklist | Verification steps | | snippet | Reusable code | ## Common Mistakes - **Fetching everything upfront**: Search on-demand, not at start - **Storing trivial changes**: Only lasting organizational value - **Duplicating**: Search before creating - **Storing secrets**: Never include credentials or sensitive files - **Ignoring uploaded files**: Always offer to save reference materials - **Missing keywords**: Assets without keywords are hard to find later

neotex

Installation

SKILL.md