Lab Notes

Tooling Layer

CLI tools, MCP adapters, skills, specs, AutoSkills, and patterns for creating new tools.

The tooling layer converts repeatable tasks into callable capabilities. Some are local CLI-first tools; others are external service adapters exposed through MCP. In both cases, the goal is to keep the agent from depending only on generative reasoning.

Local Agent Tools

The local tools toolkit acts as the base layer. It includes:

  • tools.json as the tool index;
  • README.md as the general guide;
  • AGENTS.md with rules for agents;
  • SKILL.md for toolkit activation;
  • stack-template/bootstrap.py for creating new tools;
  • auxiliary usage telemetry tools;
  • documentation for the background research worker.

MCP Adapters

Not every tool is a local CLI utility. Some capabilities are exposed through MCP adapters, especially when the system needs to call external research services. This keeps provider-specific code behind a stable tool boundary and lets agents treat external research as another callable capability.

Standard Tool Structure

For local CLI utilities, the standard structure is:

tool-name/
|-- main.py
|-- lib.py
|-- requirements.txt
|-- package.json
|-- pyproject.toml
|-- README.md
|-- SKILL.md
|-- TOOL.md
`-- tests/

Each file has a role:

FilePurpose
main.pyExecutable CLI entry point.
lib.pyDomain logic when the tool grows.
requirements.txtMinimal Python dependencies.
package.jsonAutoSkills integration.
pyproject.tomlModern Python configuration.
README.mdHuman-facing usage.
SKILL.mdAgent-facing usage: when to activate it and how to run it.
TOOL.mdTechnical specification written before implementation.
tests/Basic or advanced verification.

Creation Flow

Loading diagram…
Tool creation flow: specify, scaffold, implement, test, register, and review.

Media Automation Tools

The media toolkit applies the same pattern to a concrete domain: movie and series search and management.

ToolFunction
torrent-finderSearch sources by title, year, quality, or codec.
subtitle-finderSearch subtitles.
dubbed-finderDetect releases with dubbed audio.
media-infoExtract technical video metadata.
media-organizerOrganize downloaded media.

Why CLI-First

A CLI-first approach provides:

  • reproducibility;
  • testability;
  • execution by humans and agents;
  • observable logs and errors;
  • simple integration with other workflows;
  • less dependence on visual interfaces.

Main Lesson

An agent tool should not be only code. It should include its discovery path, usage contract, agent context, and verification strategy.

References