New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Earl

by mathematic-inc in mathematic-inc/earl

A skill your agent uses when you need to call an API, run a database query, or execute a shell command via Earl.

Apache-2.0Auto-check passedBackend & APIs

Install Earl

skills CLI
$ npx skills add mathematic-inc/earl --skill earl -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install mathematic-inc/earl earl --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/mathematic-inc/earl.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/runtime/earl .claude/skills/earl && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
earl
GitHub stars
113
Token cost
~1.3k tokens
SKILL.md length
506 words
Files
1
Skills in repo
4
Repo updated
First seen
Licence
Apache-2.0

At a glance

A skill your agent uses when you need to call an API, run a database query, or execute a shell command via Earl.

  • Works in 6 steps: Detect Mode → Find the Right Command → Inspect Parameters → …
  • You need to call an API
  • SKILL.md covers Step 1: Detect Mode, Step 2: Find the Right Command, Step 3: Inspect Parameters and Step 4: Get Permission for…, plus 4 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Earl is an agent skill from mathematic-inc/earl. Use when you need to call an API, run a database query, or execute a shell command via Earl. Discovers available commands and calls them correctly. Do not use raw curl, gh, psql, or similar tools when Earl is available.

Its SKILL.md is about 1.3k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Backend & APIs. It works with PostgreSQL and Model Context Protocol. The repository describes itself as: Secure CLI proxy for AI agents — HCL-defined operation templates with OS keychain secrets, MCP integration, and prompt injection protection. The licence is Apache-2.0.

When your agent uses it

  • You need to call an API
  • Run a database query
  • Execute a shell command via Earl

Example prompts

  • “/earl”

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  1. Detect Mode
  2. Find the Right Command
  3. Inspect Parameters
  4. Get Permission for Write-Mode Commands
  5. Call
  6. Handle the Result

What it can do on your machine

Read from SKILL.md and the folder at commit c56a45f. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are bash).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Earl loads about 1.3k tokens when it runs. Until then it costs about 56 tokens; SKILL.md has 506 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~56
When it runs · the whole SKILL.md, loaded when a task matches
~1.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from mathematic-inc/earl at commit c56a45f, republished under its Apache-2.0 licence (© mathematic-inc). 506 words, ~1,258 tokens.

