Summary

Agents starting fresh will hallucinate without guidance. Agent knowledge packaging bundles documentation in formats agents load automatically at conversation start: CONTEXT.md (general orientation), (repo context), and Agent Skills (SKILL.md plus optional supporting files). This eliminates discovery cost and prevents common failure modes.

CONTEXT.md: high-level orientation, credentials, invariants
AGENTS.md: commands, build/test steps, boundaries, exclusions
: portable task guidance, with optional CLI metadata extensions
Most agent frameworks auto-load these files from project root
Lead with commands in AGENTS.md - this is the most valuable content

An agent that has never used your CLI before will try to discover how it works through schema introspection, trial and error, and hallucination. A CLI that ships explicit, structured knowledge for agents to load at conversation start eliminates most of that discovery cost and prevents the most common failure modes before they occur.

Agent knowledge packaging is the practice of bundling the right information in the right format so agents start every session already knowing how to use your CLI correctly.

The Three File Formats

CONTEXT.md

A general-purpose context file that most agent frameworks will load automatically when it appears in the project root or the directory from which the CLI is run. It provides high-level orientation: what the tool does, what credentials are needed, and the most important invariants.

# mytool Context

mytool is the CLI for the Example Platform API. It manages users, DNS records,
billing, and deployments.

## Authentication

Set MYTOOL_API_KEY to your API key:
export MYTOOL_API_KEY=your_key_here

Obtain an API key at: https://app.example.com/settings/api-keys

## Important Invariants

- Always pass --dry-run before any delete or archive operation
- Always pass --json or rely on auto-detection when piping output
- Always pass --fields to limit response size (e.g., --fields id,name,status)
- The --yes flag is required for destructive operations in non-interactive contexts

## Getting the Schema

Run `mytool describe --json` to get the full command schema for any command group.

CONTEXT.md is intentionally lightweight. It orients the agent without overwhelming it. Deep workflow guidance goes in SKILL.md.

AGENTS.md

AGENTS.md is the open repo-instruction format used by coding agents. It is the primary context file agents look for in a repository.

Structure AGENTS.md around three concerns:

Setup - what environment variables and authentication the agent needs
Capabilities - what the CLI can do, organized by domain
Guardrails - what the agent must never do without specific safety steps

# mytool Agent Guide

## Setup

Required environment variables:

