Skills

https://www.skills.sh/docs
Admin
Skills is a platform that provides reusable capabilities and procedural knowledge, acting as plugins...
Tokens:5,312
Snippets:69
Trust Score:6.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Get Skill Detail Request and Response

Source: https://www.skills.sh/docs/api

Example of fetching a specific skill's details including file contents and install counts.

```bash
curl "https://skills.sh/api/v1/skills/vercel-labs/skills/find-skills" \
  -H "Authorization: Bearer $VERCEL_OIDC_TOKEN"
```

```json
{
  "id": "vercel-labs/skills/find-skills",
  "source": "vercel-labs/skills",
  "slug": "find-skills",
  "installs": 24531,
  "hash": "a1b2c3d4e5f6...",
  "files": [
    { "path": "SKILL.md", "contents": "---\nname: Next.js Development\n..." },
    { "path": "examples/app-router.ts", "contents": "// Example code..." }
  ]
}
```

--------------------------------

### Install a skills pack

Source: https://www.skills.sh/docs/packs

Use this command to install a collection of skills from a specific pack URL.

```bash
npx skills add https://skills.sh/p/<pack-id>
```

--------------------------------

### Install a skill using CLI

Source: https://www.skills.sh/docs

Use the npx command to install a specific skill package into your environment.

```bash
npx skills add vercel-labs/agent-skills
```

--------------------------------

### Install a skill using npx

Source: https://www.skills.sh/docs/cli

Run the CLI directly without installation to add a skill.

```bash
npx skills add <skill-name>
```

--------------------------------

### Install Vercel OIDC Helper

Source: https://www.skills.sh/docs/api

Install the recommended helper package for managing request-scoped OIDC tokens.

```bash
npm install @vercel/oidc
```

--------------------------------

### Skill Detail Path Parameters

Source: https://www.skills.sh/docs/api

Examples of path construction for GitHub and well-known skill sources.

```text
/api/v1/skills/vercel-labs/skills/find-skills
```

```text
/api/v1/skills/mintlify.com/mintlify
```

--------------------------------

### GET /api/v1/skills/:source/:skill

Source: https://www.skills.sh/docs/api

Retrieves a skill's install count and full file tree, including SKILL.md and supporting files.

```APIDOC
## GET /api/v1/skills/:source/:skill

### Description
Get a skill's install count and full file tree (SKILL.md and any supporting files).

### Method
GET

### Endpoint
/api/v1/skills/:source/:skill

### Parameters
#### Path Parameters
- **source** (string) - Required - The source repository or provider (e.g., vercel-labs/skills).
- **skill** (string) - Required - The URL-safe skill slug.

### Response
#### Success Response (200)
- **id** (string) - Stable unique identifier.
- **source** (string) - Source repository or provider.
- **slug** (string) - URL-safe skill slug.
- **installs** (integer) - Total deduplicated install count.
- **hash** (string) - SHA-256 hash of the skill's file contents.
- **files** (array) - All files in the skill folder.
```

--------------------------------

### Example repository structure

Source: https://www.skills.sh/docs/customize

A typical repository layout showing the configuration file alongside skill definition files.

```text
skills.sh.json
skills/react-best-practices/SKILL.md
skills/deploy-to-vercel/SKILL.md
skills/web-design-guidelines/SKILL.md
```

--------------------------------

### Get Skill Audit Request and Response

Source: https://www.skills.sh/docs/api

Example of fetching security audit results for a specific skill.

```bash
curl "https://skills.sh/api/v1/skills/audit/vercel-labs/skills/find-skills"
```

