How to Write Skills for Claude Code, Codex, and Cursor: A Cross-Platform Guide

The Cross-Platform Skill Movement

Skills are the new unit of agent customization — and every major coding AI platform has converged on Markdown as the format of choice. The result is an unprecedented opportunity: write a skill once, adapt the wrapper, deploy everywhere.

In 2024 and 2025, coding agents moved from experimental tools to daily-driver infrastructure. Teams now rely on Claude Code for deep repository work, OpenAI Codex for quick transformations, Cursor for real-time editor integration, and Hermes for orchestration-heavy workflows. Each platform developed its own skill system, but — critically — each settled on plain Markdown files as the delivery format.

This convergence is not accidental. Markdown is human-readable, version-control-friendly, and composable. As our foundational guide to AI agent skills explains, skills are essentially structured prompts that attach behavioral context to an agent session. The cross-platform skill movement means that a well-crafted PR review skill, refactoring pattern, or testing protocol can serve your entire development toolchain.

The challenge is no longer "can this work on my agent?" but rather "how do I structure this skill so it translates cleanly across platforms?" That is exactly what this guide answers.

For teams coordinating multiple agents — as discussed in the multi-agent system design patterns guide — cross-platform skills become the shared vocabulary that keeps all agents aligned on conventions, standards, and workflows.

Platform-Specific Skill Formats

Each coding agent platform defines its own directory structure, file naming conventions, and metadata format for skills, but all ultimately parse Markdown instruction blocks.

Claude Code Skills (CLAUDE.md + .claude/skills/ directory structure)

Claude Code uses a CLAUDE.md file at your repository root as the project-level system prompt, with individual skills stored as Markdown files in the .claude/skills/ directory. Skills are loaded contextually when the agent detects relevance or when explicitly invoked with slash commands.

The Claude Code skill format is the closest to pure Markdown. A SKILL.md file contains a name, description, and instruction body with no mandatory frontmatter — making it the simplest format to author and port from.

---
name: pr-review
description: Review pull requests for code quality, security, and convention adherence.
---

# PR Review Skill

When reviewing a pull request, follow this protocol:

1. **Scope Check**: Read the PR description and linked issues first.
2. **Diff Analysis**: Review changed files in logical order (models → services → UI).
3. **Security Scan**: Flag any hardcoded secrets, SQL injection risks, or unsafe deserialization.
4. **Convention Check**: Verify naming follows project standards (camelCase for variables, PascalCase for types).
5. **Test Coverage**: Confirm new code paths have corresponding tests.
6. **Summary**: Output a structured review with severity levels (blocker/major/minor/suggestion).

If the PR touches more than 15 files, break the review into logical groups and summarize each group separately.

OpenAI Codex Skills (AGENTS.md + skills/ folder with SKILL.md files)

OpenAI Codex organizes project context through an AGENTS.md file at the project root, which references a skills/ directory containing individual SKILL.md files. The AGENTS.md acts as an orchestrator, listing available skills and their activation conditions.

Codex skills use a lightweight frontmatter that includes the skill name, trigger patterns, and priority. The body contains the same Markdown instruction format, making the content directly portable from Claude Code skills.

## Skills

### pr-review
- **Trigger**: When asked to review a PR or examine a pull request
- **Priority**: high
- **File**: skills/pr-review.md

---

# skills/pr-review.md

When reviewing a pull request, follow this protocol:

1. **Scope Check**: Read the PR description and linked issues first.
2. **Diff Analysis**: Review changed files in logical order (models → services → UI).
3. **Security Scan**: Flag hardcoded secrets, SQL injection risks, or unsafe deserialization.
4. **Convention Check**: Verify naming follows project standards.
5. **Test Coverage**: Confirm new code paths have corresponding tests.
6. **Summary**: Output structured review with severity levels.

