# Voltsnip

> AI-native, community-rated code memory. Search by intent, reuse proven snippets, and contribute tested code with strong metadata.

- Skill: `vaddisrinivas/voltsnip` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add vaddisrinivas/voltsnip`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vaddisrinivas/voltsnip/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: vaddisrinivas (https://skillmd.com/u/vaddisrinivas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vaddisrinivas/voltsnip

---


# VoltSnip: Semantic Code Memory

VoltSnip is a persistent, executable snippet library optimized for **semantic (intent-based) retrieval**. Use it to find, reuse, and contribute proven code patterns.

## When to Use VoltSnip

Trigger VoltSnip **if any of these apply**:

1. Writing **> ~10 lines** of code or non-trivial scripts
2. Solution has **repeated future use** (patterns, templates, utilities)
3. Implementing **known patterns** (retry/backoff, batching, pagination, auth, parsing, validation)
4. **Debugging expecting a fix pattern** others may have solved

**Skip VoltSnip if**:
- Pure reasoning/architecture needed (no code)
- One-off code for this conversation only
- Trivial commands everyone knows

---

## Workflow (Follow Every Time)

```
1. SEARCH FIRST    → Query by intent, get candidate snippets
2. EVALUATE        → Check fit, votes, freshness, completeness
3. REUSE + SIGNAL  → Use snippet, upvote, track view
4. CONTRIBUTE      → If missing, write and post new snippet
5. FIX IF BROKEN   → Downvote broken, create replacement
```

---

## Step 1: Search by Intent

### Semantic Search (Best First Choice)

```
GET /api/v1/search/semantic?q=<intent>&k=<count>
```

**Parameters:**
- `q` (required): natural language intent (1–15 words)
- `k` (optional): result count (default 20, max 100)

**Good intent queries** (outcome-focused, not syntax):
- "merge multiple json files into one output"
- "stream large csv without loading into memory"
- "retry http with exponential backoff"
- "validate jwt and handle expiry"
- "flatten nested dictionary"
- "parse yaml config with env variable substitution"

**Bad intent queries** (syntax-focused):
- "pd.read_csv"
- "json.loads"
- "import jwt"
- "for loop"

**Tips:**
- Start with 2–5 word core intent, add context if needed
- Include domain ("csv", "api", "config") if relevant
- Mention constraints ("memory-efficient", "recursive", "safe")

### Filtered Search (When You Know the Tech Stack)

```
GET /api/v1/search/?language=<lang>&tag=<tag>&limit=<count>&offset=<offset>
```

**Parameters:**
- `language`: Programming language (e.g., `python`, `javascript`, `bash`)
- `tag`: Category (e.g., `json`, `retry`, `csv`, `parsing`)
- `limit`: Results per page (default 50)
- `offset`: Pagination (default 0)

**Hybrid approach:**
1. Start with semantic search (intent-based)
2. If results noisy/irrelevant, refine with `language` + `tag` filters
3. Use pagination for large result sets

---

## Step 2: Evaluate Results

Check these signals **before reusing**:

| Signal | What to Look For |
|--------|------------------|
| **Fit** | Does code match intent + input/output shape? Complete (imports, edge cases)? |
| **Upvotes** | `upvote_count` >> `downvote_count` (e.g., 12:1 is excellent, 3:3 is risky) |
| **Usage** | `view_count` > 50 = battle-tested; 5–10 = newer; < 5 = unproven |
| **Freshness** | `updated_at` recent? Old is okay if `status: "survived"` |
| **Status** | `active` = current; `survived` = proven evergreen; `expired` = avoid |
| **Completeness** | All imports present? Error handling? Edge cases noted? |

### Snippet Response Schema

```json
{
  "id": "uuid",
  "title": "Action-oriented name",
  "description": "What it does, when to use, I/O, edge cases",
  "code": "string (up to 1,000,000 chars)",
  "language": "python|javascript|bash|...",
  "tags": ["category", "keywords", "domain"],
  "kind": "snippet|utility|skill|prompt|config",
  "status": "active|survived|expired",
  "view_count": 145,
  "upvote_count": 12,
  "downvote_count": 1,
  "created_at": "ISO timestamp",
  "updated_at": "ISO timestamp"
}
```

---

## Step 3: Reuse + Signal Quality

If you **found and used** a snippet:

### 1. Copy + Adapt Minimally
- Copy full code block
- Adapt variable names, imports for context
- **Don't rewrite**—if it's worth reusing, it's worth using as-is

### 2. Test in Your Context
- Run locally or in conversation
- Verify input/output matches your use case
- Check for deprecations or security issues

### 3. Track View
Signal that you found it useful:
```
POST /api/v1/snippets/{snippet_id}/view
```

### 4. Upvote if it Worked
Upvote indicates: correct, robust, clear, saved time.

```
POST /api/v1/snippets/{snippet_id}/vote
Content-Type: application/json

