Skip to content

feat: add SeekDB management skill for Claude Code #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
NTLx wants to merge 2 commits into from
Closed

feat: add SeekDB management skill for Claude Code #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
26f5a3f
chore: add seekdb configuration templates and gitignore rules
NTLx Jan 28, 2026
aacf8e7
feat: add SeekDB management skill for Claude Code
NTLx Jan 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions .claude/skills/seekdb-management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
name: seekdb-management
description: Manage SeekDB configuration and environment
---

# seekdb-management

A skill to manage SeekDB environment settings.

## Commands

### /setup-seekdb

Sets up the SeekDB connection environment by creating a `.env` file.

#### Logic

1. **Check Environment**: Check if `.env` file exists in the project root.
2. **Handle Missing Config**: If `.env` does not exist:
- Call `AskUserQuestion` to ask the user for:
- `SEEKDB_HOST`
- `SEEKDB_PORT`
- `SEEKDB_TOKEN`
- **Hint**: Provide a friendly hint to the user: "For evaluation, you might use biodev.cm.com:2881".
3. **Create File**: Use the `Write` tool to create a `.env` file in the project root with the following format:
```env
SEEKDB_HOST=<collected_host>
SEEKDB_PORT=<collected_port>
SEEKDB_TOKEN=<collected_token>
```
4. **Git Safety**: Read the `.gitignore` file to verify if `.env` is properly ignored to prevent accidental leaks. If it's not ignored, warn the user and suggest adding it.
5. **Success Confirmation**: Confirm to the user that the environment has been successfully configured.
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
/target
/record
.env
config.toml

# macOS
.DS_Store
Expand Down
50 changes: 50 additions & 0 deletions docs/plans/2026-01-28-seekdb-skill-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Claude Code SeekDB Skill Design

## 1. Overview
This design outlines a Claude Code Skill for the `echokit_server` project to facilitate the integration and management of SeekDB. It serves two primary scenarios:
- **Scenario A (Setup Wizard)**: Guided interactive configuration for new environments.
- **Scenario B (Self-Healing/Sync)**: Automatic detection and correction of configuration drifts.

## 2. Architecture
The system relies on a "Template + Local Override" pattern:
- **Source of Truth (Private)**: `.env` file (local-only, git-ignored).
- **Standards (Public)**: `.env.example` and `config.toml.example` (committed).
- **Consumer**: `config.toml` (generated locally from templates and `.env`).

## 3. Components

### 3.1 Claude Code Skill (`SKILL.md`)
A specialized skill file in `.claude/skills/seekdb-management.md` defining commands:
- `/setup-seekdb`: Interactive wizard to collect host, port, and token.
- `/sync-seekdb`: Regenerates `config.toml` from templates using current `.env` values.

### 3.2 Templates
- `src/resources/.env.example`: Defines required environment variables.
- `src/resources/config.toml.example`: Contains placeholders like `{{SEEKDB_HOST}}`.

## 4. Workflows

### 4.1 Interactive Setup (`/setup-seekdb`)
1. Check for `.env`. If missing, prompt user via `AskUserQuestion`.
2. Offer suggested values (e.g., from the current user session context) as non-persistent placeholders.
3. Write variables to `.env`.
4. Verify `.env` is in `.gitignore`; update `.gitignore` if necessary.

### 4.2 Sync & Self-Healing
1. **Detection**: When AI performs SeekDB tasks, it verifies if `config.toml` exists and matches `.env`.
2. **Generation**: Skill reads `.env` and `config.toml.example`, performs string replacement, and writes to `config.toml`.
3. **Guard**: Adds a header comment: `# [LOCAL_ONLY] GENERATED BY CLAUDE CODE - DO NOT COMMIT`.

### 4.3 Environment Abstraction (The "Proxy" Logic)
- Skill commands will NOT hardcode `proxy`.
- Instead, the Skill will probe for the command via `command -v proxy`.
- If found, it prefixes bash calls dynamically: `proxy && ...`.
- This ensures portability across different development environments.

## 5. Security & Safety
- **Anti-Commit Guard**: Skill logic in `/commit` (if extended) or during file generation will warn if `.env` or `config.toml` are staged for commit.
- **Privacy**: No hardcoded IP addresses or tokens in the code or `SKILL.md`.

## 6. Validation
- After generation, the Skill performs a connectivity test (e.g., `nc` or a simple health check API call) to the SeekDB instance.
- Success/Failure feedback is provided to the user.
4 changes: 4 additions & 0 deletions src/resources/.env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# SeekDB Configuration
SEEKDB_HOST=your_host_here
SEEKDB_PORT=2881
SEEKDB_TOKEN=your_token_here
4 changes: 4 additions & 0 deletions src/resources/config.toml.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
[seekdb]
host = "{{SEEKDB_HOST}}"
port = {{SEEKDB_PORT}}
token = "{{SEEKDB_TOKEN}}"