# agentskill.work - LLM / Agent Reference (Full)

This file is a machine-friendly reference for agents and LLM-based tools that want to understand, cite, or integrate
with agentskill.work.

agentskill.work is a curated, searchable index of trending Claude Skill GitHub repositories. Data is aggregated from
GitHub metadata and is stored locally for fast search, paging, and SEO-friendly pages.

Important term policy:
- Keep the proper term "Claude Skill" as-is. Do NOT translate it (e.g., do not write "claude 技能").

Canonical host policy:
- Canonical host: https://agentskill.work
- https://www.agentskill.work redirects to https://agentskill.work

## Site URLs

- Home (Chinese): https://agentskill.work/zh
- Home (English): https://agentskill.work/en
- Latest list: https://agentskill.work/{lang}/latest
- Skill detail: https://agentskill.work/{lang}/skills/{owner}/{repo}
- GitHub repo (source of truth): https://github.com/{owner}/{repo}

## Sitemaps / robots (SEO)

- Sitemap index: https://agentskill.work/sitemap-index.xml
- Sitemap alias: https://agentskill.work/sitemap.xml (same as sitemap index)
- Facet sitemap (topics/languages/owners): https://agentskill.work/sitemap-facets.xml
- Robots: https://agentskill.work/robots.txt
- Site verification file (WeChat): https://agentskill.work/e5e588a3b46a049f7e2354fa3ba02fde.txt

## Public API

Base URL:
- https://agentskill.work/api

OpenAPI:
- https://agentskill.work/api/openapi.json
- https://agentskill.work/api/docs

Auth / rate guidance:
- Read endpoints are public (no auth).
- Write endpoints (e.g., manual sync) are disabled by default and must be protected by a token if enabled.
- Please use pagination (limit/offset) and avoid aggressive polling; data is refreshed on a schedule.

### Endpoints

1) List skills
- GET /skills

Query parameters (all optional unless stated):
- q: string
  - Full-text search (name/description/topics), server-side search only.
- topic: string
  - Filter by a single topic (exact topic match within the stored comma-separated topics string).
- language: string
  - Filter by primary programming language (case-insensitive).
- owner: string
  - Filter by GitHub owner (matches full_name prefix "{owner}/...").
- sort: string (default: stars)
  - stars: order by GitHub stars (descending)
  - newest: order by GitHub repo created time (repo_created_at desc; fallback to created_at)
- limit: integer (default: backend default, max: 100)
- offset: integer (default: 0)

Response shape:
{
  "total": number,
  "items": Skill[]
}

2) Get skill detail
- GET /skills/{owner}/{repo}

Response shape:
Skill

3) Facets (for discovery / sitemap generation)
- GET /facets/topics?limit=100
- GET /facets/languages?limit=50
- GET /facets/owners?limit=50

Response shape:
{
  "items": [{"value": string, "count": number}]
}

### Skill schema (as stored and returned)

Required-ish identifiers:
- id: number (local database id)
- repo_id: number (GitHub repository id)
- full_name: string (format: "{owner}/{repo}"; owner/repo can be derived by splitting on "/")
- html_url: string (GitHub repo URL)

Metadata:
- description: string | null
- description_zh: string | null (machine translation when enabled)
- summary_en: string | null (LLM-generated, offline)
- summary_zh: string | null (LLM-generated, offline)
- key_features_en: string[] | null (LLM-generated, offline)
- key_features_zh: string[] | null (LLM-generated, offline)
- use_cases_en: string[] | null (LLM-generated, offline)
- use_cases_zh: string[] | null (LLM-generated, offline)
- seo_title_en: string | null (LLM-generated, offline)
- seo_title_zh: string | null (LLM-generated, offline)
- seo_description_en: string | null (LLM-generated, offline)
- seo_description_zh: string | null (LLM-generated, offline)
- content_updated_at: string | null (ISO datetime; when enrichment content was generated)
- language: string | null (primary programming language from GitHub)
- topics: string | null (comma-separated GitHub topics; split on "," for an array)
- stars: number
- forks: number
- repo_created_at: string | null (ISO datetime from GitHub; repo created time)
- repo_updated_at: string | null (ISO datetime from GitHub; repo updated time)
- last_pushed_at: string | null (ISO datetime from GitHub)
- fetched_at: string (ISO datetime of last sync into local DB)

Notes:
- Some fields can be null depending on GitHub data availability.
- "topics" may be empty if GitHub topics are not set on that repo.

## Data freshness and background jobs

Data source:
- GitHub Search API (repositories)

Important constraint:
- GitHub API calls MUST NOT be triggered by end-user browsing (frontend).
  All GitHub API calls happen only in scheduled background jobs.

Scheduling:
- Celery beat triggers periodic sync jobs.
- Celery beat can also trigger offline enrichment jobs (DeepSeek), gated by ENABLE_ENRICHMENT.
- Sync fetches repos using two strategies:
  - Trending: GitHub Search sorted by stars (config: GITHUB_SEARCH_QUERY / GITHUB_MAX_PAGES / GITHUB_MAX_RESULTS)
  - Latest discovery: GitHub Search with a created window (created:>=YYYY-MM-DD) and sort=updated
    (config: GITHUB_NEWEST_WINDOW_DAYS / GITHUB_NEWEST_MAX_PAGES / GITHUB_NEWEST_MAX_RESULTS)
- Sync may stop early to avoid hitting GitHub API rate limits.

Rate-limit safety:
- GitHub rate limit guard will stop sync when remaining requests are low (buffer-based) or on 403/429 signals.
- Enrichment is batch-limited (ENRICH_BATCH_SIZE) and uses a Redis lock to avoid overlapping runs.

## Crawling / usage guidance

If you are an agent or crawler:
- Prefer the sitemap index for discovery.
- Prefer canonical pages under /zh or /en (language-stable URLs).
- Use the skill detail pages for citation (they include structured data and are designed for SEO).
- Avoid aggressive API crawling. Keep request rate low and honor caching.

Attribution guidance:
- Always cite the original GitHub repository URL when referencing a project.
- Do not imply endorsement by agentskill.work or by repository owners.

## License / rights

- agentskill.work aggregates public metadata from GitHub.
- The license of each project is determined by its own repository.
- Follow GitHub’s terms of service and each repository's license.