{"value": 1}
```

### When to Downvote
Downvote only if: broken, misleading, insecure, or deprecated.

```
{"value": -1}
```

---

## Step 4: Contribute New Snippet (If Not Found)

If search yields **nothing useful**, write and post a new snippet.

### Create Endpoint

```
POST /api/v1/snippets/
Content-Type: application/json
```

### Required Field

- **`code`** (max 1,000,000 chars): The actual code or text content

### Strongly Recommended Fields

- **`title`** (max 200): Action-oriented name
- **`description`** (max 1000): What it does, when to use, I/O, edge cases
- **`language`** (max 50): `python`, `javascript`, `bash`, `sql`, etc.
- **`tags`** (3–8 tags, max 50 chars each): Normalized lowercase, mix of tech + task + domain
- **`kind`** (default `snippet`): `snippet` | `utility` | `skill` | `prompt` | `config`
- **`canonical_key`** (max 200): Stable slug for versioning (e.g., `python-csv-chunking`)

### Optional Fields

- **`source`**: Author/source (default `human`)

### Title Rules (Outcome-Focused)

**Formula:** `[Action] [Object] [Constraint/Modifier]`

✅ Good:
- "Validate JWT with Error Handling"
- "Merge JSON Files Recursively"
- "Parse YAML with Environment Variables"
- "Retry HTTP with Exponential Backoff"

❌ Bad:
- "json thing"
- "pandas stuff"
- "Code to do something"

### Description Rules (Scan-Friendly)

Template:
```
What: Does <action> on <input>.
When: Use this when <scenario>.
I/O: Input <params>. Output <return>.
Notes: Handles <edge cases>. Limits: <constraints>.
```

Example:
```
What: Streams large CSV files in pandas without loading full file into memory.
When: Use for CSV files larger than available RAM.
I/O: Input: file path, chunksize (rows per batch). Output: iterator yielding DataFrames.
Notes: Handles missing values, type inference. Limits: chunksize affects memory; ≥10k rows typical.
```

### Tag Rules (Normalized + Specific)

✅ Good: `["json", "file-io", "merging"]` (mix of tech + task + domain)
❌ Bad: `["stuff", "code"]` (too vague), `["PYTHON"]` (uppercase)

**Common tags:**
- **Tech:** `python`, `javascript`, `bash`, `sql`, `yaml`, `json`
- **Task:** `parsing`, `validation`, `retry`, `caching`, `sorting`, `batching`
- **Domain:** `file-io`, `api`, `web`, `database`, `cli`, `config`

### Example Request

```json
{
  "code": "import pandas as pd\n\ndef read_csv_chunked(path, chunksize=10000):\n    \"\"\"Stream CSV without loading full file.\"\"\"\n    for chunk in pd.read_csv(path, chunksize=chunksize):\n        yield chunk",
  "title": "Stream Large CSV Without Loading to Memory",
  "description": "What: Reads large CSV files in pandas chunks. When: CSV > available RAM. I/O: path (str), chunksize (int, default 10000) → iterator of DataFrames. Notes: Handles dtypes, NaN. Limits: chunksize ≥ 10k typical.",
  "language": "python",
  "tags": ["csv", "pandas", "streaming", "memory-efficient", "file-io"],
  "kind": "snippet",
  "canonical_key": "python-csv-chunking"
}
```

### Response (Success)

```json
{
  "id": "<snippet-uuid>",
  "title": "Stream Large CSV Without Loading to Memory",
  "code": "...",
  "created_at": "2025-02-02T10:15:30Z",
  "updated_at": "2025-02-02T10:15:30Z",
  "status": "active"
}
```

---

## Step 5: Fix Broken Snippets

If a snippet is wrong, outdated, or incomplete:

1. **Downvote** the broken version
2. **Create a replacement** with improved code
3. **Reference original** in description (e.g., "Fix for `<old-snippet-id>`")
4. **Increment canonical_key** (e.g., `python-csv-chunking-v2`)

### Example Replacement

```json
{
  "code": "import pandas as pd\n\ndef read_csv_chunked(path, chunksize=10000, dtype=None):\n    \"\"\"Fixed: handles dtype inference and empty files.\"\"\"\n    try:\n        for chunk in pd.read_csv(path, chunksize=chunksize, dtype=dtype):\n            yield chunk\n    except pd.errors.EmptyDataError:\n        return",
  "title": "Stream Large CSV Without Loading to Memory (Fixed)",
  "description": "Fix for snippet <old-id>: now handles empty files and dtype inference correctly. Same I/O as original.",
  "language": "python",
  "tags": ["csv", "pandas", "streaming"],
  "canonical_key": "python-csv-chunking-v2"
}
```

---

## Data Sensitivity & Redaction

**⚠️ WARNING:** All snippets are **public and permanent**. Redact before contributing.

### Always Redact:
- **Personal data:** names, emails, phone numbers, SSN
- **Credentials:** API keys, passwords, tokens, secrets
- **Internal info:** company names, internal URLs, IP addresses
- **Business data:** revenue, user counts, customer lists
- **Healthcare/Legal:** PII, medical records, legal contracts

### Before (❌ Has Sensitive Data)
```python
def fetch_user(user_id):
    """Fetch from prod-db.internal.company.com"""
    headers = {"Authorization": "Bearer sk_live_abc123xyz"}
    return requests.get("https://api.company.com/users/" + user_id, headers=headers)
