Document agentic development

AGENTS.md

@@ -4,6 +4,10 @@
 
 This repository contains the Mintlify source for [docs.tilebox.com](https://docs.tilebox.com). Use this file to keep documentation updates consistent with the current information architecture, writing style, and tooling.
 
+## Required Writing Skill
+
+Always read and respect the `writing-technical-content` skill before writing, drafting, revising, or outlining technical documentation, guides, or long-form content in this repository.
+
 ## Information Architecture
 
 Navigation is defined in `docs.json` and currently follows this top-level structure:

agentic-development/agent-skills.mdx

@@ -0,0 +1,45 @@
+---
+title: Agent Skills
+description: Install Tilebox skills that teach AI agents how to work with Tilebox tools and workflows.
+icon: wand-magic-sparkles
+---
+
+Tilebox skills are task-level instructions for AI agents. They explain how to use the Tilebox CLI, which command patterns to prefer, and how to approach common workflows such as dataset management and job monitoring.
+
+## Install Tilebox skills
+
+Install the skills from the Tilebox skills repository.
+
+```bash
+npx skills add tilebox/skills
+```
+
+<Columns cols={1}>
+  <Card title="Tilebox skills on GitHub" icon="github" href="https://github.com/tilebox/skills" horizontal>
+    Browse the source repository for the Tilebox agent skills.
+  </Card>
+</Columns>
+
+After installation, your agent can load the relevant skill before working on a Tilebox task.
+
+## Included skills
+
+Tilebox skills cover common agent workflows around the CLI, datasets, workflows, jobs, and automations.
+
+| Skill | What it covers |
+| --- | --- |
+| `using-tilebox-cli` | Authentication, `--json`, `jq`, `agent-context`, and documentation search |
+| `managing-tilebox-datasets` | Creating schemas, updating metadata, and querying datasets |
+| `managing-tilebox-jobs` | Submitting jobs, monitoring status, reading logs, and inspecting spans |
+| `working-with-tilebox-automations` | Working with triggers, automations, and storage locations |
+| `writing-tilebox-workflows` | Writing Tilebox workflow tasks and task runners |
+
+## How to use skills with agents
+
+Ask your agent to load the most specific Tilebox skill for the task. For example, use `managing-tilebox-datasets` for schema work and `managing-tilebox-jobs` for workflow execution or observability tasks.
+
+```text Prompt
+Load the relevant Tilebox skills. Use the Tilebox CLI to submit a Sentinel-2 mosaic job, then monitor it until it completes.
+```
+
+Skills work best with the Tilebox CLI. The CLI gives the agent repeatable terminal commands, and skills tell it how to combine those commands safely. Use MCP as an alternative when the agent runs in a web or chat environment without practical terminal access.

agentic-development/ai-interfaces.mdx

@@ -0,0 +1,29 @@
+---
+title: AI interfaces
+description: Choose the right Tilebox interface for AI-assisted work.
+icon: route
+---
+
+Tilebox gives agents multiple ways to get context and take action. The right interface depends on whether the agent needs live Tilebox access, repeatable terminal commands, workflow instructions, or documentation-only context.
+
+## Interface guide
+
+| Interface | Use it for | What it gives the agent |
+| --- | --- | --- |
+| [Tilebox CLI](/agentic-development/tilebox-cli) | Default setup for coding agents, terminal operations, automation, and CI-friendly workflows | Structured command output, command discovery, and predictable inputs |
+| [Agent Skills](/agentic-development/agent-skills) | Repeated Tilebox tasks across datasets, jobs, and automations | Instructions for composing CLI commands into end-to-end workflows |
+| [Tilebox MCP](/agentic-development/tilebox-mcp) | Web-based agents, chat tools, or MCP-capable clients where terminal access is limited | Authenticated tools for datasets, workflows, and documentation search |
+| [Tilebox SDKs](/sdks/introduction) | Application code and production integrations | Language-native APIs for Python and Go |
+| [`llms-full.txt`](https://docs.tilebox.com/llms-full.txt) | Documentation-only context | A static markdown bundle of the Tilebox documentation |
+
+## How the interfaces fit together
+
+Use the CLI when an agent can run terminal commands. This is the default interface for repository-based coding agents because commands are explicit, repeatable, and easy to inspect. Use skills when the agent needs guidance for multi-step Tilebox tasks, such as creating datasets or monitoring workflow jobs.
+
+Use the MCP server when an agent cannot easily run terminal commands. This is common for web-based agents and chat tools where the agent can call hosted tools but cannot access a shell. MCP is also useful when you want an AI client to access Tilebox documentation search and live Tilebox tools without installing local software.
+
+The interfaces are complementary. For example, a coding agent can use the CLI to inspect available commands with `tilebox agent-context` and use the `managing-tilebox-jobs` skill to monitor a submitted workflow job. A web-based agent can use the MCP server for documentation search and live Tilebox access instead.
+
+## Recommended defaults
+
+For AI-assisted development in a codebase, install the CLI and Tilebox skills. Add MCP when your agent runs outside a terminal environment or when you prefer a hosted tool connection from a web or chat interface.

agentic-development/onboard-your-agent.mdx

@@ -0,0 +1,63 @@
+---
+title: Onboard your agent
+description: Configure an AI agent with the Tilebox CLI and Tilebox skills.
+icon: rocket
+---
+
+This tutorial gives an AI agent the default Tilebox setup for repository-based work: the Tilebox CLI and Tilebox skills. After completing it, your agent can inspect available CLI commands, run commands with structured output, and use Tilebox-specific skills for datasets, jobs, and automations.
+
+<Steps>
+  <Step title="Install the Tilebox CLI">
+    Install the Tilebox CLI with the install script.
+
+    ```bash
+    curl -fsSL https://cli.tilebox.com/install.sh | sh
+    ```
+
+    The CLI is the default interface for coding agents because it works in the same terminal where the agent edits files, runs tests, and applies changes.
+  </Step>
+  <Step title="Authenticate the CLI">
+    Set `TILEBOX_API_KEY` in the environment where your agent runs. You can create an API key in the [Tilebox Console](https://console.tilebox.com/settings/api-keys).
+
+    ```bash
+    export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY"
+    ```
+
+    Use a key with the smallest permissions needed for the task you want the agent to perform.
+  </Step>
+  <Step title="Install Tilebox skills">
+    Install the Tilebox skills so your agent has task-level instructions for working with the CLI and Tilebox resources.
+
+    ```bash
+    npx skills add tilebox/skills
+    ```
+
+    The skills cover CLI usage, dataset management, job monitoring, workflow authoring, and automations.
+  </Step>
+  <Step title="Optionally configure the Tilebox MCP server">
+    Configure the Tilebox MCP server when your agent cannot easily use terminal commands, for example in a web-based chat tool. The server uses OAuth, so you do not need to add API keys or headers to the configuration.
+
+    ```json
+    {
+      "mcpServers": {
+        "tilebox": {
+          "url": "https://mcp.tilebox.com/mcp"
+        }
+      }
+    }
+    ```
+
+    When the client connects, sign in with your Tilebox account and select the team the agent should use.
+  </Step>
+  <Step title="Verify the setup">
+    Ask your agent to inspect its Tilebox capabilities before assigning a larger task.
+
+    ```text Prompt
+    Check your Tilebox setup. Confirm whether the `tilebox` CLI is installed, whether you can inspect commands with `tilebox agent-context`, which Tilebox skills are available, and which datasets are available. Do not modify any Tilebox resources.
+    ```
+  </Step>
+</Steps>
+
+## Next steps
+
+Continue with [Tilebox CLI](/agentic-development/tilebox-cli) for agent-friendly command patterns, or use [AI interfaces](/agentic-development/ai-interfaces) to decide when MCP is a better fit than terminal commands.

agentic-development/overview.mdx

@@ -0,0 +1,33 @@
+---
+title: AI Overview
+description: Learn how Tilebox supports agentic development through the CLI, agent skills, the MCP server, and documentation context.
+icon: brain-circuit
+---
+
+AI-assisted development in Tilebox is built around giving agents the same operational context that developers use: current documentation, authenticated access to Tilebox resources, and predictable tools for running actions. The section explains how to connect agents to Tilebox, which interface to use for each task, and how the Tilebox CLI and skills help agents work with datasets and workflows.
+
+## How Tilebox supports agents
+
+Tilebox supports agents through a CLI-based setup. The CLI gives agents a deterministic terminal interface with structured output, machine-readable command discovery, and file-based inputs. Agent skills teach agents how to compose CLI commands into common Tilebox tasks, while the MCP server is available for AI tools where terminal access is limited, such as web-based chat agents.
+
+<Columns cols={2}>
+  <Card title="Onboard your agent" icon="rocket" href="/agentic-development/onboard-your-agent">
+    Configure an agent with the Tilebox CLI, Tilebox skills, and documentation context.
+  </Card>
+  <Card title="AI interfaces" icon="route" href="/agentic-development/ai-interfaces">
+    Decide when to use MCP, the CLI, skills, SDKs, or documentation context.
+  </Card>
+  <Card title="Tilebox MCP" icon="plug" href="/agentic-development/tilebox-mcp">
+    Connect AI tools to the Tilebox MCP server when terminal access is not available.
+  </Card>
+  <Card title="Tilebox CLI" icon="terminal" href="/agentic-development/tilebox-cli">
+    Install the CLI, authenticate it, and use agent-friendly command patterns.
+  </Card>
+  <Card title="Agent Skills" icon="wand-magic-sparkles" href="/agentic-development/agent-skills">
+    Install Tilebox skills that teach agents how to work with Tilebox tools.
+  </Card>
+</Columns>
+
+## Recommended setup
+
+Use [Onboard your agent](/agentic-development/onboard-your-agent) if you want an AI coding agent to help with Tilebox work in a repository. It covers the default setup with CLI installation, CLI authentication, Tilebox skills, and documentation context. Use the MCP setup when your agent runs in a web or chat environment where commands and terminals are not easy to use.

agentic-development/tilebox-cli.mdx

@@ -0,0 +1,70 @@
+---
+title: Tilebox CLI
+description: Install, authenticate, and use the Tilebox CLI in AI-assisted development workflows.
+icon: terminal
+---
+
+The Tilebox CLI is a command-line interface for humans, agents, and automation. It helps AI-assisted workflows by exposing Tilebox operations through explicit commands, supporting structured output, and letting agents inspect the command tree before taking action.
+
+Use the CLI as the default Tilebox interface for coding agents that can run terminal commands. It keeps actions visible in the shell, works with existing development workflows, and pairs with Tilebox skills for multi-step tasks.
+
+## Install the CLI
+
+Install the Tilebox CLI with the install script.
+
+```bash
+curl -fsSL https://cli.tilebox.com/install.sh | sh
+```
+
+## Authenticate
+
+The CLI reads the `TILEBOX_API_KEY` environment variable. Create an API key in the [Tilebox Console](https://console.tilebox.com/settings/api-keys), then export it in the shell or agent environment that runs CLI commands.
+
+```bash
+export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY"
+```
+
+Use API keys with the smallest permissions needed for the agent's task.
+
+## Discover commands with agent-context
+
+Agents should inspect the CLI instead of guessing command names and flags. The `agent-context` command returns machine-readable information about the available command tree, arguments, flags, and descriptions.
+
+```bash
+tilebox agent-context
+```
+
+Use this before asking an agent to create datasets, submit jobs, or manage automations with the CLI.
+
+## Prefer JSON output
+
+Use `--json` when the agent needs to parse command output. Structured output is easier for agents to inspect, filter, and pass to follow-up commands than terminal tables.
+
+```bash
+tilebox dataset list --json
+```
+
+## Use files and standard input for generated input
+
+For larger inputs, prefer file-based flags instead of long shell-quoted strings. The CLI supports input patterns such as `--schema-file`, `--input-file`, `--spatial-extent-file`, and `--description-file`. Many file flags also support `-` for reading from standard input.
+
+```bash
+tilebox dataset create --schema-file schema.json
+```
+
+```bash
+# Read from stdin.
+cat schema.json | tilebox dataset create --schema-file -
+```
+
+This pattern is safer for agents because generated JSON, geometry, and descriptions do not need to be embedded in one fragile shell command.
+
+## Use the CLI with Tilebox skills
+
+The Tilebox skills include guidance for using the CLI in agent workflows. Install them when you want an agent to combine CLI commands into higher-level tasks such as managing datasets, monitoring jobs, or configuring automations.
+
+```bash
+npx skills add tilebox/skills
+```
+
+After installing the skills, ask your agent to inspect `tilebox agent-context` and follow the relevant Tilebox skill before running commands that change resources. If your agent cannot use a terminal, configure the [Tilebox MCP server](/agentic-development/tilebox-mcp) instead.

agentic-development/tilebox-mcp.mdx

@@ -0,0 +1,65 @@
+---
+title: Tilebox MCP
+description: Configure the Tilebox MCP server for AI tools that support the Model Context Protocol.
+icon: plug
+---
+
+The Tilebox MCP server connects AI tools to Tilebox through the Model Context Protocol. It exposes tools for working with Tilebox datasets and workflows, and it includes documentation search so agents can retrieve current Tilebox context before answering questions or taking action.
+
+Use MCP when your agent cannot easily use terminal commands. For coding agents with shell access, the [Tilebox CLI](/agentic-development/tilebox-cli) and [Agent Skills](/agentic-development/agent-skills) are the default setup. MCP is a good fit for web-based agents, chat tools, or hosted AI clients that support MCP but do not run local commands.
+
+## What the MCP server provides
+
+The MCP server at `https://mcp.tilebox.com/mcp` provides tools for:
+
+- Accessing and interacting with Tilebox datasets and workflows
+- Searching the Tilebox documentation
+
+When an MCP-capable client has the server configured, it can invoke relevant tools during a conversation. For example, when you ask about a dataset, the agent can query the Tilebox MCP server for the current schema and include that information in its response.
+
+## Authentication
+
+The Tilebox MCP server uses OAuth. When your AI client connects, you are redirected to sign in with your Tilebox account and select a team. You do not need to configure API keys or custom headers for MCP authentication.
+
+## Configure an MCP client
+
+Add the Tilebox MCP server using the HTTP transport when your AI client supports MCP.
+
+```json
+{
+  "mcpServers": {
+    "tilebox": {
+      "url": "https://mcp.tilebox.com/mcp"
+    }
+  }
+}
+```
+
+## Configure Claude Code
+
+Run the following command to add the Tilebox MCP server to Claude Code:
+
+```bash
+claude mcp add --transport http "Tilebox" https://mcp.tilebox.com/mcp
+```
+
+## Use multiple teams
+
+If you need to access multiple Tilebox teams, add a separate MCP server entry for each team. Each entry goes through its own OAuth flow and can be authorized for a different team.
+
+```json
+{
+  "mcpServers": {
+    "tilebox-team1": {
+      "url": "https://mcp.tilebox.com/mcp"
+    },
+    "tilebox-team2": {
+      "url": "https://mcp.tilebox.com/mcp"
+    }
+  }
+}
+```
+
+<Tip>
+Use clear server names when configuring multiple teams so your agent can choose the correct Tilebox workspace for each task.
+</Tip>