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, downloads, 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] Advanced Web Research
- Slug: advanced-web-research
- Category: Research & Analysis
- Install: npx skills add openagentskill/web-research
- Trust: 91/100 Production candidate
- Downloads: 45,230
- Rating: 4.8/5
- Description: Comprehensive web research with multi-source aggregation

[2] Code Review Assistant
- Slug: code-review-assistant
- Category: Developer Tools
- Install: npx skills add openagentskill/code-review
- Trust: 77/100 Strong shortlist
- Downloads: 38,912
- Rating: 4.7/5
- 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)

=== Advanced Web Research ===

INSTALL:
npx skills add openagentskill/web-research

DESCRIPTION:
Comprehensive web research with multi-source aggregation

CATEGORY: Research & Analysis
PLATFORMS: LangChain, LlamaIndex

STATS:
- Downloads: 45,230
- Stars: 3,421
- Trust: 91/100 Production candidate
- Rating: 4.8/5 (423 reviews)

TECHNICAL:
- Version: 2.3.1
- Languages: Python, TypeScript
- Repository: https://github.com/openagentskill/web-research
- 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 a GitHub repository as a skill. The repository must have at least 10 stars and pass static security analysis plus AI scoring before automatic publishing. Used by OpenClaw and other agents to submit skill candidates.

Request Body

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

categorySkill category (required)

tagsArray of tags (optional)

submissionSourceSet to "agent" for automated submissions (optional, default: "web")

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

Example Request

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

{
  "repository": "https://github.com/owner/my-skill",
  "category": "Web Scraping",
  "tags": ["crawler", "llm", "python"],
  "submissionSource": "agent",
  "submittedByAgent": "openclaw-v1.2"
}

Example Response

{
  "success": true,
  "approved": true,
  "skill": {
    "id": "...",
    "slug": "owner-my-skill",
    "name": "My Skill"
  },
  "review": {
    "approved": true,
    "totalScore": 36,
    "summary": "High quality skill with clear documentation",
    "policy": {
      "status": "approved",
      "min_stars": 10,
      "checks": ["GitHub adoption", "Static security scan", "AI total score"]
    }
  }
}

OpenClaw Auto-Submit

If you use OpenClaw, you can configure it to automatically publish your skills to Open Agent Skill whenever a repo crosses the 50-star threshold.

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
    trigger:
      stars_threshold: 50
    payload:
      submissionSource: agent
      submittedByAgent: "openclaw-v1.2"

OpenClaw will POST automatically when the threshold is reached

Once configured, every time a monitored repo crosses 10 stars, OpenClaw will call the submit API with the repo details. You can also trigger it manually:

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

AI review runs automatically

Submitted skills go through the same review pipeline as manual submissions: minimum-star gate, static security analysis, AI quality scoring, and a final publish policy gate. Only approved skills appear immediately with the activity feed noting they were discovered by OpenClaw.

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",
    "category": "Web Scraping",
    "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.