Apira for Coding Agents

This page is the setup prompt. Use the built-in “Copy page for LLM” action to copy the whole page into your coding agent and create or update a reusable Apira skill for discovering relevant GitHub repositories.

Goal

You are adding Apira as a reusable skill or tool for this coding agent.

Create or update an apira skill that lets the agent discover relevant GitHub repositories by semantic search before implementing unfamiliar, complex, or blocked work.

Apira is a semantic search API for GitHub repositories, built for AI agents. Use it when you need to find repositories by describing implementation intent, architecture, library usage, or code patterns.

When to use Apira

Use Apira when:

You need existing open-source implementations before building something complex.
You are blocked on an implementation detail and need real repositories to study.
You need libraries, frameworks, tools, starter templates, or architecture examples.
You need alternatives to a known dependency or approach.

Do not use Apira for:

Searching inside a known repository.
Fetching repository source files.
Non-GitHub web search.
Replacing license, security, or code-quality review.

API key setup

Read the API key from APIRA_API_KEY.

Do not hard-code, print, or log the API key. Send it as the X-API-Key header. If APIRA_API_KEY is missing, explain how to configure it and stop before making requests.

export APIRA_API_KEY="apira_your_key_here"

API contract

Base URL: https://api.apira.dev
Endpoint: POST /v1/github/search
Auth header: X-API-Key: $APIRA_API_KEY
Request fields: query, limit, includeTree, filters

Request shape

{
  "query": "specific implementation pattern or repository capability",
  "limit": 10,
  "includeTree": false,
  "filters": {
    "language": "typescript",
    "categories": ["agent"],
    "topics": ["cli"],
    "minStars": 100,
    "maxStars": 50000,
    "excludeArchived": true,
    "staleAfterMonths": 18,
    "excludeRepos": ["owner/repo"]
  }
}

Response shape

{
  "query": "specific implementation pattern or repository capability",
  "results": [
    {
      "name": "owner/repo",
      "url": "https://github.com/owner/repo",
      "description": "Repository summary",
      "score": 0.82,
      "language": "TypeScript",
      "stars": 12000,
      "forks": 800,
      "topics": ["agent", "cli"],
      "pushedAt": "2026-04-01T00:00:00.000Z",
      "isArchived": false,
      "llmsUrl": "https://raw.githubusercontent.com/owner/repo/main/llms.txt",
      "evidence": ["Why this repository matched the query..."],
      "tree": ["optional repository tree entries when includeTree is true"]
    }
  ],
  "meta": {
    "total": 10,
    "appliedFilters": {
      "language": "typescript",
      "categories": {
        "mode": "explicit",
        "values": ["agent"]
      }
    }
  }
}

Available request fields

query — required. Describe the behavior, architecture, implementation pattern, or repository capability you need.
limit — optional, 1–50. Use 5–10 for focused searches; use more only when comparing alternatives.
includeTree — optional. Set true when module layout matters before deeper inspection.
filters.language — exact GitHub language match.
filters.categories — repository type, such as agent, tool, framework, library, infrastructure, or starter.
filters.topics — owner-provided GitHub topics.
filters.minStars / filters.maxStars — maturity or niche bands.
filters.excludeArchived — exclude archived repositories.
filters.staleAfterMonths — freshness cutoff for active projects.
filters.excludeRepos — omit repositories already reviewed.

Response fields to inspect

results[].evidence — why the repository matched the query.
results[].score — relative ranking score within this result set.
results[].stars / results[].forks — adoption signals.
results[].pushedAt / results[].isArchived — freshness and maintenance signals.
results[].language / results[].topics — ecosystem fit.
results[].llmsUrl — maintainer-authored agent documentation when available.
results[].tree — repository structure when includeTree is enabled.
meta.appliedFilters — constraints Apira actually applied.

Search policy and best practices

Use an intent-rich natural-language query. Describe what you need to learn or build, and prefer implementation descriptions over keyword lists.

Good queries:

minimal terminal coding agent harness
TypeScript coding agent CLI with tool execution
reference implementation of OAuth token metering middleware
Kubernetes cost monitoring controller

Weak queries:

agent
terminal
auth
monitoring

Put behavior and architecture in query. Put non-negotiable constraints in filters. Avoid filtering out useful references too early.

Read meta.appliedFilters before explaining a filtered result set. Treat each result as a candidate, not a final answer. Read evidence before recommending repositories.

Shortlist repositories with rationale, caveats, and next inspection steps. Do not copy code blindly; license, security, fit, and code quality still need review.

When results are empty, noisy, or low confidence:

Remove optional filters first.
Broaden overly specific wording.
Search adjacent concepts.
Use excludeRepos after reviewing candidates.
Tell the user when confidence is low instead of overstating the result.

Retry and error behavior

On 400, revise the request before retrying.
On 401 or 403 authentication errors, report that APIRA_API_KEY is missing or invalid.
On 403 INSUFFICIENT_CREDITS, stop retrying and report the credit issue.
On 429, back off and honor Retry-After when present.
On 500, 502, or 503, retry with jitter and a small maximum attempt count.
Do not silently ignore failed searches.

Test search

After creating the skill, test it with this request if APIRA_API_KEY is available:

{
  "query": "minimal terminal coding agent harness",
  "limit": 10,
  "filters": {
    "language": "typescript",
    "categories": ["agent"],
    "minStars": 5000,
    "excludeArchived": true,
    "staleAfterMonths": 12
  }
}