Skip to content
Scoutica Protocol

scoutica.json

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

Section titled “Required fields”
scouticastringrequired

The protocol version this card conforms to. Must match the semver pattern MAJOR.MINOR.PATCH — for example "0.1.0".

card_urlstringrequired

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"

namestringrequired

Your professional name. This is the minimum public identifier for your card.

Optional fields

Section titled “Optional fields”
titlestring

Your professional title. Included here for quick scanning without fetching the full profile.json.

senioritystring

Your seniority level. One of: entry, junior, mid, senior, lead, manager, director, executive.

domainsstring[]

Your top professional domains. Zone 1 data — visible to anyone without authentication.

availabilitystring

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
updatedstring

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_typestringdefault: 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

Section titled “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

Section titled “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>.