Cursor Rules (.cursor/rules/*.mdc format)

Cursor implements skills as .mdc rule files stored in .cursor/rules/. These files use YAML-style frontmatter to define trigger scopes (glob patterns, file types, or always-on) followed by a Markdown instruction body.

The .mdc format is the most structured of the four platforms, requiring explicit scope definitions. However, the instruction content below the YAML fence is identical Markdown — you only need to adapt the trigger metadata.

---
description: PR review protocol for code quality and security
globs: ["**/pull-request*", "**/pr-*"]
alwaysApply: false
---

# PR Review Protocol

When reviewing a pull request, follow this protocol:

1. **Scope Check**: Read the PR description and linked issues first.
2. **Diff Analysis**: Review changed files in logical order (models → services → UI).
3. **Security Scan**: Flag hardcoded secrets, SQL injection risks, or unsafe deserialization.
4. **Convention Check**: Verify naming follows project standards.
5. **Test Coverage**: Confirm new code paths have corresponding tests.
6. **Summary**: Output structured review with severity levels (blocker/major/minor/suggestion).

If the PR touches more than 15 files, break the review into logical groups.

Hermes Agent Skills (SKILL.md with YAML frontmatter)

Hermes Agent skills live in the agent's skills directory as SKILL.md files with structured YAML frontmatter defining name, description, tags, and trigger phrases. The Hermes SkillForge tool generates these files with a browser-based editor and live preview.

Hermes skills support the richest metadata of any platform, including versioning, dependencies on other skills, and conditional activation. The Markdown body below the frontmatter is structurally identical to all other platforms.

---
name: pr-review
description: Comprehensive pull request review for code quality, security, and conventions.
tags: [code-review, security, pull-request]
triggers: ["review PR", "review pull request", "check this PR"]
version: 1.2.0
---

# PR Review Skill

When reviewing a pull request, follow this protocol:

1. **Scope Check**: Read the PR description and linked issues first.
2. **Diff Analysis**: Review changed files in logical order (models → services → UI).
3. **Security Scan**: Flag any hardcoded secrets, SQL injection risks, or unsafe deserialization.
4. **Convention Check**: Verify naming follows project standards (camelCase for variables, PascalCase for types).
5. **Test Coverage**: Confirm new code paths have corresponding tests.
6. **Summary**: Output a structured review with severity levels (blocker/major/minor/suggestion).

If the PR touches more than 15 files, break the review into logical groups and summarize each group separately.

Comparison Table

Writing a Universal Skill Structure

A universal skill structure separates platform-independent instruction content from platform-specific metadata wrappers, enabling single-source maintenance across all four agent platforms.

Core Principles That Work Everywhere

Regardless of target platform, effective cross-platform skills share five structural principles. First, single responsibility: each skill handles exactly one workflow or domain. A "PR review" skill reviews code — it does not also write tests or deploy. Second, numbered procedural steps: agents follow explicit sequences more reliably than free-form prose. Number your steps and make each one atomic.

Third, explicit output format: define what the agent should produce — a structured list, a severity-tagged review, a specific file format. Fourth, conditional branches: address edge cases with "If X, then Y" clauses rather than leaving them to the model's discretion. Fifth, context independence: the skill should carry enough information to work without external documentation or implicit project knowledge.

These principles align with what the research community has found about structured prompting: constraints and procedural framing dramatically improve instruction-following accuracy. As covered in our foundational guide to AI agent skills, the difference between a mediocre skill and an excellent one is usually structural discipline, not clever wording.

Handling Platform-Specific Differences

Platform-specific differences fall into three categories: trigger mechanism, metadata schema, and file location. The trigger mechanism — how a skill gets activated — varies most. Claude Code uses slash commands and auto-detection, Codex uses AGENTS.md trigger patterns, Cursor uses glob-based scope matching, and Hermes uses keyword triggers.

The practical approach is to maintain a "canonical" Markdown file for each skill containing the instruction body, then use thin wrapper files per platform that reference or embed this content. Tools like Hermes SkillForge automate this export process — you write the skill once and get four platform-ready files with correct frontmatter.

For monorepo setups where different teams use different agents, this canonical approach means one team's skill updates propagate to all platforms simultaneously. This is particularly valuable when implementing the collaborative patterns described in the multi-agent system design patterns guide, where multiple agents must share consistent behavioral expectations.

Step-by-Step: Creating a Cross-Platform Skill

Follow this eight-step workflow to create a skill that works on Claude Code, Codex, Cursor, and Hermes from a single source file.

1. 1. Define the skill's single purpose. Write a one-sentence scope statement. If it needs "and" to connect two responsibilities, split into separate skills.

2. 2. Draft the instruction body in plain Markdown. Use numbered steps, explicit conditions, and a defined output format. Do not reference platform-specific features yet.

3. 3. Define trigger conditions for each platform. For Claude Code, choose a slash command name. For Codex, write the AGENTS.md trigger phrase. For Cursor, determine the glob pattern. For Hermes, list natural-language trigger phrases.

4. 4. Add platform-specific frontmatter. Wrap the shared Markdown body in each platform's metadata format. Claude Code needs minimal YAML. Cursor needs globs and alwaysApply. Hermes needs tags, triggers, and version.

5. 5. Place files in correct directories. Deploy to .claude/skills/, skills/, .cursor/rules/, and ~/.hermes/skills/ respectively.

6. 6. Test activation on each platform. Verify the skill triggers correctly and produces expected output with a sample task. Document any platform-specific behavioral differences.

7. 7. Commit to version control. Store all skill files alongside your repository code. Use a .skills/ directory as a canonical source, with build scripts that copy to platform-specific locations.

8. 8. Export with SkillForge for multi-format generation. Use the Hermes SkillForge editor to generate all four platform formats from a single visual interface, with live preview and validation.

Three Real-World Example Skills

These three production-ready examples demonstrate the same skill adapted across platforms, showing the translation pattern and how much content stays identical versus what changes per platform.

Example 1: GitHub PR Review Skill

The PR review skill (shown in the format examples above) demonstrates the cleanest cross-platform translation: the instruction body is 100% identical across all four platforms. Only the wrapper changes — Claude Code needs a slash command, Codex needs a trigger pattern in AGENTS.md, Cursor needs a glob scope, and Hermes needs trigger keywords and tags.

This skill works exceptionally well across platforms because code review is a procedural task with clear sequential steps. The numbered protocol translates directly regardless of which LLM underlies the agent. Teams report 40-60% consistency improvement in review quality when this skill is deployed across their toolchain, compared to ad-hoc prompting.

Example 2: Code Refactoring Skill

A refactoring skill demonstrates how to handle platform-specific tool capabilities. Claude Code can execute shell commands, so the skill can include "run tests after refactoring" as a verification step. Cursor operates within the editor, so the refactoring skill emphasizes file-by-file transformation with preview diffs. The core refactoring logic — what patterns to apply and in what order — remains platform-agnostic.

# Code Refactoring Protocol

When asked to refactor code, apply transformations in this order:

1. **Extract Dead Code**: Remove unreachable branches and unused imports.
2. **Simplify Conditionals**: Replace nested if/else with early returns or guard clauses.
3. **Extract Duplications**: Identify repeated logic blocks (>3 occurrences) and extract to named functions.
4. **Improve Naming**: Rename variables/functions that violate project conventions.
5. **Reduce Coupling**: Break circular dependencies by introducing interfaces or event patterns.

For each transformation:
- Show the before/after for affected functions
- Explain the rationale in one sentence
- Flag any behavioral risks (e.g., "this changes error handling in edge case X")

Maximum scope: 5 transformations per refactoring session. If more are needed, prioritize by impact and schedule the rest for subsequent passes.

Example 3: Test Writing Skill

The test writing skill demonstrates conditional branching across platforms. On Claude Code and Hermes (which have terminal access), the skill includes "run the test suite to verify" as a final step. On Cursor, the skill focuses on generating test code that the developer runs manually. The test generation logic — identify boundaries, write happy-path, write edge cases, add regression coverage — is identical across platforms. Teams running multi-agent orchestrations benefit especially from shared testing skills, since multiple agents reviewing the same codebase should produce consistent test coverage.

This skill benefits most from the cross-platform approach because testing conventions are team-specific but must apply regardless of which agent team members use. When a senior engineer defines the testing skill for the Prescosoft team, every developer gets consistent test output whether they use Claude Code in the terminal or Cursor in their editor.

Key to this skill's portability is that it references the project's test framework (Jest, Pytest, etc.) in the instruction body rather than relying on platform-specific tool integrations. This keeps the skill content portable even as team tooling evolves.

FAQ