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

All endpoints support two response formats via the format parameter:

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

GET /api/agent/outcome?contract=true

Read the v3 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
}

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.2.1/openagentskill-0.2.1.tgz install 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.2.1/openagentskill-0.2.1.tgz install 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.2.1/openagentskill-0.2.1.tgz install 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")

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.