```json
{
  "id": "vercel-labs/skills/find-skills",
  "source": "vercel-labs/skills",
  "slug": "find-skills",
  "audits": [
    {
      "provider": "Gen Agent Trust Hub",
      "slug": "agent-trust-hub",
      "status": "pass",
      "summary": "No risks detected",
      "auditedAt": "2026-04-15T12:00:00.000Z",
      "riskLevel": "LOW"
    },
    {
      "provider": "Socket",
      "slug": "socket",
      "status": "pass",
      "summary": "No alerts",
      "auditedAt": "2026-04-15T12:05:00.000Z"
    },
    {
      "provider": "Snyk",
      "slug": "snyk",
      "status": "pass",
      "summary": "Risk: LOW · No issues",
      "auditedAt": "2026-04-15T12:03:00.000Z",
      "riskLevel": "LOW"
    }
  ]
}
```

--------------------------------

### Add install count badge to README

Source: https://www.skills.sh/docs

Display a dynamic install count badge for your repository in your project's README file.

```markdown
[![skills.sh](https://skills.sh/b/owner/repo)](https://skills.sh/owner/repo)
```

```markdown
[![skills.sh](https://skills.sh/b/anthropics/skills)](https://skills.sh/anthropics/skills)
```

--------------------------------

### Configure skills.sh.json groupings

Source: https://www.skills.sh/docs/customize

A full example of the JSON configuration file defining skill groups and schema validation.

```json
{
  "$schema": "https://skills.sh/schemas/skills.sh.schema.json",
  "notGrouped": "bottom",
  "groupings": [
    {
      "title": "React",
      "description": "Skills for React and frontend engineering.",
      "skills": [
        "vercel-react-best-practices",
        "vercel-composition-patterns",
        "vercel-react-view-transitions"
      ]
    },
    {
      "title": "Vercel",
      "description": "Skills for deploying and optimizing on Vercel.",
      "skills": [
        "deploy-to-vercel",
        "vercel-cli-with-tokens",
        "vercel-optimize"
      ]
    }
  ]
}
```

--------------------------------

### Skill Audit Path Parameters

Source: https://www.skills.sh/docs/api

Examples of path construction for security audit endpoints.

```text
/api/v1/skills/audit/vercel-labs/skills/find-skills
```

```text
/api/v1/skills/audit/mintlify.com/mintlify
```

--------------------------------

### Update installed skills

Source: https://www.skills.sh/docs/packs

Updates all installed skills to their latest versions or targets a specific skill for an update.

```bash
npx skills update
```

```bash
npx skills update <skill>
```

--------------------------------

### GET /api/v1/skills

Source: https://www.skills.sh/docs/api

Retrieves the skill catalog from the API. Requires authentication via a Vercel OIDC token.

```APIDOC
## GET /api/v1/skills

### Description
Retrieves the skill catalog from the skills.sh platform.

### Method
GET

### Endpoint
https://skills.sh/api/v1/skills

### Authentication
Requires a Bearer token in the Authorization header, obtained via Vercel OIDC (e.g., process.env.VERCEL_OIDC_TOKEN or x-vercel-oidc-token header).
```

--------------------------------

### GET /api/v1/skills/curated

Source: https://www.skills.sh/docs/api

Returns the official curated set of first-party skills from companies and organizations.

```APIDOC
## GET /api/v1/skills/curated

### Description
Returns the official curated set of first-party skills. These are skills from companies and organizations that build the technology the skill is about.

### Method
GET

### Endpoint
/api/v1/skills/curated

### Request Example
curl "https://skills.sh/api/v1/skills/curated" -H "Authorization: Bearer $VERCEL_OIDC_TOKEN"
```

--------------------------------

### GET /api/v1/skills/search

Source: https://www.skills.sh/docs/api

Search for skills by name, source, or description. Single-word queries use fuzzy matching. Multi-word queries use semantic search for better relevance.

