doc: add skills documentation (#73)

nicoloboschi · web-flow · commit 36e48a71668d · 2025-12-23T15:42:27.000+01:00
* doc: add skills documentation

* doc: add skills documentation
diff --git a/hindsight-docs/docs/sdks/integrations/skills.md b/hindsight-docs/docs/sdks/integrations/skills.md
@@ -0,0 +1,121 @@
+---
+sidebar_position: 3
+---
+
+# Skills
+
+Hindsight provides an Agent Skill that gives AI coding assistants persistent memory across sessions. Skills are reusable prompt templates that agents can load when needed to gain specialized capabilities.
+
+## Supported Platforms
+
+| Platform | Skills Directory |
+|----------|-----------------|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `~/.claude/skills/` |
+| [OpenCode](https://github.com/opencode-ai/opencode) | `~/.opencode/skills/` |
+| [Codex CLI](https://github.com/openai/codex) | `~/.codex/skills/` |
+
+## Quick Install
+
+```bash
+curl -fsSL https://hindsight.vectorize.io/get-skill | bash
+```
+
+The installer will:
+1. Prompt you to select your AI coding assistant
+2. Run the LLM provider configuration
+3. Install the skill to the appropriate directory
+
+### Install for a Specific Platform
+
+```bash
+# Claude Code
+curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --app claude
+
+# OpenCode
+curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --app opencode
+
+# Codex CLI
+curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --app codex
+```
+
+## What the Skill Provides
+
+Once installed, your AI assistant gains the ability to:
+
+- **Retain** - Store user preferences, learnings, and procedure outcomes
+- **Recall** - Search for relevant context before starting tasks
+- **Reflect** - Synthesize memories into contextual answers
+
+The skill uses the `hindsight-embed` CLI which runs a lightweight local daemon with an embedded database.
+
+## How Skills Work
+
+Skills are **model-invoked**, meaning the AI assistant automatically decides when to use them based on the context of your conversation. You don't need to explicitly trigger the skill.
+
+The assistant will:
+- **Store** when you share preferences, when tasks succeed/fail, or when learnings emerge
+- **Recall** before starting non-trivial tasks to get relevant context
+
+### What Gets Stored
+
+The skill is optimized to store:
+
+| Category | Examples |
+|----------|----------|
+| **User Preferences** | Coding style, tool preferences, language choices |
+| **Procedure Outcomes** | Commands that worked, configurations that resolved issues |
+| **Learnings** | Bug solutions, workarounds, architecture decisions |
+
+## Architecture
+
+```
+AI Coding Assistant
+    │
+    ▼
+Hindsight Skill (SKILL.md)
+    │
+    ▼
+hindsight-embed CLI
+    │
+    ▼
+Local Daemon (auto-started)
+    │
+    ▼
+Embedded PostgreSQL (~/.pg0/hindsight-embed/)
+```
+
+All data stays on your machine. The daemon auto-starts when needed and shuts down after inactivity.
+
+## Configuration
+
+The skill uses configuration stored in `~/.hindsight/config.env`. Reconfigure anytime:
+
+```bash
+uvx hindsight-embed configure
+```
+
+## Troubleshooting
+
+### Skill not activating
+
+The skill activates based on its description matching your request. Try being explicit:
+- "Remember that..." triggers storage
+- "What do you know about..." triggers recall
+
+### Daemon issues
+
+```bash
+uvx hindsight-embed daemon status
+uvx hindsight-embed daemon logs
+```
+
+### Reconfigure
+
+```bash
+uvx hindsight-embed configure
+```
+
+## Requirements
+
+- Python 3.10+ (for `uvx`)
+- An LLM API key (OpenAI, Anthropic, Groq, etc.)
diff --git a/hindsight-docs/sidebars.ts b/hindsight-docs/sidebars.ts
@@ -172,6 +172,11 @@ const sidebars: SidebarsConfig = {
           id: 'sdks/integrations/litellm',
           label: 'LiteLLM',
         },
+        {
+          type: 'doc',
+          id: 'sdks/integrations/skills',
+          label: 'Skills',
+        },
       ],
     },
   ],
