Add an Oathe Trust Badge to Your Skill's README
Let users know your AI agent skill has been security-audited. One line of markdown.
You built a skill. You tested it. You know it’s safe. But the person reading your README doesn’t know that — and they have no reason to trust you.
That’s not a dig. It’s just reality. The MCP ecosystem is growing fast, and users are making snap decisions about which skills to install. They’re scanning READMEs, checking stars, and looking for signals. A trust badge is one of the strongest signals you can give them.
Think about it from the other side: a README with no security badge is a README that’s asking users to take the author’s word for it. In an ecosystem where skills can read files, make network requests, and execute code on the host machine, that’s a big ask. The absence of a trust signal is a signal — it tells security-conscious users (and the AI agents advising them) that this skill hasn’t been independently verified.
Why Badges Work
Badges are a solved pattern. Every serious open-source project uses them — build status, code coverage, license type. Developers have been trained to look at the badge row at the top of a README and extract trust signals in seconds.
An Oathe badge does the same thing for security. It tells the user: this skill has been through a behavioral audit, here’s the score, and you can verify it yourself. No hand-waving. No “trust me, bro.” Just a score backed by an isolated execution environment that actually ran the skill and observed what it did. In a world where agent security is a behavioral problem, visible trust signals like this matter.
If your skill scores well, you should be showing that off.
The Badge
Oathe badges are powered by Shields.io, the same service behind almost every badge you’ve ever seen on GitHub. We expose a JSON endpoint that Shields.io consumes to render the badge dynamically.
The URL format is:
https://img.shields.io/endpoint?url=https://audit-engine.oathe.ai/api/badge/{org}/{repo}Replace {org} with your GitHub organization or username, and {repo} with your repository name. That’s it.
Adding It to Your README
Markdown (one line — just drop it at the top of your README):
[](https://oathe.ai/skills?url=https://github.com/{org}/{repo})HTML (useful for npm READMEs or anywhere markdown isn’t rendered):
<a href="https://oathe.ai/skills?url=https://github.com/{org}/{repo}">
<img src="https://img.shields.io/endpoint?url=https://audit-engine.oathe.ai/api/badge/{org}/{repo}" alt="Oathe Trust Score" />
</a>Again, swap {org}/{repo} for your actual GitHub org and repo name. For example, if your repo is acme/weather-skill, the URL becomes .../api/badge/acme/weather-skill.
What the Badge Shows
The badge renders two things: your trust score and a color.
The trust score is the composite score from your most recent Oathe audit, displayed as a value out of 100 alongside the verdict (e.g., “85/100 SAFE”). It’s calculated across six behavioral dimensions defined by the Open Threat Classification. The color maps directly to the audit verdict:
| Color | Verdict |
|---|---|
| Bright green | SAFE |
| Yellow | CAUTION |
| Orange | DANGEROUS |
| Red | MALICIOUS |
| Light grey | Not scanned |
If your skill hasn’t been audited yet, the badge shows “not scanned” in grey. That’s your cue to get an audit first.
Behind the badge, the full audit report includes an explicit recommendation: INSTALL, INSTALL_WITH_CAUTION, REVIEW_BEFORE_INSTALL, or DO_NOT_INSTALL. The badge is the visible summary; the recommendation is the actionable signal that AI agents and security-conscious developers use to decide whether to proceed.
Get Audited First
The badge only works if you’ve been audited. If you haven’t done that yet, the process is simple:
- Go to oathe.ai.
- Submit your skill’s GitHub URL.
- Wait for the audit to complete — usually under two minutes.
- Once it’s done, the badge endpoint goes live automatically.
You can also submit via the API (POST /api/submit) or directly from your AI agent with npx oathe-mcp.
Oathe is free during beta. There’s no API key, no paywall, no waitlist. Submit your repo and you’ll have a badge-ready audit in minutes.
Cache Behavior
Shields.io caches badge responses based on the Cache-Control header we return. Our endpoint sets max-age=3600, which means your badge updates within 1 hour of a new audit. If you re-audit your skill after a code change, the badge will reflect the new score within that window.
You don’t need to bust the cache manually. Shields.io handles this automatically based on the header.
A Note on Shields.io
The badge is rendered by Shields.io, a third-party service. It’s extremely reliable — it serves billions of badges per month — but it is a dependency outside our control. If Shields.io is temporarily unreachable, your badge may render as broken or fail to load. This is rare, but worth knowing about. It has no effect on your audit data or trust score — only on whether the badge image renders.
Ship the Signal
You put in the work to build a clean, well-behaved skill. The badge is how you prove it. One line of markdown, and every visitor to your repo sees that you took security seriously enough to get audited. To keep the badge current as your skill evolves, automate auditing in your CI/CD pipeline so every push re-validates your score.
Add the badge. Get your audit if you haven’t already.