```APIDOC
## GET /api/v1/skills/search

### Description
Search for skills by name, source, or description. Single-word queries use fuzzy matching. Multi-word queries use semantic search for better relevance.

### Method
GET

### Endpoint
/api/v1/skills/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query. Minimum 2 characters.
- **limit** (integer) - Optional - Maximum results to return, 1-200. Default: 50.
- **owner** (string) - Optional - GitHub owner to search within.

### Request Example
curl "https://skills.sh/api/v1/skills/search?q=react%20native&owner=expo&limit=5" -H "Authorization: Bearer $VERCEL_OIDC_TOKEN"

### Response
#### Success Response (200)
- **data** (array) - List of matching skill objects.
- **query** (string) - The search query used.
- **searchType** (string) - "fuzzy" or "semantic".
```

--------------------------------

### GET /api/v1/skills

Source: https://www.skills.sh/docs/api

Returns a paginated list of skills from the leaderboard. Supports different views: all-time rankings, trending (recent growth), and hot (comparing the last hour to the same hour yesterday).

```APIDOC
## GET /api/v1/skills

### Description
Returns a paginated list of skills from the leaderboard. Supports different views: all-time rankings, trending (recent growth), and hot (comparing the last hour to the same hour yesterday).

### Method
GET

### Endpoint
/api/v1/skills

### Parameters
#### Query Parameters
- **view** (string) - Optional - "all-time" (default), "trending", or "hot".
- **page** (integer) - Optional - Page number, 0-indexed. Default: 0.
- **per_page** (integer) - Optional - Results per page, 1-500. Default: 100.

### Request Example
curl "https://skills.sh/api/v1/skills?view=trending&per_page=10" -H "Authorization: Bearer $VERCEL_OIDC_TOKEN"

### Response
#### Success Response (200)
- **data** (array) - List of skill objects.
- **pagination** (object) - Pagination metadata.
```

--------------------------------

### GET /api/v1/skills/audit/:source/:skill

Source: https://www.skills.sh/docs/api

Retrieves security audit results for a skill from available partners like Gen Agent Trust Hub, Socket, Snyk, Runlayer, and ZeroLeaks.

```APIDOC
## GET /api/v1/skills/audit/:source/:skill

### Description
Get security audit results for a skill from all available partners.

### Method
GET

### Endpoint
/api/v1/skills/audit/:source/:skill

### Parameters
#### Path Parameters
- **source** (string) - Required - The source repository or provider.
- **skill** (string) - Required - The URL-safe skill slug.

### Response
#### Success Response (200)
- **id** (string) - Stable unique identifier.
- **source** (string) - Source repository or provider.
- **slug** (string) - URL-safe skill slug.
- **audits** (array) - Security audit results from all available partners.
```

--------------------------------

### Configure Local Development Environment

Source: https://www.skills.sh/docs/api

Commands to link a project and pull environment variables for local development.

```bash
# one-time, per project
npm i -g vercel
vercel link            # link this directory to a Vercel project
vercel env pull        # writes VERCEL_OIDC_TOKEN into .env.local

# then run your app as usual
npm run dev
```

--------------------------------

### Define skills.sh.json file location

Source: https://www.skills.sh/docs/customize

The configuration file must be placed at the root of the GitHub repository.

```text
skills.sh.json
```

--------------------------------

### Retrieve Curated Skills

Source: https://www.skills.sh/docs/api

Fetch the official curated set of first-party skills.

```curl
curl "https://skills.sh/api/v1/skills/curated" \
  -H "Authorization: Bearer $VERCEL_OIDC_TOKEN"
```

--------------------------------

### Authenticate API Requests with Helper

Source: https://www.skills.sh/docs/api

Use the helper to retrieve a token and authorize requests. Call the token retrieval function inside the request handler to ensure the token remains valid.

```javascript
import { getVercelOidcToken } from '@vercel/oidc';

export async function GET() {
  const token = await getVercelOidcToken();

  const res = await fetch('https://skills.sh/api/v1/skills', {
    headers: { Authorization: `Bearer ${token}` },
  });

  return Response.json(await res.json());
}
```

--------------------------------

### Skills List Response Format

Source: https://www.skills.sh/docs/api

The JSON structure returned when listing skills, containing owner information and skill metadata.