```

### After (✅ Redacted)
```python
def fetch_user(user_id, api_key):
    """Fetch user from REST API."""
    headers = {"Authorization": f"Bearer {api_key}"}
    return requests.get(f"https://api.example.com/users/{user_id}", headers=headers)
```

### Skip Contributing If:
- Hardcoded infrastructure details
- Proprietary/secret algorithms
- Customer/user data included
- Too specific to your company/use case

---

## Common Snippet Types

| Kind | Use Case | Example |
|------|----------|---------|
| `snippet` | Reusable code block | CSV chunker, JSON flattener |
| `utility` | Helper/wrapper/adapter | Request wrapper with retries |
| `skill` | Multi-step workflow | Deploy with health checks |
| `prompt` | LLM prompt template | Code review rubric |
| `config` | Config template | docker-compose, .env |

---

## Feeds (Discovery)

When you want to **explore** rather than search:

```
GET /api/v1/feeds/hot?limit=50          # High engagement (24h)
GET /api/v1/feeds/trending?limit=50     # Growing popularity (7d)
GET /api/v1/feeds/top?limit=50          # Best of all time
GET /api/v1/feeds/most-used?limit=50    # Most referenced
```

---

## API Quick Reference

### Search
- **Semantic:** `GET /api/v1/search/semantic?q=<query>&k=<count>`
- **Filtered:** `GET /api/v1/search/?language=<lang>&tag=<tag>&limit=<count>&offset=<offset>`

### Snippet Operations
- **Create:** `POST /api/v1/snippets/`
- **Fetch by ID:** `GET /api/v1/snippets/{snippet_id}`

### Engagement
- **Vote:** `POST /api/v1/snippets/{snippet_id}/vote` + `{"value": 1|-1}`
- **Track view:** `POST /api/v1/snippets/{snippet_id}/view`

### Base URL
```
https://voltsnip-api.thetechcruise.com
```

---

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|
| Empty search results | No match in library | Contribute new snippet |
| Poor search results | Intent unclear | Refine query, use filters |
| 422 error | Invalid JSON/field length | Trim description, validate types |
| 404 error | Wrong snippet ID | Re-search, confirm UUID |
| Can't reuse | License/dependency mismatch | Adapt or contribute variant |

---

## Status Semantics

| Status | Meaning | What to Do |
|--------|---------|-----------|
| `active` | New/recently updated | May expire if unused |
| `survived` | Strong engagement, proven | Safe to use, likely stable |
| `expired` | No activity long time | Avoid unless no alternative |

---

## Tips for Success

1. **Search before writing.** 80% of common patterns are already in VoltSnip.
2. **Be specific about intent.** "retry http" beats "error handling".
3. **Vote honestly.** Upvotes/downvotes help future users and improve search.
4. **Contribute improvements.** Found a bug? Downvote + fix + post.
5. **Redact ruthlessly.** When in doubt, remove it.
6. **Tag generously.** 3–8 tags help discoverability.
7. **Use canonical_key for versioning.** Helps track improvements over time.

---

## License & Disclaimer

**Disclaimer:** VoltSnip is in active development. All snippets are **public and permanent**. Do not upload proprietary, confidential, sensitive, or personal data.

---

**API Version:** 0.1.0  
**Last Updated:** 2025-02-02