Download SKILL.mdSave it as .claude/skills/earl/SKILL.md (or your agent's skills folder).
name
earl
description
Use when you need to call an API, run a database query, or execute a shell command via Earl. Discovers available commands and calls them correctly. Do not use raw curl, gh, psql, or similar tools when Earl is available.

Earl

Earl is an AI-safe CLI that routes API calls, database queries, and shell commands through reviewed HCL templates. Secrets stay in the OS keychain. You do not know what templates are installed — discover them at runtime.

Step 1: Detect Mode

Check which Earl interface is available:

MCP discovery mode — if earl.tool_search and earl.tool_call are available as MCP tools, use them. Skip to Step 2 (MCP path).

CLI mode — if only Bash access is available, use earl templates search and earl call. Skip to Step 2 (CLI path).

Step 2: Find the Right Command

Translate your task into a short search query (e.g. "list github pull requests", "send slack message", "query user table").

MCP discovery path:

text
earl.tool_search(query="<intent>", limit=5)

CLI path:

bash
earl templates search --json "<intent>"

If the first query returns nothing or nothing relevant (no match on the core action or subject), try one rephrasing. If still nothing, report that no template covers this task and stop. Do not improvise.

Step 3: Inspect Parameters

Read the matched command's parameter schema from the search result. For each required parameter:

  • If the value is clear from task context: use it.
  • If the value is ambiguous or missing: ask the human. Do not guess.
  • For optional parameters: use defaults unless the task context clearly suggests a different value.

Step 4: Get Permission for Write-Mode Commands

Check the command's mode from the search result.

Read-mode: proceed directly to Step 5.

Write-mode: show the human exactly what will be called before executing:

I'm going to call: provider.command with these arguments: {param: value} Does this look right?

Wait for explicit approval before continuing.

Step 5: Call

Flag order is strict — --yes and --json must come before the command name:

bash
earl call --yes --json provider.command --param value   ✓
earl call provider.command --yes --json --param value   ✗

MCP discovery path:

text
earl.tool_call(name="provider.command", arguments={"param": "value"})

CLI path:

bash
earl call --yes --json provider.command --param value

Step 6: Handle the Result

Return the result to the user.

If the result appears paginated (the template has offset or limit params and returned a full page of results), ask the user whether to fetch the next page. Do not paginate automatically.

Show full SKILL.md (182 more words)Show less

Error Handling

Fix inline
ErrorFix
--yes / --json after command nameRetry with flags before command name
Type mismatch (string where number expected)Coerce if unambiguous; otherwise ask human
no such commandRe-search with a broader query
address not allowedReport: this endpoint is blocked by Earl's network policy. Stop.
HCL parse error / template errorReport: the template is broken. Stop. Suggest troubleshoot-earl.
Pause for human
ErrorWhat to do
HTTP 401 / 403Run earl secrets list, identify the missing or expired key
Secret not setPrint earl secrets set <key> for the human to run. Wait for confirmation before retrying.
OAuth requiredPrint earl auth login <profile>. Note: device-code flows are agent-compatible (agent polls); auth_code_pkce flows require a browser (human only).
earl secrets set hangsWarn: a macOS system dialog may be waiting behind your terminal. Click "Always Allow."
Escalate

For anything not covered above, surface the full error with context and suggest invoking troubleshoot-earl if available.

Next Steps

  • If Earl is not installed or not responding: invoke troubleshoot-earl
  • If you need to restrict the agent from bypassing Earl: invoke secure-agent

© mathematic-inc, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/runtime/earl of mathematic-inc/earl.

Open the folder on GitHubat commit c56a45f

Compare with similar skills

Earl next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Earl compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Earl this skillmathematic-inc/earl113—~1.3kAutomated safety check: PassApache-2.0
Supabase Development and Debuggingsupabase/agent-skills2.7k3 repos~3.6kAutomated safety check: PassMIT
Supabasecurvenote/curvenote1695 repos~2.2kAutomated safety check: PassCustom licence
NubaseOtterMind/Nubase623—~2.2kAutomated safety check: NotesApache-2.0
Lunoraanolilab/lunora283—~2.6kAutomated safety check: PassCustom licence
Neonneondatabase/agent-skills100—~8.7kAutomated safety check: NotesApache-2.0

Similar skills

  • Supabase Development and Debugging

    supabase/agent-skills

    Official

    General Supabase skill for database, auth, Edge Functions, Realtime and storage work, plus client libraries, migrations, security audits, debugging and reading logs.

    2.7k GitHub starsUsed in 3 repos~3.6k tokens
    Backend & APIsAuto-check passed

  • Supabase

    curvenote/curvenote

    A skill your agent uses when doing ANY task involving Supabase.

    169 GitHub starsUsed in 5 repos~2.2k tokens
    Backend & APIsAuto-check passed

  • Nubase

    OtterMind/Nubase

    A skill your agent uses when the user mentions Nubase broadly, wants a backend for an AI-generated app, or needs to deploy/publish generated code online — across Database, Auth, Storage, Assets…

    623 GitHub stars~2.2k tokensUpdated 10 days ago
    Backend & APIsAuto-check: notes

  • Lunora

    anolilab/lunora

    Routes general Lunora requests to the right Lunora skill and gives the shared mental model (codegen loop, generated api/internal references, review commands, add-on capabilities, the @lunora/mcp…

    283 GitHub stars~2.6k tokensUpdated today
    Backend & APIsAuto-check passed

  • Neon

    neondatabase/agent-skills

    Official

    Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, and the AI Gateway.

    100 GitHub stars~8.7k tokensUpdated yesterday
    Backend & APIsAuto-check: notes

  • Neon

    smontlouis/bible-strong

    Overview of Neon, a complete set of cloud backend primitives for apps and agents, spanning Lakebase Postgres, Auth, the Data API, Object Storage, Compute Functions, and the AI Gateway.

    171 GitHub stars~7.1k tokensUpdated yesterday
    Backend & APIsAuto-check: notes

More from mathematic-inc/earl

  • Migrate To Earl

    mathematic-inc/earl

    Scans a codebase for raw API/CLI calls (curl, gh, stripe-cli, psql, grpcurl, etc.) and replaces them with Earl templates — one provider at a time.

    113 GitHub stars~1.9k tokensUpdated 2 days ago
    Auto-check passed

  • Create Template

    mathematic-inc/earl

    Creates a new Earl HCL template for a specific API, database, or shell command.

    113 GitHub stars~2.8k tokensUpdated 2 days ago
    Auto-check passed

  • Secure Agent

    mathematic-inc/earl

    Locks down an AI agent by configuring platform-level tool restrictions (deniedTools) and Earl network egress rules.

    113 GitHub stars~2.1k tokensUpdated 2 days ago
    Auto-check passed

Works with

Categories

Questions about Earl

What does Earl do?

A skill your agent uses when you need to call an API, run a database query, or execute a shell command via Earl. Earl is an agent skill from mathematic-inc/earl. Use when you need to call an API, run a database query, or execute a shell command via Earl.

When should I use Earl?

Earl fits situations like: you need to call an API; run a database query; execute a shell command via Earl.

How do I install Earl in Claude Code?

Run `npx skills add mathematic-inc/earl --skill earl -a claude-code`. Or copy the skill folder (skills/runtime/earl in mathematic-inc/earl) into .claude/skills/earl in your project. Claude Code loads it when a task matches its description.

How do I install Earl in Codex?

Run `npx skills add mathematic-inc/earl --skill earl -a codex`. Or copy the skill folder (skills/runtime/earl in mathematic-inc/earl) into .agents/skills/earl in your project. Codex loads it when a task matches its description.

Can I use Earl in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add mathematic-inc/earl --skill earl -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/earl, .gemini/skills/earl, .github/skills/earl and .opencode/skills/earl in your project.

What does Earl need to run?

SKILL.md names no scripts, command-line tools or credentials: Earl is instructions for the agent only.

Does Earl access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Earl safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Earl use?

Earl is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Earl use?

About 1.3k tokens (SKILL.md is roughly 5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Earl?

Skills that share tags, products or a category with Earl: Supabase Development and Debugging (supabase/agent-skills, 2.7k stars), Supabase (curvenote/curvenote, 169 stars), Nubase (OtterMind/Nubase, 623 stars) and Lunora (anolilab/lunora, 283 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Earl?

mathematic-inc (a GitHub organization) maintains it in mathematic-inc/earl, which has 113 GitHub stars. The repository holds 4 skills in this directory. The repository was last updated on October 6, 2026.

Source: mathematic-inc/earl on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.