agentic-hdf5

Agentic HDF5

A set of expansions and tools for Claude Code that enable AI agents to work at a high level with HDF5 data and files. Provides 10+ tools, 14+ skills, support for semantic metadata, and natural language search of vectorized semantic metadata.

Prerequisites

Claude Code must be installed. The MCP server is fetched and run via uvx, so uv must also be installed — all Python dependencies (h5py, numpy, matplotlib, etc.) are resolved automatically.

Installation

Run these slash commands inside a Claude Code session to register the plugin marketplace and install the plugin:

# Add the marketplace (one-time)
/plugin marketplace add mattjala/agentic-hdf5

# Install the plugin
/plugin install ahdf5-plugin@agentic-hdf5

This gives you all 14+ skills and 10 MCP tools automatically.

For development/testing, clone the repo and load the plugin directly:

git clone https://github.com/mattjala/agentic-hdf5.git
claude --plugin-dir ./agentic-hdf5/plugin

Architecture

Agentic HDF5 is composed of two complementary layers — tools and skills — that can be used independently or together.

Tools

Tools are Python functions that agents call to perform concrete operations on HDF5 files. They handle the actual file I/O: reading metadata, rechunking datasets, applying compression filters, writing semantic metadata, generating visualizations, and running semantic searches. Tools live in the tools/ directory and are registered in tools/tool_catalog.json.

Skills

Skills are curated knowledge documents that teach the agent how and when to apply HDF5 best practices. They are loaded on-demand when a user's request matches the skill's domain, giving the agent expert-level guidance without bloating its context on every interaction. Skills live in .claude/skills/.

How They Work Together

Tools and skills are designed to complement each other but neither requires the other:

• Skills alone — An agent can use skill knowledge to advise on HDF5 best practices (e.g., recommending a chunk layout) without modifying any files.
• Tools alone — An agent can call tools to inspect, optimize, or annotate files using the tool's built-in logic, without loading any skill context.
• Skills + Tools — The most powerful mode. A skill provides the agent with expert knowledge (e.g., chunking strategies for cloud access patterns), and the agent then uses tools to apply that knowledge to specific files (e.g., rechunking a dataset with the recommended layout).

Semantic Metadata (SMD)

Semantic metadata attributes (ahdf5-smd-*) attach human-readable, structured descriptions to HDF5 objects — describing what data represents, its provenance, units, and scientific significance. SMD bridges the gap between raw array data and human understanding.

See docs/semantic-metadata.md for the full specification.

Vectorized Semantic Metadata (VSMD)

VSMD converts text-based SMD into vector embeddings stored directly in the HDF5 file, enabling natural language search over datasets. An agent (or user) can query "temperature measurements in Celsius" and retrieve the most semantically relevant objects — without needing to know paths or attribute names.

See docs/vectorized-semantic-metadata.md for the design document.

Testing

python -m pytest tests/

Agent Tool Selection Evaluation

The tests/agent_tool_selection/ suite evaluates whether Claude models correctly identify the right HDF5 tool from natural language prompts. Run from a normal terminal (not inside Claude Code):

pytest -m agent tests/agent_tool_selection/ -v --model haiku

See tests/agent_tool_selection/RESULTS.md for full methodology and detailed results across prompt modes.