Skip to content

codex -> agent skills #257

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
khaliqgant merged 2 commits into from
Feb 24, 2026
Merged

codex -> agent skills #257

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
de60016
codex -> agent skills
khaliqgant Feb 24, 2026
4ad99ca
pr feedback
khaliqgant Feb 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
238 changes: 238 additions & 0 deletions .agents/skills/creating-agent-skills/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,238 @@
---
name: creating-agent-skills
description: Use when creating Agent Skills packages (SKILL.md format) for Codex CLI, GitHub Copilot, or Amp - provides the agentskills.io specification with frontmatter constraints, directory structure, and validation rules
---

# Creating Agent Skills

## Overview

Agent Skills is an open standard for portable AI agent capabilities. One SKILL.md file works across Codex CLI, GitHub Copilot, and Amp.

**Official Spec:** https://agentskills.io/specification

## Installation Directories

| Tool | Location |
|------|----------|
| **Codex CLI** | `.agents/skills/{skill-name}/SKILL.md` |
| **GitHub Copilot** | `.github/skills/{skill-name}/SKILL.md` |
| **Amp** | `.agents/skills/{skill-name}/SKILL.md` |

## Directory Structure

```
my-skill/ # Must match frontmatter `name`
├── SKILL.md # Required - main definition
├── scripts/ # Optional - executable code
├── references/ # Optional - additional docs
└── assets/ # Optional - static resources
```

## Frontmatter Specification

### Required Fields

```yaml
---
name: skill-name
description: What it does and when to use it
---
```

| Field | Constraints |
|-------|-------------|
| `name` | 1-64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens, must match parent directory |
| `description` | 1-1024 chars, explains functionality AND use cases |

### Optional Fields

```yaml
---
name: pdf-processing
description: Extracts and processes PDF content. Use for document analysis and text extraction.
license: MIT
compatibility: Requires pdftotext, poppler-utils
allowed-tools: Bash(pdftotext:*) Read Write
metadata:
category: document-processing
version: 1.0.0
---
```

| Field | Constraints |
|-------|-------------|
| `license` | Short reference (e.g., `MIT`, `Apache-2.0`) |
| `compatibility` | 1-500 chars, environment requirements |
| `allowed-tools` | Space-delimited pre-approved tools (experimental) |
| `metadata` | Arbitrary string key-value pairs |

## Name Validation

```
✅ Valid: pdf-processing, code-review, data-analysis
❌ Invalid: PDF-Processing (uppercase), -pdf (leading hyphen), pdf--processing (consecutive hyphens)
```

**Pattern:** `^[a-z0-9]+(-[a-z0-9]+)*$`

## Description Best Practices

```yaml
# ❌ BAD - Too vague
description: Helps with PDFs

# ❌ BAD - Missing use cases
description: Extracts text from PDFs

# ✅ GOOD - Functionality + use cases
description: Extracts and processes PDF content. Use for document analysis, text extraction, and form data parsing.
```

**Include:**
- What the skill does
- When to activate it (keywords agents search for)
- Specific use cases

## Body Content

Markdown instructions after frontmatter. No format restrictions, but recommended sections:

```markdown
---
name: code-review
description: Reviews code for best practices and security issues. Use when analyzing PRs or conducting audits.
---

## Overview
Brief description of capabilities.

## Process
1. Step-by-step workflow
2. With clear actions

## Guidelines
- Bullet points for rules
- Best practices

## Examples
Code samples showing usage.
```

## Progressive Disclosure

Skills use tiered loading to optimize context:

1. **Metadata** (~100 tokens): `name` + `description` load at startup
2. **Activation** (<5000 tokens): Full `SKILL.md` loads when selected
3. **On-demand**: Supporting files load when referenced

**Keep `SKILL.md` under 500 lines** for efficient context usage.

## Supporting Files

### scripts/
Executable code agents can invoke:
```python
#!/usr/bin/env python3
# scripts/extract.py
import sys
# Self-contained with clear dependencies
```

### references/
Additional documentation:
- `REFERENCE.md` - Technical details
- `FORMS.md` - Templates
- Domain-specific files

### assets/
Static resources: templates, diagrams, lookup tables.

**Reference with relative paths:** `scripts/extract.py`, `references/REFERENCE.md`

