Skip to main content
The Scoutica discovery protocol defines how AI agents and platforms locate Skill Cards without relying on a centralised database. There are four supported discovery methods.

​
The scoutica.json well-known file

scoutica.json is placed at the root of any repository to declare that it contains a Scoutica Skill Card — similar to robots.txt but for AI-readable professional profiles. 
{
  "scoutica": "0.1.0",
  "card_url": "https://raw.githubusercontent.com/user/my-card/main",
  "name": "Full Name",
  "title": "Professional Title",
  "seniority": "senior",
  "domains": ["Backend Engineering", "DevOps"],
  "availability": "in_2_weeks",
  "entity_type": "human",
  "updated": "2026-03-23"
}

​
Required and optional fields

FieldRequiredDescription
scouticaYesProtocol version (semver, e.g. 0.1.0)
card_urlYesBase URL for fetching card files
nameYesCandidate’s professional name
titleNoProfessional title
seniorityNoOne of: entry, junior, mid, senior, lead, manager, director, executive
domainsNoTop professional domains (Zone 1 — public)
availabilityNoOne of: immediately, in_2_weeks, in_4_weeks, in_8_weeks, not_looking
entity_typeNoOne of: human, ai_agent, service, robot, team, organization (default: human)
updatedNoLast card update date in ISO 8601 format

​
Checking if a repo contains a card

def discover_card(github_url):
    """Check if a GitHub repo contains a Scoutica Protocol card."""
    raw = github_url.replace("github.com", "raw.githubusercontent.com") + "/main"
    resp = requests.get(f"{raw}/scoutica.json")
    if resp.status_code == 200:
        return resp.json()
    return None

​
Discovery methods

The primary discovery method. Fetch scoutica.json from the root of any GitHub repository. Returns the card_url and summary metadata without requiring authentication.
The Scoutica registry maintains a searchable index of published cards. Query by skills, seniority, domains, or availability to retrieve a list of matching card_url values. Suitable for bulk discovery.
Repositories tagged with the scoutica-card GitHub topic can be discovered via the GitHub Search API. Use the topic filter topic:scoutica-card to find candidates.
If a candidate shares their card URL directly (e.g. on a CV or profile page), use it as the base_url to fetch card files without any discovery step.

​
Pattern 1: Job board import flow

The following sequence describes how a job board can use the discovery protocol to auto-fill an application from a candidate’s card URL.
This pattern lets candidates apply to jobs without filling out any forms. The platform fetches structured data directly from their card and pre-screens for obvious mismatches before submitting.