How to Define Custom Skills in Context7: A Complete Guide

Custom skills in Context7 are reusable prompt bundles defined in a 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 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 file serves as the core contract between Context7 and AI assistants. According to the documentation in docs/skills.mdx, 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:

---
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/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/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/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/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 inside a new folder designated by skillDir. As shown at [line 515 of 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/master/packages/cli/src/types.ts). The IDE_PATHS and IDE_GLOBAL_PATHS constants at lines 57-68 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 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/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:

# 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:

---
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 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:

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/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 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 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 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/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/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/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/master/packages/cli/src/commands/generate.ts#L515).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}