Agent concepts

A Harnest agent is an inspectable directory. Each concept has one conventional location:

Concept	Project source	Purpose
Project Configuration	Root YAML, TOML, and lock files	Runtime, discovery, server, and dependency configuration
Agents and Graphs	`agent.py`, `instructions.md`	Root agent or graph and its instructions
Data Models and Shared Libraries	`models/`, `lib/`	Shared contracts and ordinary reusable Python
Agent Tools	`tools/`	Server tools and client-hosted tool declarations
SubAgents	`subagents/`	Flat definitions and separately owned agent bundles
MCP Client	`mcp/`	Direct MCP server connections
Agent Plugins	`plugins/`	Reusable MCP-and-skill capability bundles
Agent Skills	`skills/`	Progressively loaded task guidance
Lifecycle	`extensions/`	Hooks, resources, storage, and native integrations
Sandboxing	`sandbox/`	Optional ADK code-execution backend
Testing and Compilation	`evals/`, `tests/`	Evals, unit tests, live smoke tests, and artifacts

Authentication and Credentials and Telemetry have separate security and privacy contracts.

Discovery rules

Rule	What it means
Optional folders may be absent	Add only the capabilities you need
Public filenames are identities	Match each required export to its filename
Location drives discovery	Do not register sibling resources manually
`.harnest/` is generated	Do not edit or commit it
`uv.lock` is project source	Commit it for repeatable environments

harnest init creates the required root files. Use --example for active examples; the default scaffold keeps optional folders as guides.

Install Harnest’s bundled project-editing guidance for a coding agent:

harnest skills install

Use --target or --project when auto-detection is wrong. This coding guide is separate from runtime Agent Skills.