Integrating Skills Plugin with Claude Code, OpenAI Codex, Gemini CLI, and Cursor

The Hugging Face Skills repository provides platform-specific manifest files—located in .claude-plugin/, .cursor-plugin/, and the repository root—that register self-contained AI/ML skills with Claude Code, OpenAI Codex, Gemini CLI, and Cursor, enabling agents to discover and execute instructions defined in individual SKILL.md files.

The Hugging Face Skills repository packages specialized AI/ML workflows into reusable, self-contained bundles. Each skill resides in its own folder under skills/ and contains a SKILL.md file with YAML front-matter describing its purpose, parameters, and usage patterns. To make these skills accessible across major coding assistants, the repository includes dedicated integration manifests that conform to each platform's plugin architecture.

Understanding the Skills Architecture

Every skill in the repository follows a consistent folder layout. Inside skills/<skill-name>/, the SKILL.md file provides the primary interface: YAML front-matter containing name, description, and optional tags, followed by detailed prose, code snippets, and guardrails. Helper assets—such as Jinja templates in templates/ or executable scripts in scripts/—are referenced relative to the skill folder.

The agents/AGENTS.md file aggregates the front-matter from every SKILL.md into a single machine-readable list. This file serves as a fallback for agents that scan the .agents/skills directory layout but only read a single summary file. The repository includes a generation script, scripts/generate_agents.py, which regenerates AGENTS.md and the platform-specific marketplace JSON files whenever skills are added or updated.

Claude Code Integration

Claude Code discovers skills through the .claude-plugin/plugin.json manifest. This file registers the repository as a Claude Code marketplace plugin and lists the available skill names.

To install the skills bundle:

# Register the repository as a Claude Code marketplace

/plugin marketplace add huggingface/skills

# Install a specific skill (e.g., hugging-face-cli)

/plugin install hugging-face-cli@huggingface/skills

Once installed, you can reference the skill in natural language:

Claude, use the hugging-face-cli skill to list all datasets in my organization.

Claude Code loads the instructions from the skill's SKILL.md file, executes the associated CLI commands on your local machine, and streams the output back to the conversation.

OpenAI Codex Integration

OpenAI Codex discovers skills via the standard .agents/skills directory layout. The agents/AGENTS.md file serves as the primary discovery mechanism for Codex, aggregating all skill front-matter so the agent can enumerate available capabilities without parsing individual markdown files.

To make skills available to Codex:

# Create the Codex skills directory if it doesn't exist

mkdir -p ~/.agents/skills

# Copy or symlink the desired skill

cp -r /path/to/skills/huggingface-gradio ~/.agents/skills/

# Or use a symlink for easier updates

ln -s /path/to/skills/huggingface-gradio ~/.agents/skills/huggingface-gradio

When you prompt Codex with a skill reference, such as "Use the gradio skill to build a simple demo that greets a user," Codex reads skills/huggingface-gradio/SKILL.md and generates code adhering to the documented component signatures and patterns.

Gemini CLI Integration

The Gemini CLI loads skills through the gemini-extension.json manifest in the repository root. This file defines a Gemini Extension that points to the aggregated skill documentation.

To install the skill bundle:

# Local installation from a cloned repository

gemini extensions install . --consent

# Or install directly from GitHub

gemini extensions install https://github.com/huggingface/skills.git --consent

After installation, the extension injects agents/AGENTS.md into the Gemini session context. You can then reference skills naturally:

Gemini, using the hugging-face-model-trainer skill, generate a script that fine-tunes a Llama-2 13B model on a JSONL dataset.

The Gemini CLI resolves the skill reference against the injected documentation and generates code following the skill's specified patterns and guardrails.

Cursor Integration

Cursor discovers skills through the .cursor-plugin/plugin.json manifest and executes them via an MCP (Model Context Protocol) server configured in .mcp.json.

To add the skills to Cursor:

