Tool Structure

The standard layout for a CLI tool. The files, the directories, the conventions, and the documentation requirements.

Purpose

This page documents the standard layout for a CLI tool in the lab. Every CLI tool follows the same structure to make it easy to find, read, test, and integrate.

The structure is enforced by the CLI Python tool template. A new tool is created by copying the template and renaming the relevant files.

Directory layout

tool-name/
├── __init__.py             ← empty, marks the package
├── main.py                 ← CLI entry point
├── lib.py                  ← core logic (optional)
├── cli.py                  ← Click commands (optional)
├── requirements.txt        ← Python dependencies
├── pyproject.toml          ← Python project config
├── package.json            ← AutoSkills (project context for the sub-agent)
├── README.md               ← user-facing documentation
├── TOOL.md                 ← technical specification
├── SKILL.md                ← activation by the Coordinator
├── AGENTS.md               ← instructions for the coding sub-agent
├── .env.example            ← example environment variables
├── src/                    ← additional modules (optional)
│   ├── __init__.py
│   ├── api.py
│   ├── cache.py
│   └── ...
├── tests/                  ← unit tests
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_main.py
│   ├── test_lib.py
│   └── ...
├── skills/                 ← related skills (optional)
│   └── skill-name/
│       └── SKILL.md
├── docs/                   ← additional documentation (optional)
│   ├── README.md
│   ├── architecture.md
│   └── ...
└── examples/               ← usage examples (optional)
    ├── example-1.md
    └── ...

The structure is a generalization of the lab's real tools (e.g., torrent-finder, subtitle-finder).

Required files

Every tool must have:

main.py — the CLI entry point.
requirements.txt — the Python dependencies.
pyproject.toml — the Python project config.
package.json — the AutoSkills context.
README.md — the user-facing documentation.
TOOL.md — the technical specification.
SKILL.md — the activation file.
AGENTS.md — the instructions for the coding sub-agent.
tests/ — the unit tests.

A tool without these files is incomplete.

Optional files

A tool may have:

lib.py — the core logic, separated from the CLI glue.
cli.py — the Click commands, separated from main.py.
.env.example — example environment variables.
src/ — additional modules.
skills/ — related skills.
docs/ — additional documentation.
examples/ — usage examples.

The optional files are added when the tool grows. A small tool does not need them.

File contents

`main.py`

The CLI entry point. Typical structure:

#!/usr/bin/env python3
"""Tool Name — short description."""
 
import argparse
import json
import sys
from pathlib import Path
 
from tool_name.lib import do_something
 
 
def main():
    parser = argparse.ArgumentParser(description="Tool Name")
    parser.add_argument("query", help="The search query")
    parser.add_argument("--limit", type=int, default=10, help="Max results")
    parser.add_argument("--format", choices=["json", "text"], default="text")
    args = parser.parse_args()
 
    result = do_something(args.query, limit=args.limit)
 
    if args.format == "json":
        print(json.dumps(result, indent=2))
    else:
        for item in result:
            print(f"- {item['name']}: {item['url']}")
    return 0
 
 
if __name__ == "__main__":
    sys.exit(main())

The main.py should be small. The core logic should be in lib.py.

`lib.py`

The core logic. Typical structure:

"""Core logic for Tool Name."""
 
from typing import Any
import requests
 
 
def do_something(query: str, *, limit: int = 10) -> list[dict[str, Any]]:
    """The tool's main capability.
 
    Args:
        query: The search query.
        limit: The maximum number of results.
 
    Returns:
        A list of result dictionaries.
 
    Raises:
        ValueError: If the query is invalid.
        ConnectionError: If the upstream is unreachable.
    """
    if not query:
        raise ValueError("query is required")
 
    response = requests.get(
        "https://api.example.com/search",
        params={"q": query, "limit": limit},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

The lib.py is pure logic. It does not depend on argparse or any CLI framework.

`requirements.txt`

The Python dependencies. One per line:

requests>=2.28
beautifulsoup4>=4.11
lxml>=4.9
pydantic>=2.0

Pin the major version. Pin the minor version when the API is unstable.

`pyproject.toml`

The Python project config. Typical:

[project]
name = "tool-name"
version = "0.1.0"
description = "Short description"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.28",
    "pydantic>=2.0",
]
 
[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "pytest-cov>=4.0",
]
 
[build-system]
requires = ["setuptools>=68.0"]
build-backend = "setuptools.build_meta"

`package.json` (AutoSkills)

The AutoSkills context. This is a small JSON file that the coding sub-agent uses to understand the project:

{
  "name": "tool-name",
  "description": "Short description",
  "version": "0.1.0",
  "type": "python-cli",
  "entry": "main.py",
  "skills": ["python-patterns", "python-testing"],
  "tags": ["media", "search", "movies"]
}

The skills field is the list of skills the sub-agent should activate. The tags field is the list of tags the Coordinator uses to find the tool.

`README.md`

The user-facing documentation. Typical sections:

Title and short description.
Installation.
Usage (with examples).
Configuration.
Limitations.
License.

`TOOL.md`

The technical specification. The format is documented in Tool Spec.

`SKILL.md`

The activation file. The format is documented in Tool Spec.

`AGENTS.md`

The instructions for the coding sub-agent. Typical sections:

Project overview.
Conventions.
File structure.
How to add a new command.
How to add a new dependency.
How to run the tests.

Tests

The tests/ directory contains the unit tests. The lab uses pytest for Python tools. The tests are organized by module:

tests/test_main.py — tests for the CLI entry point.
tests/test_lib.py — tests for the core logic.
tests/test_<module>.py — tests for additional modules.

The tests follow the conventions in Tool Spec → Tests.

Skills

A tool may have one or more associated skills. A skill is a markdown file that the Coordinator activates when the user's request matches the skill's trigger phrases.

The skills live in skills/<skill-name>/SKILL.md. The format is documented in Tool Spec → SKILL.md.

Examples

The examples/ directory contains usage examples. Examples are markdown files that show how to use the tool in a specific scenario.

The format is:

# Example: <title>
 
## Scenario
[What the example does.]
 
## Command
[The command to run.]
 
## Expected output
[What the user should see.]