## Complete Example

```markdown
---
name: typescript-expert
description: Expert TypeScript assistance with strict typing and modern patterns. Use for TypeScript projects requiring type safety, generics, or advanced type manipulation.
license: MIT
compatibility: Requires Node.js 18+, TypeScript 5+
---

You are an expert TypeScript developer.

## Guidelines

- Always use strict type checking
- Prefer `unknown` over `any`
- Use type guards for runtime checking
- Leverage template literal types

## Best Practices

- Export types from dedicated `.types.ts` files
- Use `readonly` for immutable data
- Prefer interfaces for objects, types for unions

## Examples

### Type Guard

```typescript
function isUser(obj: unknown): obj is User {
return (
typeof obj === 'object' &&
obj !== null &&
'id' in obj &&
'name' in obj
);
}
```
```

## Validation

Use the validation tool:
```bash
skills-ref validate ./my-skill
```

Checks:
- YAML frontmatter validity
- Name format compliance
- Required fields presence
- Directory name matches `name` field

## Quick Checklist

**Frontmatter:**
- [ ] `name` is 1-64 chars, lowercase alphanumeric + hyphens
- [ ] `name` matches parent directory name
- [ ] `description` is 1-1024 chars
- [ ] `description` includes functionality AND use cases

**Content:**
- [ ] Under 500 lines for efficient loading
- [ ] Clear instructions agents can follow
- [ ] Examples for complex operations

**Structure:**
- [ ] Directory named exactly as `name` field
- [ ] `SKILL.md` at directory root
- [ ] Supporting files in appropriate subdirectories

## Cross-Tool Compatibility

The SKILL.md format is identical across implementations. To port:

```bash
# Codex → Copilot
mv .agents/skills/my-skill .github/skills/my-skill

# Copilot → Codex/Amp
mv .github/skills/my-skill .agents/skills/my-skill
```

