Lucid Skill

AI-native data analysis via natural language. Connect Excel, CSV, MySQL, PostgreSQL data sources and query with SQL. Use when: (1) user asks to query, analyz...

Security Scan

The skill's code, install spec, and runtime instructions are consistent with a CLI/MCP tool for read-only data exploration (Excel/CSV/MySQL/Postgres) — nothing indicates intentional misdirection — but there are a few implementation and privacy/security details you should review before installing or connecting sensitive systems.

Purpose & Capability

Name/description match the code and runtime instructions: a CLI/MCP tool that connects CSV/Excel and relational DBs, builds a DuckDB-backed catalog, offers semantic search and read-only SQL. Required binary 'lucid-skill' and the listed install step align with providing this CLI.

Instruction Scope

SKILL.md limits scope to read-only SELECT/WITH queries and describes connecting local files and DBs and starting an MCP stdio server. This matches the source: the CLI and server handlers expose tools to connect sources, list/describe tables, and execute queries. Two items to note: (1) the CLI/server persist a catalog and semantic files under ~/.lucid-skill/ and advertises 'auto-restore' of previous connections — but passwords are claimed not to be stored (see environment_proportionality). (2) Several code paths interpolate file paths and SQL identifiers into DuckDB SQL via Python f-strings (e.g., read_csv_auto('path') and read_xlsx('path')), which can be brittle if inputs contain unexpected characters (single quotes) and could result in local SQL parsing issues or unintended behavior; this is a coding/escaping vulnerability rather than evidence of malicious intent.

Install Mechanism

Install spec uses a 'uv' package install of 'lucid-skill' and the skill bundle includes full Python source and a pyproject. There are no opaque remote-download URLs or URL shorteners in the install spec. The install approach is proportionate for a CLI tool; verify the uv package source/trust before installing.

Credentials

The skill declares no required environment variables or credentials, which is consistent. It documents optional env vars (LUCID_DATA_DIR, LUCID_EMBEDDING_ENABLED). Database credentials are accepted at connect-time (CLI options / tool params) and the CatalogStore strips 'password' before writing source config. Two cautions: (1) the 'auto-restore' feature raises the question of how DB connections are re-established without stored passwords — startup logic may attempt to restore only file-based sources or may fail for DBs (the code can surface failures). (2) Enabling embeddings triggers a large (~460 MB) model download from external model hosts when enabled; that requires network access and disk space and should be acceptable only if you trust the model source.

Persistence & Privilege

The skill persists a catalog and semantic YAML under ~/.lucid-skill/ (configurable via LUCID_DATA_DIR), and may download models into a models cache. It does not request elevated OS privileges or set always:true. The MCP server runs over stdio for integrations (expected) — be aware that autonomous agent invocation will allow the agent to call the tool handlers to access local files and databases if you grant it access.

Assessment

This skill appears to do what it says: a read-only data exploration CLI and MCP server. Before installing or connecting sensitive data: 1) Verify the package source for 'lucid-skill' (the uv install) and prefer pinned releases from a trusted registry. 2) Inspect startup.auto_restore_connections (or try a dry run) to confirm DB passwords are not persisted and to see which connections are auto-restored. 3) Be aware that enabling embeddings downloads a large model from the network — confirm the model source and allow adequate disk space. 4) Avoid passing untrusted/remote-controlled file paths; some connectors interpolate paths into SQL with simple f-strings and may behave incorrectly with specially crafted paths (e.g., containing single quotes). 5) Run the tool in an isolated environment or container if you intend to connect production databases. 6) If you do not want the agent to call the skill autonomously, restrict invocation policies in your agent/platform. If you want, I can: point to the exact lines that interpolate paths/identifiers, summarize startup.auto_restore behavior if you provide startup.py, or produce a short checklist to harden local deployment.

Connect data → infer semantics → query with natural language → get answers.

All output is JSON unless noted. No API key needed.

Quick Start

lucid-skill connect csv /path/to/sales.csv     # Connect data
lucid-skill overview                            # Check connected sources
lucid-skill search "月度销售额趋势"              # Find relevant tables + suggested SQL
lucid-skill query "SELECT month, SUM(amount) FROM sales GROUP BY month"  # Execute

Core Commands

Command	Purpose
overview	Show all connected sources, tables, semantic status
connect csv/excel/mysql/postgres	Connect a data source
tables	List all tables with row counts
describe <table>	Column details + sample data + semantics
profile <table>	Deep stats: null rate, distinct, min/max, quartiles
init-semantic	Export schemas for semantic inference
update-semantic <file|->	Save semantic definitions (JSON from file or stdin)
search <query> [--top-k N]	Natural language → relevant tables + JOIN hints + metric SQL
join-paths <a> <b>	Discover JOIN paths between two tables
domains	Auto-discovered business domains
query <sql> [--format json|md|csv]	Execute read-only SQL
serve	Start MCP Server (stdio JSON-RPC)

For full command reference with all parameters: read references/commands.md

Smart Query Pattern (Recommended)

When a user asks a data question:

1. lucid-skill search "关键词" — find relevant tables, suggestedJoins, suggestedMetricSqls
2. If multi-table: lucid-skill join-paths table_a table_b — get JOIN SQL
3. Compose SQL from the returned context
4. lucid-skill query "SELECT ..." — execute and present results

Semantic Layer Setup

First-time setup to enable intelligent search:

lucid-skill init-semantic                               # Export schemas
# Analyze output → infer business meanings for each column
echo '{"tables":[...]}' | lucid-skill update-semantic -  # Save semantics

For JSON schema details: read references/json-schema.md

Key Tips

• Auto-restore: Previous connections survive restarts. Always overview first to check existing state.
• Read-only: Only SELECT allowed. INSERT/UPDATE/DELETE/DROP are blocked.
• Semantic files: Stored in ~/.lucid-skill/semantic_store/ (YAML, human-readable).
• Data directory: ~/.lucid-skill/ (override with LUCID_DATA_DIR env var).
• Embedding: Set LUCID_EMBEDDING_ENABLED=true for better multilingual search (downloads ~460 MB model on first use).
• No credentials stored: Database passwords are never written to disk.
• MCP mode: lucid-skill serve starts stdio JSON-RPC server for MCP integrations.

Detailed References

• references/commands.md — Full CLI command reference with all parameters
• references/json-schema.md — update-semantic JSON format specification
• references/workflow.md — Multi-step workflow guides (first-time setup, returning sessions, multi-source)