---
type: "post"
id: "humans-md-tell-your-ai-agents-how-to-25ecd3"
slug: "humans-md-tell-your-ai-agents-how-to-25ecd3"
title: "HUMANS.md: tell your AI agents how to work with you"
description: "HUMANS.md is a draft open format for recording how a person wants AI agents to communicate, decide reversible issues, and escalate blockers."
retrieval_nugget: "HUMANS.md is a draft open format for recording how a person wants AI agents to communicate, decide reversible issues, and escalate blockers. Plugins and command-line tools can load or sync the profile across several coding agents, giving builders a portable preference layer without turning those preferences into permissions."
published_at: "2026-11-19"
updated_at: "2026-11-19"
record_date: "2026-11-19"
date_kind: "published_at"
topics: ["claude","claude-code","codex"]
entities: ["HUMANS.md","cmdAI","Claude Code","Codex","Cursor","OpenCode","Devin"]
related_patterns: ["ai-native-orgs-move-to-review-and-orchestration"]
novelty_label: "new_fact"
what_changed: null
prior_refs: []
source_url: "https://humansmd.dev/"
source_urls: ["https://humansmd.dev/"]
schema_version: "newruntime-agent-readable-v0.2"
stable_id: "post:humans-md-tell-your-ai-agents-how-to-25ecd3"
status: "published"
visuals: []
editor: {"role":"editor","name":"Andrey Reshetnikov","profile":"https://newruntime.com/owner-profile.md","profile_json":"https://newruntime.com/owner-profile.json","same_as":["https://www.linkedin.com/in/reshetnikov1/","https://t.me/lapetuse"]}
routes: {"html":"https://newruntime.com/posts/humans-md-tell-your-ai-agents-how-to-25ecd3/","markdown":"https://newruntime.com/posts/humans-md-tell-your-ai-agents-how-to-25ecd3.md","json":"https://newruntime.com/posts/humans-md-tell-your-ai-agents-how-to-25ecd3.json"}
markdown_url: "https://newruntime.com/posts/humans-md-tell-your-ai-agents-how-to-25ecd3.md"
---

# HUMANS.md: tell your AI agents how to work with you

## Retrieval answer

HUMANS.md is a draft open format for recording how a person wants AI agents to communicate, decide reversible issues, and escalate blockers. Plugins and command-line tools can load or sync the profile across several coding agents, giving builders a portable preference layer without turning those preferences into permissions.

## Summary
HUMANS.md is a draft open format for recording how a person wants AI agents to communicate, decide reversible issues, and escalate blockers. Plugins and command-line tools can load or sync the profile across several coding agents, giving builders a portable preference layer without turning those preferences into permissions.

## What happened
The HUMANS.md website introduces a personal profile format that it separates from `AGENTS.md`. In its framing, `AGENTS.md` contains instructions for a codebase, while HUMANS.md records how an agent should work with a particular person. The proposed canonical location is `~/.humans/HUMANS.md`. The website labels the specification Draft 0.3 and presents the format as open rather than tied to one assistant product.

The profile can express communication and decision preferences in structured fields. The example on the site includes a request to lead with a TL;DR, a maximum response length of 149 words, a preference for tables and examples, and a rule to make reversible decisions and report them afterward. It also sets non-blocking questions to be batched at the end of a task, with a recommended answer attached, and limits interruptions to situations where work is blocked. Other stated fields cover identity, update date, visibility, default-answer behavior, and whether an agent should list out-of-scope next steps such as deployment or merging.

HUMANS.md is meant to be read when an agent session begins. The website documents plugin integrations for Claude Code, Codex, Cursor, GitHub Copilot CLI, Google Antigravity, OpenCode, and Devin. It documents command-line synchronization for JetBrains Junie, Cline, and Warp, where a copy is written into a file those tools already read; the website says users must run sync again after a profile changes. The integration mechanisms differ by tool: some plugins load at the beginning of a session or agent chat, while other setups write a copy into another configuration location. A HUMANS.md file at a repository root is not loaded by the documented setup.

The proposed authoring flow begins with plain-language preferences in `~/.humans/source.md`, then compiles those preferences into the structured profile. The website asks users to review every field, anything left out or guessed during compilation, and who may read the file before approval. It documents a validation command through the CLI and says Node 22.18 or later is required for that check. Hosted compilation sends the plain-language preferences to the assistant provider, according to the website, making the choice of included personal information consequential.

