Agent Cards

🃏 What are Agent Cards?

Every OMNISKILL agent carries a structured Agent Card in its agent-manifest.yaml. The card describes the agent's capabilities, input/output modalities, cost tier, token estimates, and quality metrics in a machine-readable format.

Agent Cards enable:

• Discovery — External systems (web UIs, LLM routers, IDE extensions) can find agents and their capabilities from a single JSON index.
• Selection — When multiple agents could handle a task, card metadata enables automated or user-assisted agent selection.
• Observability — Token usage estimates and quality metrics per agent enable cost optimization.
• Ecosystem — A standardized card format makes agents portable across frameworks.

📋 Card Schema

Field	Type	Required	Description
capabilities	object	✅	Boolean flags for agent capabilities
capabilities.streaming	boolean	✅	Supports streaming output
capabilities.multi-turn	boolean	✅	Supports multi-turn conversations
capabilities.file-output	boolean	✅	Produces file artifacts
capabilities.self-evaluation	boolean	✅	Validates own output quality
capabilities.context-aware	boolean	✅	Uses prior context from the pipeline
skills-provided	list	✅	Skills this agent provides (min 1 item)
input-modes	list[string]	✅	MIME types the agent accepts
output-modes	list[string]	✅	MIME types the agent produces
cost-tier	string	✅	fast | standard | premium
avg-tokens	object	✅	Token usage estimates (input and output integers)
quality-metrics	object | null	❌	Evaluation metrics (null = not yet evaluated)

📝 Example Card

card:
  capabilities:
    streaming: false
    multi-turn: true
    file-output: true
    self-evaluation: true
    context-aware: true
  skills-provided:
    - id: requirements-engineering
      name: Requirements Engineering
      description: "Transforms ambiguous ideas into crystal-clear, testable specifications"
      tags: [specification, requirements, acceptance-criteria]
  input-modes:
    - "text/plain"
    - "text/markdown"
  output-modes:
    - "text/markdown"
  cost-tier: standard
  avg-tokens:
    input: 2000
    output: 8000
  quality-metrics: null

⚡ Generating agent-cards.json

The agent-cards.json file is an auto-generated JSON index of all agent cards. It's deployed alongside llms.txt during GitHub Actions builds.

CLI Command (recommended)

# Generate agent-cards.json at the repo root
omniskill generate agent-cards

# Write to a custom directory
omniskill generate agent-cards --output ./dist/

# JSON output (for scripting)
omniskill --json generate agent-cards

Standalone Script

Works without the omniskill package installed — only requires Python 3.10+ and PyYAML:

python scripts/generate-agent-cards.py
python scripts/generate-agent-cards.py --output ./dist/

🖥️ CLI Reference

Summary Table

omniskill cards

Displays a Rich table of all agents with their name, role, capability badges (⚡🔄📄🔍🧠), and cost tier (color-coded).

Single Agent Detail

omniskill cards spec-writer-agent

Displays a detailed panel with all card fields for the named agent.

JSON Export

omniskill cards --json

Outputs a JSON envelope with all card data.

Validate Cards

omniskill cards --validate

Validates every agent's card section against the schema. Exits with code 0 on success, code 2 on failure.

Freshness Check

omniskill validate --check-agent-cards

Checks whether agent-cards.json is up to date with current manifests.

🔌 Using Cards Programmatically

The generated agent-cards.json file can be consumed by any tool that reads JSON:

// JavaScript
const cards = await fetch("agent-cards.json").then(r => r.json());
const premiumAgents = cards.agents.filter(
  a => a.card?.["cost-tier"] === "premium"
);

# Python
import json
with open("agent-cards.json") as f:
    data = json.load(f)
for agent in data["agents"]:
    if agent["card"] and agent["card"]["cost-tier"] == "fast":
        print(f"Fast agent: {agent['name']}")

➕ Adding Cards to Your Agent

1. Open your agent's agent-manifest.yaml
2. Add a card: section at the end (see the template)
3. Fill in accurate values based on your agent's actual capabilities
4. Run omniskill cards --validate to verify

The card section is optional — agents without it continue to work normally. However, cards are recommended for discoverability and programmatic consumption.