diff --git a/hindsight-docs/static/get-skill b/hindsight-docs/static/get-skill
@@ -65,77 +65,78 @@ print_banner() {
 # Embedded SKILL.md content
 SKILL_CONTENT='---
 name: hindsight
-description: Give your agent persistent memory that works like human memory. Store facts, preferences, and context that persist across sessions.
+description: Store user preferences, learnings from tasks, and procedure outcomes. Use to remember what works and recall context before new tasks.
 ---
 
 # Hindsight Memory Skill
 
-You have access to persistent memory via the `hindsight-embed` CLI. Use it to remember important information about the user and recall it when relevant.
-
-## Setup (first time only)
-
-Run: `uvx hindsight-embed configure`
-
-This will configure your LLM provider and start a local daemon that manages your memory bank.
+You have persistent memory via the `hindsight-embed` CLI. **Proactively store learnings and recall context** to provide better assistance.
 
 ## Commands
 
-The CLI uses a bank ID to organize memories. Use `default` for general memories or create project-specific banks.
-
 ### Store a memory
 
-Use `memory retain` to store important facts, preferences, decisions, or context:
+Use `memory retain` to store what you learn:
 
 ```bash
-uvx hindsight-embed memory retain default "User prefers dark mode for all UIs"
-uvx hindsight-embed memory retain default "Project uses Python 3.11 with FastAPI" --context work
-uvx hindsight-embed memory retain myproject "API uses JWT authentication"
+uvx hindsight-embed memory retain default "User prefers TypeScript with strict mode"
+uvx hindsight-embed memory retain default "Running tests requires NODE_ENV=test" --context procedures
+uvx hindsight-embed memory retain default "Build failed when using Node 18, works with Node 20" --context learnings
 ```
 
 ### Recall memories
 
-Use `memory recall` to search for relevant memories before starting tasks:
+Use `memory recall` BEFORE starting tasks to get relevant context:
 
 ```bash
-uvx hindsight-embed memory recall default "What are the user'"'"'s UI preferences?"
-uvx hindsight-embed memory recall default "What tech stack does this project use?"
+uvx hindsight-embed memory recall default "user preferences for this project"
+uvx hindsight-embed memory recall default "what issues have we encountered before"
 ```
 
 ### Reflect on memories
 
-Use `memory reflect` for contextual answers that synthesize multiple memories:
+Use `memory reflect` to synthesize context:
 
 ```bash
-uvx hindsight-embed memory reflect default "How should I set up the dev environment?"
+uvx hindsight-embed memory reflect default "How should I approach this task based on past experience?"
 ```
 
-### Other commands
+## IMPORTANT: When to Store Memories
 
-```bash
-uvx hindsight-embed bank list              # List all memory banks
-uvx hindsight-embed daemon status          # Check daemon status
-uvx hindsight-embed --help                 # Full CLI help
-```
+**Always store** after you learn something valuable:
+
+### User Preferences
+- Coding style (indentation, naming conventions, language preferences)
+- Tool preferences (editors, linters, formatters)
+- Communication preferences
+- Project conventions
+
+### Procedure Outcomes
+- Steps that successfully completed a task
+- Commands that worked (or failed) and why
+- Workarounds discovered
+- Configuration that resolved issues
 
-## When to Use
+### Learnings from Tasks
+- Bugs encountered and their solutions
+- Performance optimizations that worked
+- Architecture decisions and rationale
+- Dependencies or version requirements
 
-### Store memories when you learn:
-- User preferences (coding style, tools, UI preferences)
-- Project context (tech stack, architecture decisions)
-- Personal information the user shares (name, role, company)
-- Important decisions or outcomes
+## IMPORTANT: When to Recall Memories
 
-### Recall memories when:
-- Starting a new task (get relevant context first)
-- Making decisions that should consider user preferences
-- Working on a project where past context would help
+**Always recall** before:
+- Starting any non-trivial task
+- Making decisions about implementation
+- Suggesting tools, libraries, or approaches
+- Writing code in a new area of the project
 
 ## Best Practices
 
-1. **Be specific**: Store "User prefers 2-space indentation" not "User has preferences"
-2. **Recall first**: Before starting tasks, recall relevant context
-3. **Use context tags**: Organize with `--context` (work, personal, preferences)
-4. **Use project banks**: Create separate banks for different projects
+1. **Store immediately**: When you discover something, store it right away
+2. **Be specific**: Store "npm test requires --experimental-vm-modules flag" not "tests need a flag"
+3. **Include outcomes**: Store what worked AND what did not work
+4. **Recall first**: Always check for relevant context before starting work
 '
 
 # Get skills directory for app (bash 3.x compatible)
diff --git a/uv.lock b/uv.lock
