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.

One contract. Validated by a real JSON Schema. Enforceable at runtime.

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

288

tests passing

official examples

A real contract, not a vibe.

Most agent specs stop at "you are a helpful assistant." employee.md goes further: it answers what is this agent's job? Down to the budget, the approval policy, the data it can touch, and the SLA it owes.

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

data_access, system_access, network_access, tool_access — auditable at the field level.
Economy & compliance

Rate, currency, budget_limit, payment_method, plus SOC2/GDPR frameworks and audit retention.
Schema-validated

Every field is enforceable. Catch typos before they ship.

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 9 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

Get started in 30 seconds

# 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

# or use the runtime SDK in Python
from runtime import Employee
agent = Employee.from_yaml(open("employee.md").read())
prompt = agent.system_prompt()

Full quickstart Runtime SDK reference