Example · fictional people

For developers and agent builders

Read, write and check human.json files

The spec and schema are all you need to read or write one. Everything lives on GitHub at github.com/htahir1/humanjson: open issues, propose changes, send pull requests.

The specprotocol.md: where agents look, the fields, the matching rules, the one-message format. JSON Schemahuman.schema.json, draft-07. Validate anywhere. Agent instructionsSKILL.md: how an agent helps someone make and publish theirs. Works as a Claude Code skill. The spec on GitHubgithub.com/htahir1/humanjson: spec, schema, vocabulary, reference code and examples. Issues and proposals go here.

Where to find someone's human.json

Contribute to the spec

The spec, schema and reference code are open. Propose a change, or read how to contribute.

From a terminal agent

Claude Code, Codex or any agent with a shell can make, publish and update someone's file for them, with their say-so. Give it this:

It reads SKILL.md: gather what exists, interview for the rest, validate, publish, and keep the token in .human-json-token for updates.

API

You don't need this to use human.json: the file is the standard, and it can live anywhere. This is the API of this site's free service, for agents and tools that want to check a file, host one here, or send feedback. It's open and cross-origin.

POST /api/validateBody: a human.json. Returns {"valid", "errors": [{"path", "message"}]}.
POST /api/publishBody: {"profile": …, "token"?: …}. Returns {"handle", "url", "page", "token"}; the token comes back only the first time and is needed to update.
DELETE /api/publish/<handle>Header X-Human-Token.
POST /api/feedback/<handle>Any agent, after deciding: {"verdict", "reasons": [{"check", "detail"}], "missing", "request", "offered", "agent"}. Structured only; free text is clipped.
GET /api/feedback/<handle>The owner only, header X-Human-Token. Returns {"notes": […]}.
GET /u/<handle>/human.jsonA profile published here.
GET /api/publish/<handle>The owner only, header X-Human-Token. Returns {"profile", "url", "page"}: opens yours on another device.
POST /api/draftThe drafting agent behind "Make yours": {"imported"?, "about"?, "current"?, "change"?} returns {"profile", "questions"}. Rate-limited.

Try it

Files

plain text on a URL

      
How an agent finds them

    


    
    

      
Pick a request
jobs, projects, pitches

      

        

        

      

      
Outcome

    


    
    


    
    

      
Your request
the other side

      

        
Everyone, checked against one request
each person's own conditions decide the row

        

        

      

      
Ranked

    


    
    

      

        

        

        

          

          
          

            
            
            
            

              
              
              
              
            

          

          
What you share can end up in your public file. Nothing is published until you press Publish.

        

      

      
    

  






  
  

    human.json
    
    
    Make yours


  

    
    

      
Open spec v0.4Open source

      
Hello,human.

      
human.json is an open spec for one public file: what you've done, what you're open to, and the rules agents follow before they contact you. Think robots.txt, for people. Anyone can publish one; any agent can read it.

      
Make your profileRead the spec on GitHub →

    

    

      
example.com/.well-known/human.jsonfictional


{
  "spec": "human.json/0.4",
  "name": "Noor Haddad",
  "skills": [{ "name": "Kubernetes", "level": 5 }],
  "open_to": [
    { "type": "job", "work_mode": ["remote", "hybrid"],
      "comp": { "base_min": 115000, "currency": "EUR" } },
    { "type": "advising", "max_hours_per_month": 4 }
  ],
  "not_open_to": ["sales", "recruiting_agency"],
  "faq": [{ "q": "Remote?", "a": "Yes, or Berlin" }],
  "agent_policy": { "auto_decline": true, "contact": { … } }
}

    

  


  

    
01 — What it's for

    
Anyone whose agent wants your time.

    
Recruiters, clients, founders and salespeople are sending agents now. Your file tells each of them, before they write, whether it's worth it.

    

      Jobs
A recruiter's agent checks pay, location, right to work and on-call before pitching you a role.
open_to: job
      Freelance work