```json
{
  "data": [
    {
      "owner": "vercel-labs",
      "totalInstalls": 89240,
      "featuredRepo": "skills",
      "featuredSkill": "find-skills",
      "skills": [
        {
          "id": "vercel-labs/skills/find-skills",
          "slug": "find-skills",
          "name": "find-skills",
          "source": "vercel-labs/skills",
          "installs": 24531,
          "sourceType": "github",
          "installUrl": "https://github.com/vercel-labs/skills",
          "url": "https://skills.sh/vercel-labs/skills/find-skills"
        }
      ]
    },
    {
      "owner": "supabase",
      "totalInstalls": 12084,
      "featuredRepo": "supabase",
      "featuredSkill": "Supabase",
      "skills": [...]
    }
  ],
  "totalOwners": 87,
  "totalSkills": 342,
  "generatedAt": "2026-03-31T08:00:00.000Z"
}
```

--------------------------------

### Retrieve Paginated Skills

Source: https://www.skills.sh/docs/api

Fetch a list of skills from the leaderboard with optional view and pagination parameters.

```curl
curl "https://skills.sh/api/v1/skills?view=trending&per_page=10" \
  -H "Authorization: Bearer $VERCEL_OIDC_TOKEN"
```

```json
{
  "data": [
    {
      "id": "vercel-labs/skills/find-skills",
      "slug": "find-skills",
      "name": "find-skills",
      "source": "vercel-labs/skills",
      "installs": 24531,
      "sourceType": "github",
      "installUrl": "https://github.com/vercel-labs/skills",
      "url": "https://skills.sh/vercel-labs/skills/find-skills"
    }
  ],
  "pagination": {
    "page": 0,
    "perPage": 10,
    "total": 8420,
    "hasMore": true
  }
}
```

--------------------------------

### Define skill slug in configuration

Source: https://www.skills.sh/docs/customize

Use the extracted slug as the value within the skills array in the configuration file.

```text
vercel-react-best-practices
```

--------------------------------

### Define API Base URL

Source: https://www.skills.sh/docs/api

The base URL for all API requests.

```text
https://skills.sh
```

--------------------------------

### Search Skills

Source: https://www.skills.sh/docs/api

Perform a fuzzy or semantic search for skills based on query parameters.

```curl
curl "https://skills.sh/api/v1/skills/search?q=react%20native&owner=expo&limit=5" \
  -H "Authorization: Bearer $VERCEL_OIDC_TOKEN"
```

```json
{
  "data": [
    {
      "id": "expo/skills/react-native",
      "slug": "react-native",
      "name": "React Native",
      "source": "expo/skills",
      "installs": 3842,
      "sourceType": "github",
      "installUrl": "https://github.com/expo/skills",
      "url": "https://skills.sh/expo/skills/react-native"
    }
  ],
  "query": "react native",
  "searchType": "semantic",
  "count": 5,
  "durationMs": 142
}
```

--------------------------------

### Identify skill URL

Source: https://www.skills.sh/docs/customize

The skill slug is derived from the final segment of the skill's URL on skills.sh.

```text
https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
```

--------------------------------

### Authenticate API Requests Manually

Source: https://www.skills.sh/docs/api

Read the OIDC token directly from environment variables without using the helper library.

```javascript
// Read fresh per request — do not cache the string
const token = process.env.VERCEL_OIDC_TOKEN;

await fetch('https://skills.sh/api/v1/skills', {
  headers: { Authorization: `Bearer ${token}` },
});
```

--------------------------------

### Error Response Format

Source: https://www.skills.sh/docs/api

Standard JSON structure returned for API errors.

```json
{
  "error": "error_code",
  "message": "Human-readable description."
}
```

--------------------------------

### Disable telemetry

Source: https://www.skills.sh/docs/cli

Opt out of anonymous telemetry collection by setting the environment variable.

```bash
DISABLE_TELEMETRY=1
```
Tokens:
Raw