Note
Current status: The protocol, CLI, schemas, and AI-powered card generation are live and ready to use today. The monetization layer (micropayments, blockchain identity, $SKILL token) is on the roadmap and under active development.
This project has a strict separation between two concerns:
| Part | What | Where | Visibility |
|---|---|---|---|
| The Protocol | Open standard, schemas, agent rules, registry API, smart contracts, templates | This repo (scoutica/) |
🌍 Public — anyone can clone, fork, build on it |
| Your Skill Card | Your personal profile, Rules of Engagement, evidence, salary floor | Your private store (e.g. ~/my-card/) |
🔒 Private — never committed to this repo |
The protocol is the network. Your skill card is your node on it.
✅ Ready to build your node? Check out the Candidate Onboarding Guide to create your personal skill card in 15 minutes.
A user who clones this repo gets:
- JSON Schemas to validate their card
- Agent rule templates to evaluate opportunities
- Registry API spec to run their own node
- CLI tools to publish and discover cards
They do NOT get your private data. Your card lives in your own private directory and will never hit this repo.
scoutica-protocol/
├── README.md ← You are here
├── SKILL.md ← Agent instructions (candidate side)
├── RECRUITER_SKILL.md ← Agent instructions (employer side)
├── docs/ ← 📚 DOCUMENTATION (Astro/Starlight → docs.scoutica.com)
│ ├── astro.config.mjs ← Starlight navigation and site configuration
│ ├── package.json ← Docs build and validation commands
│ └── src/content/docs/ ← CLI reference, guides, and architecture
├── .specs/ ← 🔬 SPECIFICATIONS
│ ├── ROADMAP.md ← 5-phase roadmap
│ └── network/ ← Network architecture specs
│ ├── 05_AGENT_COMMUNICATION ← Message types, transport, SLAs
│ ├── 12_ARCHITECTURE_DEEP ← Critical path, milestones
│ └── 13_TRANSPORT_ARCH ← Git/Nostr/Webhook waterfall
├── .agents/skills/ ← 🤖 AGENT SKILLS
│ ├── create-skill-card/ ← Generate a card from documents
│ ├── apply-to-role/ ← Draft a card-grounded CV + cover letter for a role
│ ├── evaluate-candidate/ ← Score candidates against jobs
│ ├── build-integration/ ← Build apps consuming cards
│ └── extend-protocol/ ← Add features to the protocol
├── schemas/ ← JSON Schema definitions
│ └── registry/ ← Registry index schemas
├── tools/ ← CLI tools
│ ├── scoutica ← Main CLI (bash + embedded Python)
│ ├── scoring.py ← Deterministic fit scoring engine
│ ├── import_aijs.py ← Offline ai-job-search → Skill Card importer
│ └── validate_card.py ← Schema validator (scoutica validate)
├── protocol/templates/ ← Card and rule templates
└── protocol/
├── examples/ ← Sample candidate + employer cards
└── registry/ ← Seed registry data (candidates + roles)
Today (v0.4.0 — local delivery primitives; real transport is planned):
1. Candidate installs the CLI → generates Skill Card (profile + evidence + rules)
2. Pushes card to GitHub → registers in the decentralized registry
3. Employer creates Recruiter Card → publishes structured job postings
4. Employer's agent searches registry → runs deterministic fit scoring
5. Agent queues an offer locally (Git-native PR / Nostr are the planned transports) → candidate agent auto-evaluates
6. If rules pass → accept. If rules fail → auto-reject with reasons.
7. All interactions logged for trust scoring + anti-ghosting.
Transport Evolution:
| Phase | Transport | Status |
|---|---|---|
| V1 | Git-native inbox (PRs as messages) | 🔧 Local simulation |
| V2 | Nostr relays (encrypted, decentralized) | 🔧 Planned |
| V3 | HTTP webhooks (for always-on agents) | 📋 Spec ready |
Target cost to hire: ~$4 total · LinkedIn Recruiter: ~$10,000/year · Agency: ~$15,000–$30,000/hire
Choose the method that works best for you:
The easiest way to generate a Candidate Card is to give these instructions directly to an AI agent (like Claude Code, Cursor, or OpenClaw):
Agent: Please install the Scoutica Protocol CLI and generate a Skill Card for my CVs in this folder.
Important constraints:
1. Ensure you are currently in the folder that contains my CV/resume files. If not, ask me which folder contains them before proceeding.
2. If the user doesn't have local AI tools (gemini, claude, ollama), run `scoutica scan . --clipboard` instead.
3. If I have PDFs, you may need `brew install poppler` for extraction.
Supported formats: .md, .txt, .pdf, .docx, .json, .yaml, .csv, .html
TTL: The preview URL generated at the end will expire in 24 hours.
Installation:
curl -fsSL https://raw.githubusercontent.com/traylinx/scoutica-protocol/main/install.sh | bash
Generation:
scoutica scan .
Requires Python 3.11+ with the strict validation dependencies installed:
python3 -m pip install 'jsonschema[format]' PyYAMLThe installer verifies these prerequisites before writing files. It never installs Python packages into your global environment.
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/traylinx/scoutica-protocol/main/install.sh | bash╔═══════════════════════════════════════════════════════╗
║ ║
║ ⚡ Scoutica Protocol — CLI Installer ║
║ ║
║ Your skills. Your rules. Your data. ║
║ ║
╚═══════════════════════════════════════════════════════╝
→ Creating directories in ~/.scoutica...
→ Downloading scoutica CLI...
→ Downloading JSON schemas...
→ Downloading card templates...
→ Downloading AI card generator...
→ Downloading validation tool...
╔═══════════════════════════════════════════════════════╗
║ ║
║ ✅ Scoutica CLI installed successfully! ║
║ ║
╚═══════════════════════════════════════════════════════╝
To get started, run:
source /Users/sebastian/.zshrc && scoutica init
Windows (PowerShell):
irm https://raw.githubusercontent.com/traylinx/scoutica-protocol/main/install.ps1 | iexWindows currently ships the PowerShell implementation 0.1.0 for protocol
0.4.0 under capability set windows-subset-v1. Its supported surface is
exactly init, init --ai, validate, publish, info, help, and version.
Other commands are deliberately reported as unsupported (exit 2); full POSIX
command parity is parked for a future effort.
Once installed, use the built-in help to see the commands supported by your platform. The full help surface below is from the POSIX implementation 0.4.0:
scoutica helpScoutica Protocol CLI v0.4.0
Your skills. Your rules. Your data.
Usage: scoutica <command> [options] [directory]
🚀 Create your card:
scan <docs-folder> Auto-generate from your documents (easiest)
init Step-by-step interactive wizard
init --ai Generate via AI assistant (paste your CV)
import aijs <fork> Convert an ai-job-search fork into a card (offline)
🔧 Manage your card:
info [dir] View your card summary
preview [dir] Build HTML layout and publish to here.now
validate [dir] [--schema-dir /abs] Validate against trusted or explicit schemas
publish [dir] Push card to GitHub
resolve <url> Fetch and display any card from a URL
🏢 Employer commands:
org init Create a Recruiter/Employer Identity Card
org verify Verify domain ownership (DNS TXT record)
org publish Push employer card to GitHub
role create Create a structured job posting (role.json)
role validate [dir] Validate role(s) against protocol schemas
🌐 Network commands:
evaluate <card> <role> Score fit between a candidate and role
jobs search Search the registry for candidates or roles
send <url> --type ... Send a message to another agent
inbox Check for incoming messages
reply <msg_id> --accept Accept/reject a message
deliver Push pending messages to recipients
register <dir> --type Generate registry entry for PR submission
identity init Generate your Nostr keypair
⚙️ Advanced:
doctor System diagnostics and health check
status Show local card, identity, and network state
logs Show recent CLI activity
update Update the Scoutica Protocol CLI
help Show this help
version Show version
Examples:
# Full workflow: scan → validate → publish
scoutica scan ~/CV/ && scoutica validate && scoutica publish
# Score a candidate against a role (clean JSON out)
scoutica evaluate ./my-card --role ./role.json --json
# Scaffold an employer identity
scoutica org init
Put your CV, certs, and portfolio in a folder and let AI extract your skill card automatically. No server required.
scoutica scan ~/my-docs/ # auto-detects installed CLI
scoutica scan ~/my-docs/ --with gemini --allow-remote-provider
scoutica scan ~/my-docs/ --clipboard # copy prompt to clipboard (no CLI needed)Document extraction happens locally. Remote-capable AI providers send the full generated prompt and document text to a remote service only after a per-invocation confirmation, or when noninteractive automation supplies --allow-remote-provider. Ollama is treated as local only for its default or a loopback endpoint. --clipboard makes no Scoutica network call but copies the same sensitive prompt to your system clipboard for user-controlled transfer. Scan state is private to the resulting card at <card>/.scoutica/state.json.
Supported providers (auto-detected in this order):
| Provider | CLI | Repo |
|---|---|---|
| Gemini CLI | gemini |
google-gemini/gemini-cli |
| Claude Code | claude |
anthropics/claude-code |
| OpenAI Codex | codex |
openai/codex |
| OpenCode | opencode |
opencode-ai/opencode |
| Ollama | ollama |
ollama.com |
| switchAILocal | ail |
traylinx/switchAILocal |
Vibe and OpenClaw scan adapters are intentionally disabled until they expose a characterized stdin or prompt-file interface; Scoutica will not place source documents in process arguments.
📗 Learn More: Check out the Complete Documentation for full commands, guides, and architecture.
Are you an organization looking to hire from the network? Set up your Recruiter Card:
# 1. Initialize your organization identity
scoutica org init
# 2. Verify your domain (DNS TXT record)
scoutica org verify --domain company.com
# 3. Create a structured job posting
scoutica role create
# 4. Validate and publish to GitHub
scoutica role validate roles/
scoutica org publishYour roles are now live on the mesh network. Candidate agents will automatically evaluate and pitch you candidates that match your requirements.
- Open
GENERATE_MY_CARD.mdon GitHub - Copy the entire file contents
- Paste it into any AI assistant — ChatGPT, Claude, Gemini, Copilot, etc.
- Follow the conversation — the AI will interview you and generate your 4 files
- Save the files to a GitHub repo → your card is live
This is the recommended path for non-technical users. No git, no CLI, no install.
- Click "Use this template" on the Scoutica Protocol repo
- Name your repo (e.g.,
my-scoutica-card) - Edit the files in
protocol/templates/with your data - Push → done
git clone https://github.com/traylinx/scoutica-protocol.git
cp -r protocol/templates/ my-card/
python tools/validate_card.py ./my-card/If you keep your profile in an ai-job-search fork (an independent MIT workflow by Mads Lorentzen), convert it into a Skill Card in one offline, deterministic step — no network, no AI, no guessing:
scoutica import aijs ~/ai-job-search --to ./my-card --salary-floor-eur 85000
scoutica validate ./my-cardKeep applying with ai-job-search and become discoverable with Scoutica off one profile. Your behavioral profile, interview stories, and salary data are never imported (data minimization). See the bridge guide and scoutica import.
| Decision | Choice | Status |
|---|---|---|
| Format | Pure Markdown + JSON + YAML — no runtime needed | ✅ Live |
| Distribution | GitHub (Phase 1) → Federated registries (Phase 2) | ✅ Phase 1 Live |
| Matching | Agent-side (decentralized, each agent scores locally) | ✅ Live |
| Identity | Soulbound Tokens on Base L2 (primary), Polygon (fallback) | 🔜 Roadmap |
| Payment | Stripe credits (V1) → On-chain micro-fees (V2) → $SKILL token (V3) | 🔜 Roadmap |
| Compliance | EU AI Act High-Risk compliant by design | ✅ Live |
| Anti-bias | No demographic fields in schema | ✅ Live |
The Scoutica Protocol is built by its community. We welcome contributions of all kinds — protocol design, code, documentation, and ideas.
See the platform/ folder to understand the schema and implementation, then pick an area that interests you.
Built with the conviction that your professional identity should belong to you, not a platform.