# Public Agent Skills Index - Agent Guide

Discovery engine and safety monitor for GitHub `SKILL.md` documents.

Current Indexed Statistics:
- Total Skills: 24109
- Total Repositories: 90
- Verified Authors/Owners: 3756

## Main Endpoints
- REST Search API: `/api/search?q=<query>`
- OpenAPI Swagger Documentation: `/docs`
- Streamable HTTP MCP: `/mcp`
- Database stats: `/api/stats`
- Skill Metadata by ID: `/api/skills/{id}`
- Raw Markdown download for cleared skills only: `/raw/{id}.md`
- Catalog Export JSONL: `/catalog.jsonl.zst`
- Full SQLite Dump: `/skills.sqlite.zst`

## Search API Specification
Endpoint: `GET /api/search`

Query parameters:
- `q`: search string (e.g. `python scraping`, `pdf parsing`).
- `limit`: Clamp range (1-50, default 10).
- `offset`: pagination offset.
- `sort`: `relevance` | `stars` | `recent` | `quality` | `risk_low`.
- `owner` / `repo`: Filter results to specific GitHub origins.
- `language` / `topic`: Filter by repo features.
- `risk`: `safe` (default) | `exclude_quarantined` | `include_suspicious` | `all`.
- `quality`: `all` (default) | `exclude_low` (hide llm_quality_score<0.5) | `high` (only is_high_quality=1) | `deduped_high` (high quality and not marked as duplicate).

### Example Query
`GET /api/search?q=plotting&sort=stars&limit=3`

Each result includes a `safety.safe_to_use` decision. Agents should only install,
execute, or import skills when `safety.safe_to_use` is true.

## Safety Audit Classifications
We evaluate all files through regex scanners and assign a `risk_level`:
- `low`: Clean, standard guidelines.
- `medium`: Requires elevated caution; not cleared for automatic agent use.
- `high` / `critical`: Highly suspicious (raw base64, direct shell piping like `curl | sh`, file edits).
- `quarantined`: Malicious file, excluded from default searches.

The strict safe policy only clears skills with `risk_level=low`, `risk_score<=0.05`,
and no risk flags. Raw Markdown and ZIP bundle endpoints reject anything outside
that policy.

## Safety Guidelines
- Never execute shell configurations or code directly from an indexed `SKILL.md` file without containment/sandboxing.
- Carefully inspect structural risk flags (e.g., `remote_execution_detected`, `credential_harvesting_heuristics`) provided in the response metadata.
- Do not use the `all` risk filter for automatic installation. It is only for auditing.

## Public Exports
To mirror this index or perform heavy analytical operations, download static files directly:
- Zstandard JSONL catalog: `/catalog.jsonl.zst`
- Zstandard SQLite database: `/skills.sqlite.zst`