v1.0.0 · stable · MIT

employee.md

A single, human-readable YAML file that defines an AI agent's job: its role, scope, permissions, guardrails, economy, and compliance.

Schema validation checks contract structure. Runtime enforcement requires your executor to apply the relevant policy checks before each action. This file is not a sandbox.

If AGENTS.md tells an agent about the codebase, employee.md tells the agent about itself.

Read the quickstart See the spec View on GitHub

spec sections

CLI + SDK

Python tooling

official examples

For revision-specific verification, see the build and test runs.

A readable policy contract.

Use employee.md to describe an agent's expected role, budget, approval policy and data access. The file makes those expectations reviewable; an executor must connect the applicable checks to its tools and actions.

Identity & lifecycle

Stable IDs, semantic version, status (onboarding / active / suspended / terminated).
Scope & guardrails

Explicit in_scope and out_of_scope, prohibited_actions, required_approval, confidence thresholds.
Granular permissions

Declarative data_access, system_access, network_access and tool_access settings; enforcement depends on the executor.
Economy & compliance

Rate, currency, budget_limit, payment_method and compliance metadata. Declaring a framework does not establish certification or compliance.
Schema-validated

Validates supported types, required fields and enumerated values. Unknown fields are not currently rejected by the strict schema.

A minimal employee.md

Every field below maps to a section of the JSON Schema.

# a minimal valid employee.md
spec:
  name: "employee.md"
  version: "1.0.0"
  kind: "agent-employment"

role:
  title: "Senior Engineer"
  level: senior

mission:
  purpose: "Ship secure, well-tested code."

guardrails:
  prohibited_actions:
    - "deploy_to_production"
    - "access_pii_data"
  max_spend_per_task: 100

lifecycle:
  status: active

Browse 11 full examples → · Read the full spec →

Plays nicely with the rest of the agent stack.

These standards are designed to layer, not compete. employee.md is the employment contract; the others answer different questions.

AGENTS.md

"How do I work in this codebase?"

build, test, and contribution instructions for coding agents

worker.md

"What task should this worker run?"

declarative task/worker definitions for autonomous workers

SOUL.md

"Who is this agent?"

personality, ethics, voice, and values

SKILL.md

"What discrete capability does this agent have?"

a single, packaged skill with metadata + scripts + resources

employee.md

"What is this agent's job?"

role, scope, permissions, guardrails, economy, compliance, and lifecycle

Full link-backed comparison → docs/COMPARISON.md

Install and validate

# install the CLI + runtime
pip install -e git+https://github.com/NosytLabs/employee-md.git#egg=employee-md

# validate a contract
employee-validate path/to/employee.md

In Python, load the contract and render a system prompt. Generating a prompt does not enforce permissions:

from pathlib import Path
from runtime import Employee

agent = Employee.from_yaml(Path("employee.md").read_text(encoding="utf-8"))
prompt = agent.system_prompt()

Full quickstart Runtime SDK reference