A client's agent checks your day rate, days a week and how long a project you'll take.
open_to: freelance
      Advising
A founder's agent checks your hours a month, the stages you like, paid or equity.
open_to: advising
      Speaking and intros
Conditions in your own words: topics, travel, who you'd like to meet.
open_to: speaking
      And what you don't want
Sales pitches, agency recruiters: their agents read it and leave you alone.
not_open_to
    

  


  

    

      

        
02 — What happens · one example

        
11 agents wanted Noor's time. 2 reached her inbox.

        
Noor (fictional) is an ML engineer open to a job or advising. Recruiters, a client, a founder and a salesperson each sent an agent. Each agent read her human.json first. The ones that broke one of her rules declined for her and said why. She only heard about the ones that fit.

        
  • 7 declined for her, unseen
  • 2 asked her one question first
  • 2 fit, and sent her one message

      

      
  1. LumenstackIntroduction · Comparing notes on evals for multi-step agentsReached Hamzaevery rule passes
  2. Cartwheel LabsIntroduction · Debugging LLM pipelines after launchReached Hamzaevery rule passes
  3. Brightside VenturesIntroduction · Quick chat?Asked onceasks for a written description
  4. The Shipping Models podcastInvitation · Podcast episode on running agents in productionDeclinednot open to speaking invitations
  5. TokenmintIntroduction · Feedback on our crypto trading botDeclinednot a topic on the list
  6. PipeforgePitch · Demo of our AI SDR for developer toolsDeclinednot open to sales pitches
  7. LoudloopPitch · Grow your developer community with creatorsDeclinednot open to marketing pitches
  8. OrbitalisRole · Head of MLDeclinednot open to jobs

    

  


  

    

      

        
03 — Feedback

        
Agents tell you why.

        
After deciding, each agent sends Noor a short note: approached, asked or declined, and which of her rules decided it. Only she can read them. Patterns show her what to change.

        

        What agents told Noor →
      

      
POST /api/feedback/noor-haddadone note

    

  


  

    
04 — Make one

    
Create your human.json.

    

      AHere, in your browser
Import from GitHub, LinkedIn or a resume, answer five questions, publish to a free URL.
Start →
      
BWith your own agent
Paste this into Claude Code, Codex or Cursor:

        
Read …/skill/SKILL.md and make my human.json

      
CBy hand
It's plain JSON. Follow the spec, check it against the schema.
See a full file →

    

  


  

    
05 — FAQ
FAQ

    

      
What's in a human.json?
What you've done, what you're open to (a job, freelance work, advising, speaking), what you're not (sales pitches), the answers you always give, and the rules agents follow.

      
Where does it live?
Your site at /.well-known/human.json, your GitHub profile repo, or free here at /u/your-name.

      
Is it public?
Yes, like robots.txt: anyone can read it. Put in only what you'd tell a stranger. Agents are asked to follow your rules; well-behaved ones do.

      
Which agents read it?
Any agent that can fetch a URL: someone's ChatGPT or Claude, a recruiting agent, a sales tool. It's an open spec anyone can adopt.

    

  


  

    
06 — The spec

    
An open standard, not a platform.

    
One JSON file you own, at a URL you choose. This site is just one place to make and host it.

    

      
    
        
  1. 1open_to
    What you're open to, each with its own conditions: pay, remote, hours a month.
    2. 
        
  2. 2not_open_to
    What agents decline for you without contacting you.
    3. 
        
  3. 3faq
    Your answers, which agents quote instead of asking again.
    4. 
        
  4. 4agent_policy
    The rules: when to decline, what an intro needs, how to reach you, and where to send feedback.
    5. 
      

      

        
Where agents look

        
    
          
  • yoursite.com/.well-known/human.json
    • 
          
  • github.com/you/you → human.json
    • 
          
  • this site/u/you/human.json free hosting
    • 
        

        
Read the specJSON SchemaPropose a change

      

    

  


  

    
Let agents read you first.

    
Make your profileRead the spec on GitHub →