zvec-agent-skills: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code when working with code in this repository.

Overview

This repository contains AI Agent skills for Zvec vector database. It provides complete technical guidance for building vector search applications with Zvec, supporting Python and Node.js development environments.

Package Name: @zvec/agent-skills

GitHub: https://github.com/zvec-ai/agent-skills

Commands

# Install dependencies
bun install

# Build skills (compiles templates + code examples into skills/ output)
bun run build

# Pre-publish build (runs automatically before npm publish)
npm run prepublishOnly

Architecture

Build System

The build process (scripts/build-skills.ts) transforms source files into distributable skills:

1. Source location: src/zvec/ contains templates, code examples, and general docs
2. Output location: skills/zvec/ contains the built skill files
3. Template processing: Templates in src/zvec/templates/*.md contain {{CODE:snippet-name}} placeholders
4. Code snippets: Code files in src/zvec/code/{typescript,python}/ define snippets with @snippet:name and @end markers
5. Build output: Each template generates two files: skills/zvec/<topic>/python.md and typescript.md

Directory Structure

zvec-agent-skills/
├── src/zvec/                  # Source files
│   ├── SKILL.md               # Skill main description
│   ├── templates/             # Markdown templates with {{CODE:*}} placeholders
│   ├── code/
│   │   ├── typescript/        # .ts files with @snippet markers
│   │   └── python/            # .py files with @snippet markers
│   └── general/               # Language-agnostic docs
├── skills/zvec/               # Built output (generated, don't edit directly)
├── scripts/
│   └── build-skills.ts        # Build script
├── .github/workflows/         # CI/CD workflows
├── package.json               # Package config (@zvec/agent-skills)
└── README.md                  # User documentation