Skip to main content
scoutica.json is the well-known discovery file for the Scoutica Protocol. Place it at the root of your GitHub repository and any AI agent or crawler that checks for it will immediately know that your repo contains a Skill Card and where to fetch the full card files. Think of it as robots.txt — but instead of telling crawlers what not to index, it tells agents where to find your professional profile.

​
Required fields

​
scoutica
string
required
The protocol version this card conforms to. Must match the semver pattern MAJOR.MINOR.PATCH — for example "0.1.0".
​
card_url
string
required
The base URL agents use to fetch your card files. All card files (profile.json, rules.yaml, evidence.json, SKILL.md) are resolved relative to this URL. Must be a valid HTTPS URI.Example: "https://raw.githubusercontent.com/user/my-card/main"
​
name
string
required
Your professional name. This is the minimum public identifier for your card.

​
Optional fields

​
title
string
Your professional title. Included here for quick scanning without fetching the full profile.json.
​
seniority
string
Your seniority level. One of: entry, junior, mid, senior, lead, manager, director, executive.
​
domains
string[]
Your top professional domains. Zone 1 data — visible to anyone without authentication.
​
availability
string
Your current availability for new opportunities. One of:
  • immediately — available now
  • in_2_weeks — available in approximately two weeks
  • in_4_weeks — available in approximately four weeks
  • in_8_weeks — available in approximately eight weeks
  • not_looking — not open to opportunities at this time
​
updated
string
The date this card was last updated, in ISO 8601 format (YYYY-MM-DD). Helps agents determine whether to re-fetch a cached card.
​
entity_type
string
default:"human"
The type of entity this card represents. Defaults to "human". One of:
  • human — an individual person
  • ai_agent — an autonomous AI agent
  • service — a software service or API
  • robot — a physical robot or hardware agent
  • team — a group of people acting together
  • organization — a company or institution

​
Example

{
  "scoutica": "0.1.0",
  "card_url": "https://raw.githubusercontent.com/user/my-card/main",
  "name": "Alice Developer",
  "title": "Lead Engineering Manager",
  "seniority": "lead",
  "domains": ["Backend Engineering", "DevOps", "AI/ML"],
  "availability": "in_4_weeks",
  "updated": "2026-03-23",
  "entity_type": "human"
}

​
How agents discover your card

There are four ways an AI agent can find your Skill Card:
  1. scoutica.json at repo root — An agent checks for this file at the root of any GitHub repository. This is the primary discovery method.
  2. Scoutica registry — Cards can be submitted to a public registry index. Agents query the registry to find cards by domain, seniority, or availability.
  3. GitHub topics — Repositories tagged with the scoutica-card topic are discoverable through the GitHub search API. Add this topic to your repo to increase visibility.
  4. Direct URL — Anyone can share a direct link to a card. Agents can resolve a card from any URL using scoutica resolve <url>.
Run scoutica publish ./my-card/ to automatically generate scoutica.json, commit your card files, and push to GitHub. The CLI creates the discovery file for you — you do not need to write it by hand.
The scoutica.json file is auto-generated by the CLI and kept in sync when you run scoutica publish. Edit profile.json and rules.yaml directly; the discovery file will be regenerated from them.