1. Open the Cursor plugin marketplace and add the repository URL: https://github.com/huggingface/skills
2. Cursor reads .cursor-plugin/plugin.json to discover the skills/ directory path and available skill names.
3. For remote execution, Cursor contacts the MCP server defined in .mcp.json to fetch runtime artifacts and execute helper scripts.

Once configured, you can invoke skills directly from the Cursor command palette, such as "Run hugging-face-jobs → generate-responses.py". Cursor loads the skill's SKILL.md instructions and executes any associated helper scripts from the scripts/ directory.

Runtime Execution and Helper Scripts

Skills are instruction-based and do not ship compiled binaries. Execution is delegated to the host agent, which reads the SKILL.md file and invokes any referenced helper scripts.

For example, the hugging-face-jobs skill includes a helper script at skills/hugging-face-jobs/scripts/generate-responses.py. When the skill is invoked, the agent runs this script after checking the required environment variables documented in the skill's SKILL.md.

The repository includes scripts/publish.sh to regenerate all integration manifests. This script invokes scripts/generate_agents.py to update agents/AGENTS.md and the platform-specific JSON files, ensuring that skill names remain synchronized across all manifests.

Extending with Custom Skills

To add a new skill compatible with all platforms:

1. Copy an existing skill folder: cp -r skills/huggingface-gradio skills/my-new-skill
2. Edit skills/my-new-skill/SKILL.md and update the YAML front-matter name: my-new-skill
3. Add or modify helper assets in scripts/ or templates/ as needed
4. Run ./scripts/publish.sh to regenerate agents/AGENTS.md and update the platform manifests in .claude-plugin/, .cursor-plugin/, and the root gemini-extension.json
5. Commit the changes and push to trigger CI validation that ensures skill names match across all integration files

Summary

• The Hugging Face Skills repository uses platform-specific manifests—.claude-plugin/plugin.json, .cursor-plugin/plugin.json, gemini-extension.json, and agents/AGENTS.md—to register skills with Claude Code, Cursor, Gemini CLI, and OpenAI Codex.
• Each skill is a self-contained folder with a SKILL.md file containing YAML front-matter and detailed instructions, optionally accompanied by helper scripts in scripts/ or templates in templates/.
• Claude Code installs skills via its plugin marketplace using /plugin install, while OpenAI Codex discovers skills through the .agents/skills directory layout and the aggregated agents/AGENTS.md file.
• Gemini CLI loads the repository as an extension using gemini extensions install, and Cursor integrates via its plugin marketplace and an MCP server configured in .mcp.json.
• The scripts/publish.sh utility regenerates all integration manifests to keep skill names synchronized across platforms when adding or updating skills.

Frequently Asked Questions

How do I install a specific skill in Claude Code?

Register the Hugging Face Skills marketplace in Claude Code using /plugin marketplace add huggingface/skills, then install the individual skill with /plugin install <skill-name>@huggingface/skills. For example, /plugin install hugging-face-cli@huggingface/skills makes the CLI skill available for natural language invocation.

What is the difference between AGENTS.md and individual SKILL.md files?

The agents/AGENTS.md file aggregates the YAML front-matter from every SKILL.md into a single machine-readable list, serving as a discovery mechanism for agents like OpenAI Codex that scan the .agents/skills directory but may only read a single summary file. Individual SKILL.md files contain the full instructions, code snippets, and guardrails required for execution.

Can I use these skills without installing platform-specific plugins?

Yes. Because skills are instruction-based and reside in standard markdown files, you can manually copy any skill folder from the skills/ directory and reference the SKILL.md instructions directly in your prompts. However, installing the platform-specific plugins—via .claude-plugin/plugin.json, gemini-extension.json, or the Cursor marketplace—enables automatic discovery and structured invocation through the agents' native command interfaces.

How do I add a new skill that works across all four platforms?

Create a new folder under skills/ containing a SKILL.md with unique YAML front-matter (name, description, tags) and any helper scripts or templates. Run ./scripts/publish.sh to regenerate agents/AGENTS.md and update the platform manifests in .claude-plugin/, .cursor-plugin/, and gemini-extension.json. The CI pipeline validates that skill names match across all integration files before merging.

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