No content changes required.
15 changes: 11 additions & 4 deletions packages/cli/src/commands/convert.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,9 +163,13 @@ function getDefaultPath(format: string, filename: string, subtype?: string, cust
case 'droid':
return join(process.cwd(), '.factory', `${baseName}.md`);
case 'codex':
// Codex skills go to .codex/skills/{name}/SKILL.md
// Codex skills go to .agents/skills/{name}/SKILL.md
if (subtype === 'skill') {
return join(process.cwd(), '.codex', 'skills', baseName, 'SKILL.md');
return join(process.cwd(), '.agents', 'skills', baseName, 'SKILL.md');
}
// Codex agents go to .agents/agents/{name}/AGENT.md
if (subtype === 'agent') {
return join(process.cwd(), '.agents', 'agents', baseName, 'AGENT.md');
}
// Other subtypes use AGENTS.md
Copy link
Copy Markdown

@codeant-ai codeant-ai Bot Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: Codex slash commands currently fall through to the generic AGENTS.md path, but the Agent Skills/Codex docs specify that progressive-disclosure slash commands should live at .opencommands/{name}.md. This mislocation means converted Codex slash commands won't be written where the editor expects them, so they may not be discovered or invoked correctly as slash commands. Add a dedicated slash-command branch in the Codex getDefaultPath case to target .opencommands/{name}.md. [logic error]

Severity Level: Major ⚠️ 
- ⚠️ `prpm convert --to codex --subtype slash-command` writes AGENTS.md.
- ⚠️ Converted Codex slash-commands diverge from `.opencommands/` install layout.
Suggested change
// Other subtypes use AGENTS.md
// Codex slash commands use .opencommands/{name}.md for progressive disclosure
if (subtype === 'slash-command') {
return join(process.cwd(), '.opencommands', `${baseName}.md`);
}
Steps of Reproduction ✅ 
1. Run the CLI convert command created by `createConvertCommand()` at
`packages/cli/src/commands/convert.ts:534-585`, e.g.:

   `prpm convert my-command.md --to codex --subtype slash-command` in a project directory
   with no `--output` flag.

2. The `.action` handler in `createConvertCommand()` calls `handleConvert()` at
`convert.ts:569-576`, passing `options.to === 'codex'` and `options.subtype ===
'slash-command'`.

3. Inside `handleConvert()` at `convert.ts:485-487`, the code computes the output path as:

   `const outputPath = options.output || getDefaultPath(options.to, sourcePath,
   options.subtype, options.name);`

   so it calls `getDefaultPath('codex', sourcePath, 'slash-command', options.name)`.

4. In `getDefaultPath()` at `convert.ts:90-178`, the `case 'codex'` branch at `165-175`
executes. Because `subtype` is `'slash-command'`, neither the `skill` check at `167-168`
nor the `agent` check at `171-172` matches, so execution falls through to the default
branch at `174-175` and returns `<cwd>/AGENTS.md`. This is inconsistent with:

   - The Codex progressive disclosure spec in
   `packages/converters/docs/agent-skills.md:218-223`, which specifies
   `.opencommands/{name}.md` for Codex slash commands; and

   - The install flow in `packages/cli/src/commands/install.ts:1097-1111` and the
   progressive-disclosure logic at `install.ts:1475-1481`, where manifest formats
   including `'codex'` install slash commands to `.opencommands/{packageName}.md`.

   As a result, Codex slash commands produced via `prpm convert --to codex --subtype
   slash-command` are written to `AGENTS.md` instead of the `.opencommands/{name}.md`
   location used by `prpm install` and described in the docs.
Prompt for AI Agent 🤖 
This is a comment left during a code review.

**Path:** packages/cli/src/commands/convert.ts
**Line:** 174:174
**Comment:**
	*Logic Error: Codex slash commands currently fall through to the generic AGENTS.md path, but the Agent Skills/Codex docs specify that progressive-disclosure slash commands should live at `.opencommands/{name}.md`. This mislocation means converted Codex slash commands won't be written where the editor expects them, so they may not be discovered or invoked correctly as slash commands. Add a dedicated `slash-command` branch in the Codex `getDefaultPath` case to target `.opencommands/{name}.md`.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
👍 | 👎

return join(process.cwd(), 'AGENTS.md');
Expand Down Expand Up @@ -217,8 +221,11 @@ function detectFormat(content: string, filepath: string): string | null {
if (filepath.includes('.zed/extensions') || filepath.includes('.zed/slash_commands')) {
return 'zed';
}
if (filepath.includes('.codex/skills')) {
return 'codex';
if (filepath.includes('.agents/skills')) {
return 'codex-skill';
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot Feb 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: detectFormat now returns "codex-skill"/"codex-agent", but handleConvert only supports "codex". This makes .agents/skills or .agents/agents files fail conversion with "Unsupported source format". Add cases for the new formats or map them back to "codex" before the switch.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At packages/cli/src/commands/convert.ts, line 225:

<comment>detectFormat now returns "codex-skill"/"codex-agent", but handleConvert only supports "codex". This makes .agents/skills or .agents/agents files fail conversion with "Unsupported source format". Add cases for the new formats or map them back to "codex" before the switch.</comment>

<file context>
@@ -221,8 +221,11 @@ function detectFormat(content: string, filepath: string): string | null {
-  if (filepath.includes('.agents/skills') || filepath.includes('.agents/agents')) {
-    return 'codex';
+  if (filepath.includes('.agents/skills')) {
+    return 'codex-skill';
+  }
+  if (filepath.includes('.agents/agents')) {
</file context>
Fix with Cubic

}
if (filepath.includes('.agents/agents')) {
return 'codex-agent';
}

// Use robust content detection from converters
Expand Down
14 changes: 7 additions & 7 deletions packages/converters/docs/agent-skills.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@

| Tool | File Location | Documentation |
|------|--------------|---------------|
| **OpenAI Codex** | `.codex/skills/{skill-name}/SKILL.md` | [Codex Skills](https://developers.openai.com/codex/skills) |
| **OpenAI Codex** | `.agents/skills/{skill-name}/SKILL.md` | [Codex Skills](https://developers.openai.com/codex/skills) |
| **GitHub Copilot** | `.github/skills/{skill-name}/SKILL.md` | [Copilot Skills](https://code.visualstudio.com/docs/copilot/customization/agent-skills) |

## Overview
Expand All @@ -17,9 +17,9 @@ Agent Skills is an open standard for giving AI agents new capabilities and exper
### Codex Discovery Locations

OpenAI Codex CLI discovers skills from these locations (in order of precedence):
1. **REPO**: `$CWD/.codex/skills` - Project-specific skills
2. **REPO**: `$CWD/../.codex/skills` - Parent folder organization skills
3. **REPO**: `$REPO_ROOT/.codex/skills` - Repository-wide skills
1. **REPO**: `$CWD/.agents/skills` - Project-specific skills
2. **REPO**: `$CWD/../.agents/skills` - Parent folder organization skills
3. **REPO**: `$REPO_ROOT/.agents/skills` - Repository-wide skills
4. **USER**: `$CODEX_HOME/skills` - User-personal skills
5. **ADMIN**: `/etc/codex/skills` - System-level defaults
6. **SYSTEM**: Bundled - Built-in skills
Expand Down Expand Up @@ -210,8 +210,8 @@ The converter generates SKILL.md with:
### Cross-Format Conversion

Skills authored for one tool can be converted for another:
- Codex skill → Copilot skill: Change directory from `.codex/skills/` to `.github/skills/`
- Copilot skill → Codex skill: Change directory from `.github/skills/` to `.codex/skills/`
- Codex skill → Copilot skill: Change directory from `.agents/skills/` to `.github/skills/`
- Copilot skill → Codex skill: Change directory from `.github/skills/` to `.agents/skills/`

The content format is identical between implementations.

Expand All @@ -220,7 +220,7 @@ The content format is identical between implementations.
For Codex subtypes not natively supported as skills:
- **Rules**: Use `AGENTS.md` in project root
- **Slash commands**: Use `.opencommands/{name}.md`
- **Agents**: Use `.openagents/{name}/AGENT.md`
- **Agents**: Use `.agents/agents/{name}/AGENT.md`

## Related Documentation

Expand Down
4 changes: 2 additions & 2 deletions packages/converters/src/format-registry.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -323,15 +323,15 @@
"fileExtension": ".md"
},
"skill": {
"directory": ".codex/skills",
"directory": ".agents/skills",
"filePatterns": ["SKILL.md"],
"nested": true,
"nestedIndicator": "SKILL.md",
"usesPackageSubdirectory": true,
"fileExtension": ".md"
},
"agent": {
"directory": ".openagents",
"directory": ".agents/agents",
"filePatterns": ["AGENT.md"],
"nested": true,
"nestedIndicator": "AGENT.md",
Expand Down
16 changes: 10 additions & 6 deletions packages/converters/src/from-codex.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@
* Based on the Agent Skills specification at agentskills.io
*
* Directory structure:
* - .codex/skills/{skill-name}/SKILL.md (required)
* - .codex/skills/{skill-name}/scripts/ (optional)
* - .codex/skills/{skill-name}/references/ (optional)
* - .codex/skills/{skill-name}/assets/ (optional)
* - .agents/skills/{skill-name}/SKILL.md (required)
* - .agents/skills/{skill-name}/scripts/ (optional)
* - .agents/skills/{skill-name}/references/ (optional)
* - .agents/skills/{skill-name}/assets/ (optional)
*
* @see https://agentskills.io/specification
* @see https://developers.openai.com/codex/skills
Expand Down Expand Up @@ -70,15 +70,19 @@ function parseFrontmatter(content: string): { frontmatter: Record<string, any>;
/**
* Parse allowed-tools string into array of tool names
* Format: "Bash(git:*) Bash(jq:*) Read Write"
*
* Tool names may contain letters, digits, hyphens, underscores, and dots.
* Patterns like "Bash(git:*)" extract the base tool name "Bash".
*/
function parseAllowedTools(toolsString: string): string[] {
// Split by whitespace and extract tool names
return toolsString
.split(/\s+/)
.filter(Boolean)
.map(tool => {
// Extract base tool name from patterns like "Bash(git:*)"
const match = tool.match(/^([A-Za-z]+)(?:\([^)]*\))?$/);
// Extract base tool name from patterns like "Bash(git:*)" or "MCP_tool(pattern)"
// Tool names can contain: letters, digits, hyphens, underscores, dots
const match = tool.match(/^([A-Za-z0-9_.-]+)(?:\([^)]*\))?$/);
return match ? match[1] : tool;
})
// Deduplicate tool names
Expand Down
Loading
Loading