- `MYTOOL_API_KEY` - API key for authentication
- `MYTOOL_BASE_URL` - Override the API base URL (optional, default: https://api.example.com)

Run `mytool auth status --json` to verify authentication before starting work.

## Capabilities

### User Management

- Create, update, suspend, and delete users
- Assign roles: admin, member, viewer
- Bulk operations with --status filter

### DNS Records

- Create A, AAAA, CNAME, MX, TXT records
- Supports raw JSON payloads for full RFC 1035 compliance
- Propagation takes 0–60 seconds

### Deployments

- Trigger deployments, roll back to previous versions
- Monitor deployment status with --watch

## Guardrails

### Before any DELETE operation

1. Run with --dry-run first
2. Inspect the `would_affect` count and `preview` array
3. Check the `warnings` array for side effects
4. Only then run without --dry-run

### Before bulk operations

1. Always use --fields to limit response size
2. Always use --all with --json for streaming output
3. Verify the count with a dry-run or list operation first

### Never

- Do not pass absolute paths to --output
- Do not pass --yes without a preceding --dry-run
- Do not retry on 422 (validation failure) - fix the input instead

## Schema Discovery

```bash
# Full CLI schema
mytool describe --json

# Schema for a specific command
mytool user create --help --json
```

SKILL.md

The SKILL.md folder shape - YAML frontmatter with name/description, a body, optional scripts/, references/, and assets/ - is covered on Agent Skills; this section covers only what a CLI adds to that base shape.

Skill folders are read off disk at conversation start, loaded at runtime by agent frameworks as a skill tool surface, and attached server-side by hosted model platforms to their managed execution environments - see Agent Skills for the consumption models. Packaging a CLI's knowledge as skills therefore pays off in three places at once, without a translation layer.

A CLI skill extends the base frontmatter with fields that point at runtime introspection instead of a static description - see Schema Introspection for the schema_command/auth/capabilities fields and a worked example. Keep the base name and description valid on their own for agents that only understand the public Agent Skills format; treat the extension fields as additive.

The skill body should encode preview-then-execute pairs, not prose warnings:

# Step 1: preview
mytool users delete --status suspended --dry-run --json

# Step 2: confirm the would_affect count, read warnings
# Step 3: execute only if the preview is acceptable
mytool users delete --status suspended --yes --json

Field mask usage belongs in the skill body too - see Context Window Discipline for the --fields mechanics this invariant depends on.

Per-Command Skill Files

For complex CLIs, supplement the top-level SKILL.md with per-command skill files. These live alongside the CLI's documentation or in a skills/ directory:

mytool/
  SKILL.md             # top-level capability declaration
  AGENTS.md            # agent guardrails and setup
  skills/
    user-management.md # detailed user command workflows
    dns-records.md     # DNS-specific invariants and examples
    deployments.md     # deployment safety patterns

Per-command files can go deeper without bloating the top-level skill:

---
name: mytool-dns-records
description: DNS record commands, propagation timing, and invariants for mytool
skill: mytool/dns-records
version: 2.4.1
parent: mytool
---

# DNS Records

## Record Types

Supported: A, AAAA, CNAME, MX, TXT, SRV, CAA, NS

## Propagation Timing

DNS changes propagate within 0–60 seconds. Do not assume a record is live
immediately after creation. Use `` `mytool dns record get <id> --fields id,name,status` ``
to check propagation status.

## Invariants

- Always verify a record exists before attempting to update it
- MX records require `priority` - there is no default
- CNAME records cannot coexist with other record types at the same name
- Do not delete a record if you are unsure which service depends on it

## Proxied vs Unproxied

The `proxied` field routes traffic through the CDN. When true:

- The record's actual IP is hidden
- HTTP/HTTPS traffic is accelerated and protected
- Non-HTTP protocols (e.g., mail, SIP) must use proxied: false

## Raw Payload Example

```json
{
  "type": "A",
  "name": "api",
  "content": "203.0.113.10",
  "ttl": 300,
  "proxied": false,
  "comment": "Production API server"
}
```

Versioning and Discoverability

Skill files should be versioned and referenced from the CLI's machine-readable schema:

{
  "name": "mytool",
  "version": "2.4.1",
  "skill_files": [
    {
      "path": "SKILL.md",
      "version": "2.4.1",
      "url": "https://raw.githubusercontent.com/example/mytool/v2.4.1/SKILL.md"
    },
    {
      "path": "skills/user-management.md",
      "version": "2.4.1",
      "url": "https://raw.githubusercontent.com/example/mytool/v2.4.1/skills/user-management.md"
    }
  ]
}

An agent can discover skill file URLs from the schema, fetch only the skills relevant to its current task, and load them into context selectively.

The "Always Use" Pattern

The most impactful invariants are those that prevent common, recoverable mistakes. Encode these as explicit rules in every skill file:

## Invariants (Always Follow)

- **Always `--dry-run` before delete**: `` `mytool <resource> delete ... --dry-run --json` ``
- **Always `--fields` on list commands**: Minimum `--fields id,name,status`
- **Always check `warnings` in dry-run output** before executing
- **Always `--json`** in non-interactive scripts (or rely on TTY auto-detection)
- **Never `--yes` without a preceding `--dry-run`** for bulk operations
- **Never absolute paths** for `--output` - use relative paths only

These invariants reduce the need for the agent to reason about safety on every call.

Scoring Rubric

This axis is part of the Agent DX CLI Scale.

Score	Criteria
0	Only `--help` and a docs site. No agent-specific context files.
1	A `CONTEXT.md` or `AGENTS.md` with basic usage guidance.
2	Agent Skills covering per-command or per-API-surface workflows and invariants.
3	Comprehensive skill library encoding agent-specific ("always use --dry-run", "always use --fields"). Skills are versioned, discoverable, and follow the public Agent Skills format.

Checklist

AGENTS.md in the repository root with setup instructions, capabilities, and guardrails
CONTEXT.md in the repository root for agent frameworks that load it automatically
SKILL.md with at least name and description frontmatter
CLI metadata extension points to the live introspection command (schema_command or equivalent)
Per-command or per-domain skill files in a skills/ directory for complex CLIs
Skill files include versioning and are referenced from the CLI's schema output
"Always use" invariants are encoded explicitly - --dry-run, --fields, --json
Skill files are updated as part of the release pipeline, not manually

Schema Introspection - CLI schema commands and optional skill metadata
Agent Skills - portable skill folder format
Context Window Discipline - why --fields invariants matter
Safety Rails - and confirmation patterns to encode as invariants
The Agent DX CLI Scale - full scoring framework

Agent Knowledge Packaging