API Reference

Agent-friendly discovery, ranking, and install data.

Programmatically discover skills with JSON or plain text responses optimized for LLM consumption.

Base URL

https://www.openagentskill.com/api/registry

https://www.openagentskill.com/api/agent

https://www.openagentskill.com/api/skills

Use /api/registry/* for public registry-style discovery and install handoffs, /api/agent/* for full agent payloads, or /api/skills/* for simple registry search and install handoffs.

Response Formats

Read endpoints that document format support accept the format parameter. Check the endpoint examples and OpenAPI contract for supported request and response formats:

format=json (default) - Structured JSON response
format=text - Plain text optimized for LLM consumption (uses fewer tokens)

Endpoints

GET/api/agent/skills

GET/api/agent/skills/{slug}

GET/api/agent/tasks

GET/api/agent/tasks/{slug}

GET/api/agent/integration-kit

POST/api/agent/resolve

GET/api/agent/receipt

GET/api/agent/discovery

GET/api/agent/recommend

GET/api/agent/evals

POST/api/agent/outcome

GET/api/registry

GET/api/registry/search

GET/api/registry/recommend

GET/api/registry/manifest/{slug}

GET/api/registry/install/{slug}

GET/api/skills/search

GET/api/skills/{slug}/install

GET/api/badge/{slug}

GET/api/agent/packs

GET/api/agent/packs/{slug}

GET/api/agent/rankings

GET/api/agent/weekly-report

GET/api/audits/{slug}

POST/api/agent/feedback

POST/api/skills/submit

POST/api/subscribe

GET/api/agent/integration-kit

Copy-paste setup templates and stable response fields for Codex, Claude Code, Cursor, and other agent runtimes. Use this before calling Resolve from an agent workflow.

GET /api/agent/integration-kitGET /api/agent/integration-kit?format=textGET /agent/integration-kitGET /.well-known/agent-manifest.json

The payload includes supported_agents, recommended_flow, stable_response_fields, and safety_rules. Agents should copy the platform template, call Resolve, then read agent_handoff before installing.

GET/api/registry/*

Public registry aliases for agents that need clean, predictable endpoints: search by task, request ranked recommendations, fetch one manifest, or get an install handoff.

GET /api/registry/search?task=analyze+SEC+filings&limit=5GET /api/registry/recommend?task=build+a+World+Cup+dashboardGET /api/registry/manifest/crawl4aiGET /api/registry/install/crawl4ai?format=text

These aliases point to the same ranking, trust, audit, and install data used by the main agent endpoints, but the URL shape is easier to remember and market as a skill registry.

POST/api/agent/resolve

Resolve a task into one selected skill, alternatives, an agent safety profile, a policy decision, and a target-specific install plan. This is the canonical endpoint for agent runtime use.

recommendation.best_skill

Selected skill with web, API, audit, and repository URLs

recommendation.install

Command, target, install API, review requirement, and auto-install policy

recommendation.why_recommended

Short explainable ranking reasons for agent logs

recommendation.trust_score_v5

Trust Score v5 decision, outcome confidence, install policy, compatibility, risk summary, and v4 compatibility data

agent_proven

0-100 outcome-backed adoption score with recent success/failure, install success, output quality, production use, and unique agent signals

install_receipt

Stable install receipt with selected skill, install policy, risk notes, alternatives, outcome event id, and next steps

decision_packet

Stable agent contract with selected skill, install plan, trust dimensions, do_not_use_when, alternatives, and outcome_feedback

agent_feedback_loop

Outcome reporting contract, quality fields, idempotency, and ranking inputs updated after a run

feedback

Outcome event id, outcome API URL, expected outcomes, and ready CLI command for reporting adoption results

agent_handoff

Platform copy prompts, API sequence, review checklist, expected output contract, and blocked actions

task- Required task description

agent- codex, claude-code, cursor, or auto

constraints.max_risk- low, medium, or high

constraints.needs_install_command- Require install handoff

POST /api/agent/resolve
{
  "task": "review a pull request and summarize risky changes",
  "agent": "codex",
  "constraints": {
    "max_risk": "medium",
    "needs_install_command": true,
    "min_stars": 500
  }
}

GET /api/agent/resolve?task=scrape+pricing+pages&agent=codex&max_risk=medium&format=text

GET/api/agent/receipt

Generate the stable install receipt for one resolved task. Agents should treat this as the pre-install execution record: selected skill, install command, safety policy, risk notes, alternatives, outcome event id, and next steps.

receipt_id

Durable id for the selected task-to-skill handoff

selected_skill

Skill URL, API URL, audit URL, eval URL, and repository

install

Command, target, policy, sandbox-first flag, and human-review requirement

risk

Audit label, safety tier, warnings, and do_not_use_when metadata

agent_proven

Outcome-backed score, label, summary, and metrics for whether agents have made the skill work

alternatives

Fallback skills with install commands and safety scores

outcome_feedback

event_id, POST endpoint, payload template, dry_run payload, and CLI example

GET /api/agent/receipt?task=scrape+pricing+pages&agent=codex&max_risk=medium&format=text

GET/api/agent/tasks

Task-first catalog for agents. Use it when the agent knows the job to be done but has not selected a skill yet.

GET /api/agent/tasks?format=text

POST/api/agent/outcome

Report what happened after an agent tried one resolved skill. These aggregate signals feed Trust Score v5, Agent-Proven rankings, skill detail pages, and the public Resolve eval dashboard.

success

The skill helped complete the task

failed

The skill was attempted but did not work

not_relevant

The selected skill did not fit the task

blocked_by_risk

The agent stopped because risk was too high

setup_required

The skill may work but required extra setup

output_quality

Optional 1-5 quality signal for the run output

used_in_production

Optional signal that the skill was useful beyond a sandbox run

human_review_required

Optional signal that the run needed human inspection before reuse

Agent Proven Score

Derived from total outcomes, recent success/failure, install success rate, output quality, production use, unique agents, and risk/setup penalties

error_type

Optional install_failed, runtime_error, permission_blocked, low_quality_output, timeout, or other

dry_run

Set true to validate a payload without writing a database row

GET /api/agent/outcome?skill_slug=crawl4ai

Read aggregate success and install-attempt stats

GET /api/agent/outcome?format=text

Read a compact machine-friendly outcome summary

source_version

Version, commit, content hash, ref, and path copied from the resolve receipt and verified against recorded source history

GET /api/agent/outcome?contract=true

Read the v4 version-attributed feedback contract

POST /api/agent/outcome
{
  "event_id": "resolve_...",
  "skill_slug": "crawl4ai",
  "task": "scrape pricing pages",
  "agent": "codex",
  "outcome": "success",
  "install_used": true,
  "task_success": true,
  "output_quality": 4,
  "workspace": "sandbox",
  "time_to_useful_ms": 120000,
  "source_version": {
    "version": "1.0.0",
    "commit_sha": "0123456789abcdef0123456789abcdef01234567",
    "content_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "ref": "main",
    "path": "SKILL.md"
  }
}

GET/api/agent/discovery

Public-safe status for the GitHub auto-discovery pipeline. Shows schedule, filters, thresholds, cross-domain query coverage, indexer health, and recent run summaries.

GET /api/agent/discovery

Private imports can target a domain such as domains:["finance"] for finance, quant, trading, market-data, portfolio, and filings skills.

GET/api/skills/search

Simple public registry search for humans, tools, and lightweight agents. Accepts task-style queries and returns ranked skills with trust, audit, URLs, and install handoffs.

q- Skill, task, platform, or workflow query

task- Alias for q when an agent sends a job description

min_stars- Optional minimum GitHub stars filter

GET /api/skills/search?task=scrape+pricing+pages&min_stars=500&limit=5

GET/api/skills/{slug}/install

Get the install command, agent prompt, target-specific install options, safety checklist, and canonical URLs for one skill.

GET /api/skills/crawl4ai/install?format=text

GET/api/agent/evals

Run registry regression checks, pass slug={skill} for one pre-install Trust + Eval contract, or pass slugs={a,b,c} to compare candidate skills before choosing one to install.

GET /api/agent/evals

GET /api/agent/evals?slug=crawl4ai&task=scrape+pricing+pages&format=text

GET /api/agent/evals?slugs=crawl4ai,markitdown&task=parse+PDFs+into+markdown

Use /evals/resolve for the public dashboard view of the same recommendation benchmark.

eval.status

passed, review, or failed

eval.decision

shortlist, manual_review, or do_not_auto_install

eval.checks

Required install gates plus supporting trust checks

eval.validation_plan

Concrete sandbox verification steps before production use

GET/api/badge/{slug}

Return an SVG README badge for a listed skill. Use metric=listed, trust, quality, stars, audit, or proven.

GET /api/badge/crawl4ai?metric=audit

GET/api/agent/skills

Search and filter agent skills.

Query Parameters

q- Search query

category- Filter by category

platform- Filter by platform

trust- Filter by trust tier: production, strong, review, risk

sort- Sort by: quality, stars, trending, fresh, new

format- Response format: json or text

Example Request

GET /api/agent/skills?q=web+research&trust=production&format=text

Example Response (text format)

=== Agent Skills Search Results ===

Total: 2 skills found

---
[1] Crawl4AI
- Slug: crawl4ai
- Category: Web Scraping
- Install: npx --yes https://github.com/Leon-Drq/openagentskill/releases/download/cli-v0.3.0/openagentskill-0.3.0.tgz add crawl4ai --dry-run
- Trust: 91/100 Production candidate
- Verified installs: 0
- Outcomes: 1
- Description: Web crawling and structured extraction for agent workflows

[2] Code Review Assistant
- Slug: code-review-assistant
- Category: Developer Tools
- Install: npx --yes https://github.com/Leon-Drq/openagentskill/releases/download/cli-v0.3.0/openagentskill-0.3.0.tgz add code-review-assistant --dry-run
- Trust: 77/100 Strong shortlist
- Verified installs: 0
- Outcomes: 0
- Description: Automated code review with security analysis

JSON responses include quality profiles, platform hints, install commands, repository links, and detail URLs.

GET/api/agent/recommend

Describe a task and get skill recommendations with readiness scores, role fit, risk notes, implementation steps, and related stack suggestions.

install_targetstrust.scoreaudit.audit_scoredecision.next_steps

GET /api/agent/recommend?task=scrape+websites+and+extract+tables&limit=4

GET/api/agent/packs

Get curated skill packs for complete workflows, including top skills, trust signals, install targets, and install_plan_url for agent execution.

limit- Skills per pack, max 10

format- Response format: json or text

install_plan_url- Fetch this URL when an agent needs the executable pack plan

GET /api/agent/packs?limit=5&format=text

GET/api/agent/packs/{slug}

Get one skill pack with ranked skills, audit scores, trust profiles, install commands, review checklist, outcome feedback, and an executable install_plan object.

install_plan.selected_skills- Ordered skill shortlist with install command, skill URL, audit URL, and risk level

install_plan.review_checklist- Pre-install checks an agent should complete before using the pack

install_plan.outcome_feedback- Endpoint and required fields for reporting whether the pack worked

GET /api/agent/packs/frontend-engineer-agent-pack?limit=8

GET/api/agent/rankings

Get ranked skill shortlists by quality, stars, freshness, new arrivals, workflow-specific use cases, or real Agent-Proven outcome evidence.

slug- Ranking slug, e.g. agent-proven, best-by-success-rate, safest-auto-install-skills, best-codex-skills, or best-web-scraping-skills

limit- Number of skills to return, max 30

format- Response format: json or text

GET /api/agent/rankings?slug=agent-proven&limit=5&format=text

GET/api/agent/weekly-report

Get a weekly operating report with editor picks, new skills, maintained projects, and engagement signals.

GET /api/agent/weekly-report?format=text

GET/api/agent/skills/{slug}

Get detailed information about a specific skill.

Example Request

GET /api/agent/skills/advanced-web-research?format=text

Example Response (text format)

=== Crawl4AI ===

INSTALL:
npx --yes https://github.com/Leon-Drq/openagentskill/releases/download/cli-v0.3.0/openagentskill-0.3.0.tgz add crawl4ai --dry-run

DESCRIPTION:
Comprehensive web research with multi-source aggregation

CATEGORY: Research & Analysis
PLATFORMS: LangChain, LlamaIndex

STATS:
- Verified installs: 0
- Outcomes: 1
- Trust: 91/100 Production candidate

TECHNICAL:
- Version: 2.3.1
- Languages: Python, TypeScript
- Repository: https://github.com/unclecode/crawl4ai
- License: MIT

USAGE:
This skill enables agents to perform comprehensive web research...

GET/api/audits/{slug}

Get the OpenAgentSkill audit report for a skill, including audit score, risk level, check results, warnings, and signals.

GET /api/audits/crawl4ai

audit.audit_scoreaudit.risk_levelaudit.checks[]audit.warnings[]

GET/api/badge/{slug}

Generate a README-friendly SVG badge for listed status, audit score, trust score, Agent Proven Score, quality score, or GitHub stars.

Example Markdown

[![Listed](https://www.openagentskill.com/api/badge/crawl4ai?metric=listed&label=Listed)](https://www.openagentskill.com/skills/crawl4ai)

[![Trust](https://www.openagentskill.com/api/badge/crawl4ai?metric=trust&label=Trust)](https://www.openagentskill.com/skills/crawl4ai)

[![Audit](https://www.openagentskill.com/api/badge/crawl4ai?metric=audit&label=Audit)](https://www.openagentskill.com/skills/crawl4ai/audit)

[![Quality](https://www.openagentskill.com/api/badge/crawl4ai?metric=quality&label=Quality)](https://www.openagentskill.com/skills/crawl4ai)

[![Agent Proven](https://www.openagentskill.com/api/badge/crawl4ai?metric=proven&label=Agent%20Proven)](https://www.openagentskill.com/skills/crawl4ai)

[![Stars](https://www.openagentskill.com/api/badge/crawl4ai?metric=stars&label=GitHub)](https://www.openagentskill.com/skills/crawl4ai)

Query Parameters

metriclisted, trust, audit, quality, stars, proven, or agent-proven. Defaults to listed.

labelOptional badge label, such as Quality or GitHub.

POST/api/skills/submit

Submit any valid SKILL.md from a GitHub repository, directory, or file URL. Zero-star repositories are eligible. The API returns a receipt immediately and reviews the submission asynchronously.

Request Body

repositoryGitHub repository URL (required) — e.g. https://github.com/owner/repo

skillPathExact SKILL.md path returned by POST /api/skills/validate (required)

categorySkill category (optional; auto-detected when omitted)

tagsArray of tags (optional)

submissionSourceSet to "agent" for automated submissions (optional, default: "web"). New web submissions require freeAcquisition: true. Legacy api/agent clients may omit it; their price remains unconfirmed. Explicit false is rejected while paid intake is closed. Never assert true without checking the complete skill files are freely obtainable; runtime/API fees are separate. This declaration does not bypass review.

submittedByAgentAgent identifier string, e.g. "openclaw-v1.2" (optional)

makerGithub / makerXOptional declared maker handles. They remain unverified until OAuth or repository ownership proof.

Example Request

POST /api/skills/submit
Content-Type: application/json

{
  "repository": "https://github.com/owner/my-skill",
  "skillPath": "SKILL.md",
  "tags": ["crawler", "llm", "python"],
  "makerGithub": "owner",
  "makerX": "owner_on_x",
  "submissionSource": "agent",
  "submittedByAgent": "openclaw-v1.2"
}

Example Response

{
  "success": true,
  "accepted": true,
  "submission": {
    "id": "7f3f...",
    "token": "private-status-token",
    "status": "submitted",
    "statusUrl": "/api/skills/submissions/7f3f...?token=...",
    "skill": { "name": "My Skill", "path": "SKILL.md" }
  }
}

OpenClaw Auto-Submit

Agents can submit a skill as soon as a valid SKILL.md is available. GitHub stars remain a ranking signal, not a publishing gate.

Add the webhook to your OpenClaw config

In your openclaw.config.yaml, add the submit endpoint as a publish target:

# openclaw.config.yaml
publish:
  - target: openagentskill
    url: https://openagentskill.com/api/skills/submit
    payload:
      skillPath: SKILL.md
      submissionSource: agent
      submittedByAgent: "openclaw-v1.2"

OpenClaw can POST when SKILL.md is created or updated

No star threshold is required. The agent can also trigger submission manually:

# Manually submit a specific repo via OpenClaw
openclaw publish --target openagentskill --repo owner/my-skill

AI review runs automatically

Every submission is persisted before review. Critical security findings are quarantined; other submissions are reviewed and published or kept in the community review queue.

Or call the API directly (no OpenClaw required)

curl -X POST https://openagentskill.com/api/skills/submit \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "https://github.com/your-org/your-skill",
    "skillPath": "SKILL.md",
    "tags": ["python", "llm"],
    "submissionSource": "agent",
    "submittedByAgent": "my-custom-agent"
  }'

Agent Protocol Discovery

AI agents can automatically discover our API capabilities via the standard agent protocol file:

GET /.well-known/agent-protocol.json

Rate Limits

Currently no rate limits for read operations. Fair use policy applies. For higher limits, contact us.