<div align="center">

<img src="./public/placeholder-logo.svg" alt="OpenAgentSkill" width="260" />

OpenAgentSkill

The skill layer for AI agents.

Let your AI agent find, compare, install, and report outcomes for the right reusable skill automatically.

OpenAgentSkill is npm for AI Agent Skills.

Try Resolve · Browse Skills · GitHub Skill Index · Outcome Loop · Audits · API Docs · Submit Skill

<br />

<img src="./public/github-homepage-preview.png" alt="OpenAgentSkill homepage showing the skill layer for AI agents" width="920" />

<br />

_{The skill layer for AI agents · Registry API · Trust Score · Auto installs}

</div>

Start Here

Why Star This Repo?

OpenAgentSkill is not another static directory. It is a registry, trust layer, and recommendation API designed for agents that need to choose and install reusable skills before acting.

Copy-Paste Agent Integration

Give this to Codex, Claude Code, Cursor, or any browser-capable agent:

Before installing a third-party skill, call OpenAgentSkill:

GET https://www.openagentskill.com/api/agent/resolve?task={TASK}&agent={AGENT}&max_risk=medium&format=json

Use the response to inspect:
- recommended_skill
- alternatives
- install_command
- trust_score
- audit_url
- risk_level
- do_not_use_when

Only install when the risk policy allows it. After trying the skill, report the result:

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

30-Second Demo

Ask OpenAgentSkill to resolve a task before your agent installs anything:

curl "https://www.openagentskill.com/api/agent/resolve?task=analyze+stock+news&agent=codex&max_risk=medium&format=text"

Example response shape:

OpenAgentSkill Resolve
Task: analyze stock news
Best skill: Serenity Skill
Trust Score: 83/100
Install: npx skills add muxuuu/serenity-skill
Risk: needs_review
Alternatives: OpenBB, Last30days Skill, VectorBT
Outcome API: https://www.openagentskill.com/api/agent/outcome

After one narrow run, report what happened:

curl -X POST "https://www.openagentskill.com/api/agent/outcome" \
  -H "content-type: application/json" \
  -d '{
    "event_id": "resolve_...",
    "skill_slug": "serenity-skill",
    "task": "analyze stock news",
    "agent": "codex",
    "outcome": "success",
    "install_used": true
  }'

Read the machine-friendly outcome summary:

curl "https://www.openagentskill.com/api/agent/outcome?format=text"

What Makes OpenAgentSkill Different?

Based on the public positioning of OpenAgentSkill, skills.sh, agentskills.io, and common GitHub skill lists:

OpenAgentSkill should sit between package-manager speed and audit-grade decision support: agents can still install quickly, but they first get a reasoned shortlist and risk profile.

Best Skills By Domain

How Agents Use It

1. Describe a task.
2. Call /api/agent/resolve.
3. Inspect the recommended skill, alternatives, Trust Score, audit URL, install plan, and risk policy.
4. Install in a sandboxed workflow only when the policy allows it.
5. Report the outcome through /api/agent/outcome.
6. Future rankings improve from aggregate feedback.

Useful endpoints:

For Skill Authors

Get your skill indexed, audited, ranked, and shareable.

• Public skill page with canonical URL.
• Trust Score and audit page.
• Install command and agent-readable metadata.
• README badge.
• X share card and launch copy.
• Claim/verified listing flow.
• Alternatives and use-case pages that can send qualified traffic back to your project.

Add a badge to your README:

[![OpenAgentSkill Trust](https://www.openagentskill.com/api/badge/YOUR-SLUG?metric=trust&label=Trust)](https://www.openagentskill.com/skills/YOUR-SLUG)
[![OpenAgentSkill Audit](https://www.openagentskill.com/api/badge/YOUR-SLUG?metric=audit&label=Audit)](https://www.openagentskill.com/skills/YOUR-SLUG/audit)

Submit or fix a skill:

• Website: openagentskill.com/submit
• GitHub issue: Skill submission

Core Product Surfaces

Trust Score

Trust Score is a decision signal for agents and builders. It combines:

• GitHub stars, forks, freshness, and maintenance.
• README/SKILL.md completeness.
• License clarity.
• Install command availability and safety.
• Permission and runtime risk hints.
• Audit score and risk level.
• Real agent outcome feedback.

Trust Score is not a security guarantee. It is a shortlist signal. Review source code before installing third-party skills in sensitive environments.

Auto-Discovery

The indexer scans GitHub for high-signal skill repositories and imports approved matches. MCP and Model Context Protocol repositories are intentionally excluded from automated imports.

Current production strategy:

• Grow toward 20,000+ approved skill listings.
• Prefer high-star, recently maintained repositories.
• Rotate across scenario-specific query groups.
• Cover coding, data, documents, finance, quant, research, security, DevOps, RAG, browser automation, commerce, marketing, support, legal, education, productivity, Web3, sports analytics, ML/media, science, and robotics.
• Submit fresh skill pages to IndexNow after imports.

Useful protected routes:

POST /api/indexer/run
GET  /api/indexer/run/coding-data
GET  /api/indexer/run/finance-research
GET  /api/indexer/run/growth-ops
GET  /api/indexer/run/frontier-expansion
POST /api/indexer/refresh-stars
POST /api/indexnow/submit

X Growth Loop

OpenAgentSkill can generate compliant X share drafts for indexed skills and creator replies.

GET  /api/x/share?skill_slug=crawl4ai
GET  /api/x/reply-draft?skill_slug=crawl4ai&tweet_url=https://x.com/user/status/123&format=json
POST /api/x/reply

Public draft endpoints generate copy and Web Intent URLs. Protected OAuth posting routes require explicit server-side authorization and an authorized X connection.

Tech Stack

Local Development

git clone https://github.com/Leon-Drq/openagentskill.git
cd openagentskill

pnpm install
cp .env.example .env.local
pnpm dev

Validation:

pnpm run lint
pnpm run build

Environment Variables

Never commit production secrets. Keep privileged Supabase and X credentials server-only.

Database Setup

Apply SQL files in scripts/ in order. The current schema includes:

• Skills catalog.
• Profiles and points.
• Activity and feedback events.
• Secure public-write RPCs.
• Indexer run logs.
• X OAuth token storage.
• Claims and skill events.
• Hardened RLS policies.
• Skill audits and daily event aggregates.
• Agent outcome feedback and aggregate success signals.

Latest outcome-feedback migration:

scripts/015_agent_outcomes_and_resolve_evals.sql

Project Structure

app/
  api/
    agent/        Agent-friendly search, rankings, recommendation, feedback, outcomes
    audits/       Skill audit API
    badge/        SVG badge API
    indexer/      Protected import and maintenance jobs
    x/            X OAuth, Web Intent, and optional posting routes
  skills/         Skill directory and detail pages
  outcomes/       Agent outcome loop page
  audits/         Audit index
  best/           Best-of ranking pages
  trending/       Trending skills
  hot/            Hot skills
  agents/         Agent-specific pages
  official/       Creator pages
  compare/        Comparison pages
  guides/         Guides and SEO content

lib/
  audits.ts       Audit scoring and normalization
  quality.ts      Quality profiles
  trust.ts        Trust scoring
  decision.ts     Adoption-readiness profile
  rankings.ts     Ranking logic
  indexer/        GitHub discovery and import pipeline
  db/             Supabase data access
  seo/            Programmatic SEO page data

scripts/
  *.sql           Supabase migrations
  *.mjs, *.ts     Content and seed scripts

Roadmap

See ROADMAP.md.

Security

See SECURITY.md. OpenAgentSkill does not guarantee that third-party skills are safe. Treat Trust Score and audits as decision support, not a replacement for source review and sandboxed execution.

Contributing

See CONTRIBUTING.md. Useful contribution types include skill submissions, metadata fixes, audit improvements, API improvements, SEO guide contributions, and UI fixes.

License

MIT. See LICENSE.