# How to Define Custom Skills in Context7: A Complete Guide

> Learn to define custom skills in Context7 using SKILL.md files. Extend your AI coding assistant with domain specific knowledge and structured markdown instructions. Master reusable prompt bundles.

- Repository: [Upstash/context7](https://github.com/upstash/context7)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Custom skills in Context7 are reusable prompt bundles defined in a [`SKILL.md`](https://github.com/upstash/context7/blob/main/SKILL.md) file that extend AI coding assistants with domain-specific knowledge through a structured YAML front-matter format and markdown instructions.**

Context7 is an open-source tool for creating and managing AI coding assistant skills. Custom skills allow teams to encode best practices, security rules, and library-specific patterns into reusable components that any supported AI assistant can consume, ensuring consistent behavior across your development workflow.

## What Are Custom Skills in Context7?

Custom skills in Context7 function as **reusable prompt bundles** that inject domain-specific expertise into AI coding assistants. Unlike generic AI responses, these skills contain curated knowledge about specific libraries, frameworks, or organizational coding standards.

Each skill is essentially a small directory containing a mandatory **[`SKILL.md`](https://github.com/upstash/context7/blob/main/SKILL.md)** file that follows the **Agent Skills** open standard. This standard defines how AI assistants should interpret and apply the embedded instructions, making skills portable across different AI tools including Claude Code, Cursor, and Antigravity.

## The SKILL.md Format and Structure

The [`SKILL.md`](https://github.com/upstash/context7/blob/main/SKILL.md) file serves as the core contract between Context7 and AI assistants. According to the documentation in [`docs/skills.mdx`](https://github.com/upstash/context7/blob/master/docs/skills.mdx#L99-L106), the file consists of two distinct parts.

### YAML Front Matter

The file must begin with a YAML front-matter block delimited by triple dashes. This block declares the skill's metadata:

```yaml
---
name: nextauth-best-practices
description: Guidelines for secure, maintainable NextAuth.js integration
---

```

The `name` field serves as the skill's identifier, while the `description` helps AI assistants determine when to apply the skill based on user queries.

### Markdown Instructions

Following the front matter, the remainder of the file contains standard markdown that encodes the actual expertise. This section typically includes:

- **Overview sections** explaining core concepts
- **Security guidelines** with specific rules (e.g., "Always use HTTPS")
- **Code examples** demonstrating proper implementation patterns
- **Anti-patterns** highlighting common mistakes to avoid

The AI assistant prepends these instructions to its context when the skill is invoked, effectively constraining its responses to follow the encoded best practices.

## How to Create Custom Skills

Context7 provides an interactive CLI workflow for generating custom skills. The implementation in [[`packages/cli/src/commands/generate.ts`](https://github.com/upstash/context7/blob/main/packages/cli/src/commands/generate.ts)](https://github.com/upstash/context7/blob/master/packages/cli/src/commands/generate.ts) orchestrates a five-step process that transforms user input into structured skill files.

### Step 1: Describe the Expertise

The generation process begins with a free-form description of the knowledge domain. The CLI prompts the user to articulate what expertise the skill should encode, such as "React performance optimization patterns" or "Internal API authentication standards."

### Step 2: Select Source Libraries

Context7 searches its library index to find relevant repositories based on the description. The selection UI, implemented around [lines 52-63 of [`generate.ts`](https://github.com/upstash/context7/blob/main/generate.ts)](https://github.com/upstash/context7/blob/master/packages/cli/src/commands/generate.ts#L52-L63), allows users to select up to **five libraries** that provide the factual grounding for the skill.

### Step 3: Answer Clarifying Questions

To disambiguate scope, the service generates three focused questions via the `getSkillQuestions` function in [[`packages/cli/src/utils/api.ts`](https://github.com/upstash/context7/blob/main/packages/cli/src/utils/api.ts)](https://github.com/upstash/context7/blob/master/packages/cli/src/utils/api.ts). These questions might probe specific frameworks, security requirements, or team conventions to ensure the generated skill matches the intended use case.

### Step 4: AI Generation Process

The collected inputs—description, selected libraries, and clarifying answers—are sent to the Context7 skill generation endpoint (`/api/v2/skills/generate`). The streaming response is parsed by `handleGenerateResponse`, implemented at [lines 72-84 of [`api.ts`](https://github.com/upstash/context7/blob/main/api.ts)](https://github.com/upstash/context7/blob/master/packages/cli/src/utils/api.ts#L72-L84), which processes the AI-generated markdown content in real-time.

### Step 5: File Output and Structure

Finally, the generated markdown is saved as [`SKILL.md`](https://github.com/upstash/context7/blob/main/SKILL.md) inside a new folder designated by `skillDir`. As shown at [line 515 of [`generate.ts`](https://github.com/upstash/context7/blob/main/generate.ts)](https://github.com/upstash/context7/blob/master/packages/cli/src/commands/generate.ts#L515), the CLI creates the directory structure and writes the mandatory skill file. Users can optionally add templates, scripts, or example files to the same directory to enhance the skill's utility.

## How Custom Skills Are Consumed by AI Assistants

Once created, custom skills integrate seamlessly with AI coding assistants through a standardized discovery mechanism.

### Installation Paths for Different IDEs

Context7 supports multiple AI assistants through specific directory mappings defined in [[`packages/cli/src/types.ts`](https://github.com/upstash/context7/blob/main/packages/cli/src/types.ts)](https://github.com/upstash/context7/blob/master/packages/cli/src/types.ts). The `IDE_PATHS` and `IDE_GLOBAL_PATHS` constants at [lines 57-68](https://github.com/upstash/context7/blob/master/packages/cli/src/types.ts#L57-L68) specify where each assistant looks for skills:

- **Claude Code**: `~/.claude/skills/`
- **Cursor**: `~/.cursor/skills/` or `.cursor/skills/` (project-specific)
- **Antigravity**: `.agents/skills/`
- **Universal agents**: `.context7/skills/`

When you run `npx ctx7 skills install`, the CLI copies the skill files to the appropriate directory based on the target assistant flag (e.g., `--claude`).

### Runtime Integration

At runtime, AI assistants read the [`SKILL.md`](https://github.com/upstash/context7/blob/main/SKILL.md) files from their designated skill directories. When a user query matches the skill's description or scope, the assistant prepends the skill's markdown instructions to its system prompt. This injection happens transparently, constraining the AI's responses to follow the encoded patterns, security rules, and best practices without requiring the user to manually paste prompts.

## Trust and Security Considerations

Context7 implements several safeguards to ensure custom skills remain secure and trustworthy.

Each skill in the public registry carries a **trust score** (0-10) derived from automated safety scans that detect prompt injection attempts and verify content safety. For custom skills generated via the CLI, the system requires user authentication before installation and enforces quota limits through the `getSkillQuota` function in [[`packages/cli/src/utils/api.ts`](https://github.com/upstash/context7/blob/main/packages/cli/src/utils/api.ts)](https://github.com/upstash/context7/blob/master/packages/cli/src/utils/api.ts).

Blocked or unsafe skills trigger explicit error messages during the generation or installation process, preventing malicious or poorly constructed skills from entering the AI assistant's context.

## Code Examples

### Generating a Skill via CLI

Initiate the interactive skill generation workflow:

```bash

# Start the interactive generation process

npx ctx7 skills generate

```

The CLI will prompt you for a description, present library options, ask clarifying questions, and generate the skill files.

### Sample SKILL.md Structure

A minimal skill file following the Agent Skills standard:

```yaml
---
name: nextauth-best-practices
description: Guidelines for secure, maintainable NextAuth.js integration
---

# Overview

Provide a concise explanation of NextAuth concepts and configuration patterns.

# Security Requirements

- Always use HTTPS in production environments.
- Store OAuth secrets in environment variables, never in code.
- Implement CSRF protection for all authentication endpoints.

# Implementation Example

```ts
import NextAuth from "next-auth";
import GoogleProvider from "next-auth/providers/google";

export default NextAuth({
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    }),
  ],
  secret: process.env.NEXTAUTH_SECRET,
});

```

```

This format matches the specification documented in [`docs/skills.mdx`](https://github.com/upstash/context7/blob/master/docs/skills.mdx#L99-L106).

### Installing for Claude Code

Deploy a generated skill to Claude Code's skill directory:

```bash

# Install the skill into Claude Code's global skill directory

npx ctx7 skills install /my-org/skills nextauth-best-practices --claude

```

The CLI copies [`SKILL.md`](https://github.com/upstash/context7/blob/main/SKILL.md) and any associated assets into `~/.claude/skills/nextauth-best-practices/`, making the skill immediately available to Claude Code.

### Programmatic Access with Node SDK

Fetch and utilize skills programmatically using the Context7 SDK:

```ts
import { downloadSkill } from "context7-sdk";

async function loadSkill() {
  // Download skill files from GitHub repository
  const { files } = await downloadSkill("my-org/skills", "nextauth-best-practices");
  
  // Extract the SKILL.md content
  const skillMd = files.find(f => f.path === "SKILL.md")?.content;
  
  console.log(skillMd);
  // Use skill content to augment AI prompts or documentation
}

loadSkill();

```

The `downloadSkill` function internally calls `downloadSkillFromGitHub` (implemented in [[`packages/cli/src/utils/github.ts`](https://github.com/upstash/context7/blob/main/packages/cli/src/utils/github.ts)](https://github.com/upstash/context7/blob/master/packages/cli/src/utils/github.ts#L82-L84)) to retrieve all skill files from the repository.

## Summary

- **Custom skills in Context7** are reusable prompt bundles that encode domain-specific knowledge through the Agent Skills open standard.
- **Structure requirements**: Each skill requires a [`SKILL.md`](https://github.com/upstash/context7/blob/main/SKILL.md) file with YAML front matter (name, description) and markdown instructions.
- **Generation workflow**: The CLI guides users through describing expertise, selecting up to five source libraries, answering clarifying questions, and AI generation via `/api/v2/skills/generate`.
- **Consumption mechanism**: AI assistants read skills from specific directories (`.claude/skills`, `.cursor/skills`, etc.) and prepend instructions to their prompts at runtime.
- **Security features**: Trust scores, authentication requirements, and quota checks (`getSkillQuota`) ensure safe skill distribution and usage.

## Frequently Asked Questions

### What file format does Context7 use for custom skills?

Context7 uses the **Agent Skills** open standard, which requires a [`SKILL.md`](https://github.com/upstash/context7/blob/main/SKILL.md) file containing YAML front matter followed by markdown content. The YAML block declares the skill's `name` and `description`, while the markdown section contains the actual instructions, rules, and examples the AI assistant will use. This format is documented in [`docs/skills.mdx`](https://github.com/upstash/context7/blob/master/docs/skills.mdx#L99-L106) and ensures compatibility across different AI coding assistants.

### How many libraries can I reference when creating a custom skill?

You can reference up to **five libraries** when generating a custom skill through the Context7 CLI. During the interactive generation process implemented in [[`packages/cli/src/commands/generate.ts`](https://github.com/upstash/context7/blob/main/packages/cli/src/commands/generate.ts)](https://github.com/upstash/context7/blob/master/packages/cli/src/commands/generate.ts#L52-L63), the CLI searches Context7's library index and presents relevant repositories based on your expertise description. This limitation ensures the generated skill remains focused and contextually coherent while drawing from authoritative sources.

### Can I use custom skills with any AI coding assistant?

Yes, custom skills work with any AI coding assistant that supports the **Agent Skills** standard, including Claude Code, Cursor, Antigravity, and universal agents. Each assistant reads skills from specific directories defined in [[`packages/cli/src/types.ts`](https://github.com/upstash/context7/blob/main/packages/cli/src/types.ts)](https://github.com/upstash/context7/blob/master/packages/cli/src/types.ts#L57-L68), such as `~/.claude/skills/` for Claude Code or `.cursor/skills/` for Cursor. When you install a skill using `npx ctx7 skills install`, the CLI automatically places files in the correct location for your chosen assistant.

### Where are custom skills stored locally?

Custom skills are stored in assistant-specific directories within your home folder or project root. According to the `IDE_PATHS` and `IDE_GLOBAL_PATHS` definitions in [[`packages/cli/src/types.ts`](https://github.com/upstash/context7/blob/main/packages/cli/src/types.ts)](https://github.com/upstash/context7/blob/master/packages/cli/src/types.ts#L57-L68), Claude Code uses `~/.claude/skills/`, Cursor uses `~/.cursor/skills/` (global) or `.cursor/skills/` (project-specific), and Antigravity uses `.agents/skills/`. When generating skills via the CLI, the final output is written to a local `skillDir` as shown at [line 515 of [`generate.ts`](https://github.com/upstash/context7/blob/main/generate.ts)](https://github.com/upstash/context7/blob/master/packages/cli/src/commands/generate.ts#L515).