Skip to main content
Agent Skills is available on all Portkey plans. The sync CLI requires Node.js 18+.
Agent Skills are the standard for giving AI coding assistants domain-specific knowledge. A skill is a SKILL.md file that tells your agent how your team works — coding standards, review checklists, security patterns, API conventions. Portkey is a skills registry for your team. Create and version skills in Prompt Engineering Studio, sync them to any agent with one command. When you publish an update, every engineer gets it on their next sync.

​
How it works

Skills in Portkey are stored as versioned, team-shared assets. The sync CLI pulls them down and writes them to the correct directory for each agent automatically:
AgentSkills directory
Claude Code.claude/skills/
Cursor.cursor/skills/
Codex.codex/skills/
OpenCode.opencode/skills/
GitHub Copilot.github/skills/
No additional configuration needed — the agent discovers SKILL.md files and uses the description field to decide when to activate each skill.

​
Quick start

Using Claude Code? The Setup using CLI sets up gateway routing, MCP servers, and skills in one command:
npx github:portkey-ai/agent-cli

​
Step 1: Create a skill in Portkey

In Prompt Engineering Studio, create a new Partial. Skills are stored as Prompt Partials with a YAML frontmatter block:
Creating a skill partial in Portkey
---
name: code-reviewer
description: Expert code review assistant. Use when reviewing code, identifying bugs, or suggesting improvements.
---

# Code Review Expert

Your instructions here...
The name field becomes the directory name on disk (code-reviewer/SKILL.md). The description tells the agent when to activate the skill.

​
Step 2: Sync to your machine

PORTKEY_API_KEY=your-key npx github:Portkey-AI/agent-cli skills sync

Setup using CLI

One command setup — gateway routing, MCP, and skills

​
Authoring skills

​
The SKILL.md format

Every skill must start with YAML frontmatter containing name and description: 
---
name: your-skill-name
description: What this skill does and when the agent should use it. Be specific — the agent reads this to decide when to activate the skill.
---

# Skill Title

Your instructions here...
name — lowercase, hyphens only, max 64 characters. Becomes the directory name on disk. description — tells the agent when to activate this skill. Write it like a trigger condition: “Use when reviewing Python code, or when the user asks about code quality, performance, or testing.”

​
Versioning

Skills follow the same versioning workflow as all Portkey Prompt Partials:
  1. Edit — make changes in the partial editor
  2. Save — creates a new draft version (doesn’t affect what’s published)
  3. Publish — promotes a version to production; everyone who syncs next gets it
Skills listed as versioned prompt partials in Portkey Prompt Engineering Studio

​
Rolling back

If a new version causes issues:
  1. Open the skill in Portkey → Version History
  2. Select the previous version → Publish
  3. Team re-runs sync → rolled back immediately

​
Using skills in agents

After syncing, skills are written to the agent’s skills directory and discovered automatically at session start. Claude Code reads from .claude/skills/ — skills are available immediately in your next Claude Code session. Cursor reads from .cursor/skills/ — skills appear as active context in Cursor’s rule system. Codex reads from .codex/skills/ — skills are loaded when Codex starts a session in the project.

​
Next steps

Claude Code

Gateway routing, MCP, and skills for Claude Code

Cursor

Add skills to Cursor’s rule system

OpenAI Codex

Load skills into Codex sessions

All coding agents

Cline, Roo Code, Goose, opencode, and more
Last modified on April 7, 2026