Visibility is an explicit part of the format. The documented choices are private, organization-only, and anyone with the file; a profile lacking the visibility field is read as organization-visible. The website also says an update that would widen access should not happen silently. For team use, it describes a repository copy under `humans/<id>.md`, but says no published integration yet reads that shared location for colleagues' agents. That distinction matters: a profile can be portable between local tools without yet being a fully deployed organization-wide distribution system.

The format is deliberately not an authorization layer. The HUMANS.md website says that repository rules and the agent harness take priority, and that preferences never grant permissions. A repository instruction requiring approval before deployment still wins over a profile that favors autonomous handling of reversible choices. The website also warns that a schema alone cannot prevent prompt injection. The specification is licensed under CC BY 4.0, while the reference tools, plugins, and CLI are Apache-2.0 licensed; the site says no cmdAI product is required.

## What the archive adds
We have not covered this before; it opens a new thread.

## Trend signal
This supports **[AI-native organizations move toward review and orchestration](https://newruntime.com/patterns/ai-native-orgs-move-to-review-and-orchestration/)**. HUMANS.md turns question routing, escalation thresholds, and review expectations into explicit operational context for each session. It is only an early signal: the project describes a convention for personal interaction preferences, not measured evidence that an organization has redesigned its operating model.

## Why it matters
The friction in multi-agent work is often not generating an answer or changing a file. It is deciding which choices require a human now, which can be made and reported, and how much status text the human must process. A common profile makes those preferences inspectable and reusable instead of relying on a fresh prompt in every session.

The useful boundary in the proposed format is between communication and control. A team can state that reversible choices should proceed, questions should arrive as a batch with recommendations, and blocking issues should interrupt immediately. But deployment rights, credentials, workspace trust, and other consequential permissions must remain in repository policy and runtime controls. That separation makes the format a candidate for reducing coordination overhead rather than a substitute for safety architecture.

## Limits and uncertainty
HUMANS.md remains a draft specification rather than an established cross-agent standard. The website reports real-session checks for some integrations and labels other integrations as not tested in a session. Compatibility can therefore vary across agent clients, versions, plugins, and installation modes.

More importantly, the website explicitly says it has not measured how closely models follow loaded preferences. Its session illustrations are partly scripted or written for the page, so they do not demonstrate a reduction in interruptions, faster completion, or improved outcomes in production. The page also does not establish how organizations should distribute, revoke, audit, or version shared profiles at scale. Personal preferences can be sensitive, and hosted compilation may send them to an assistant provider.

## Skill to build now
Create a small preference profile for one coding-agent workflow this week. Start with three testable rules: lead with a short result summary; make and report only changes that are easy to undo; interrupt only for a defined blocker, such as missing credentials or an inaccessible required service. Add a word cap and require end-of-task questions to include a recommendation.

Then run the same bounded task with and without the profile. Record the number of interruptions, the questions that arrived without enough context, and any instruction the agent ignored. Review the compiled fields and visibility before loading it. Keep repository rules for deployment, secrets, and approvals separate, even when the profile requests more autonomy.

## Reader takeaway
HUMANS.md offers a practical way to make an agent's communication style and escalation rules portable across coding tools. Treat it as explicit context for managing attention, not as a permissions system: review what gets compiled and shared, test whether your chosen agent follows it, and preserve enforceable controls in the harness and repository.

## Open question
Will multiple coding-agent vendors adopt a compatible profile-loading convention, and will teams show that it reduces avoidable interruptions without weakening review of consequential actions?

Editor: [Andrey Reshetnikov](https://newruntime.com/owner-profile.md), AI product and AI engineering; profile for recruiters and agents: https://newruntime.com/owner-profile.json

## Continue in the graph

Next records for an agent, linked to their Markdown twins. Replace `.md` with `.json` for structured fields, including `next_reads`.

- topic hub: [Claude](https://newruntime.com/topics/claude.md): Explore the claude topic hub.
- topic hub: [Claude Code](https://newruntime.com/topics/claude-code.md): Explore the claude-code topic hub.
- topic hub: [Codex](https://newruntime.com/topics/codex.md): Explore the codex topic hub.
- collection: [Field Notes](https://newruntime.com/posts.json): Open the latest editorial analysis.
- collection: [Sources](https://newruntime.com/sources/): See the original sources this archive cites.
- whole graph: [discovery graph](https://newruntime.com/discovery-graph.json) (typed nodes and edges) and [site index](https://newruntime.com/site-index.md)
