From de600160a678d9f18b85ed0de98eb1dd8b35ab05 Mon Sep 17 00:00:00 2001 From: Khaliq Date: Tue, 24 Feb 2026 12:03:08 +0100 Subject: [PATCH 1/2] codex -> agent skills --- .agents/skills/creating-agent-skills/SKILL.md | 238 ++++++++++++++++++ packages/cli/src/commands/convert.ts | 10 +- packages/converters/docs/agent-skills.md | 14 +- packages/converters/src/format-registry.json | 4 +- packages/converters/src/from-codex.ts | 8 +- packages/converters/src/to-codex.ts | 14 +- packages/types/src/package.ts | 1 + .../app/blog/agent-skills-support/page.tsx | 4 +- prpm.json | 29 +++ 9 files changed, 299 insertions(+), 23 deletions(-) create mode 100644 .agents/skills/creating-agent-skills/SKILL.md diff --git a/.agents/skills/creating-agent-skills/SKILL.md b/.agents/skills/creating-agent-skills/SKILL.md new file mode 100644 index 00000000..063e89b8 --- /dev/null +++ b/.agents/skills/creating-agent-skills/SKILL.md @@ -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. diff --git a/packages/cli/src/commands/convert.ts b/packages/cli/src/commands/convert.ts index 6c2891c0..7abb3338 100644 --- a/packages/cli/src/commands/convert.ts +++ b/packages/cli/src/commands/convert.ts @@ -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 return join(process.cwd(), 'AGENTS.md'); @@ -217,7 +221,7 @@ 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')) { + if (filepath.includes('.agents/skills') || filepath.includes('.agents/agents')) { return 'codex'; } diff --git a/packages/converters/docs/agent-skills.md b/packages/converters/docs/agent-skills.md index ea88cd6b..79335393 100644 --- a/packages/converters/docs/agent-skills.md +++ b/packages/converters/docs/agent-skills.md @@ -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 @@ -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 @@ -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. @@ -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 diff --git a/packages/converters/src/format-registry.json b/packages/converters/src/format-registry.json index 3f354c3e..78f2f531 100644 --- a/packages/converters/src/format-registry.json +++ b/packages/converters/src/format-registry.json @@ -323,7 +323,7 @@ "fileExtension": ".md" }, "skill": { - "directory": ".codex/skills", + "directory": ".agents/skills", "filePatterns": ["SKILL.md"], "nested": true, "nestedIndicator": "SKILL.md", @@ -331,7 +331,7 @@ "fileExtension": ".md" }, "agent": { - "directory": ".openagents", + "directory": ".agents/agents", "filePatterns": ["AGENT.md"], "nested": true, "nestedIndicator": "AGENT.md", diff --git a/packages/converters/src/from-codex.ts b/packages/converters/src/from-codex.ts index cd9da150..c980ae2a 100644 --- a/packages/converters/src/from-codex.ts +++ b/packages/converters/src/from-codex.ts @@ -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 diff --git a/packages/converters/src/to-codex.ts b/packages/converters/src/to-codex.ts index 34556992..98c452c3 100644 --- a/packages/converters/src/to-codex.ts +++ b/packages/converters/src/to-codex.ts @@ -2,13 +2,16 @@ * Codex Format Converter * Converts canonical format to OpenAI Codex CLI format * - * Codex supports two output formats: - * 1. Native SKILL.md format for skills: - * - Directory: .codex/skills/{skill-name}/SKILL.md + * Codex supports native formats: + * 1. SKILL.md format for skills: + * - Directory: .agents/skills/{skill-name}/SKILL.md * - YAML frontmatter with name, description, optional metadata * - Based on Agent Skills standard (agentskills.io) * - * 2. AGENTS.md fallback for other subtypes (rules, slash-commands, agents): + * 2. AGENT.md format for agents: + * - Directory: .agents/agents/{agent-name}/AGENT.md + * + * 3. AGENTS.md fallback for other subtypes (rules, slash-commands): * - Progressive disclosure via named sections * - Users invoke by saying the command/skill name * @@ -571,7 +574,8 @@ function parseArgumentHint(hint: string | string[]): string[] { /** * Generate suggested filename for Codex * - * For skills: SKILL.md (inside .codex/skills/{name}/ directory) + * For skills: SKILL.md (inside .agents/skills/{name}/ directory) + * For agents: AGENT.md (inside .agents/agents/{name}/ directory) * For other subtypes: AGENTS.md */ export function generateFilename(pkg?: CanonicalPackage): string { diff --git a/packages/types/src/package.ts b/packages/types/src/package.ts index afecbd29..dbc80080 100644 --- a/packages/types/src/package.ts +++ b/packages/types/src/package.ts @@ -161,6 +161,7 @@ export const FORMAT_NATIVE_SUBTYPES: Partial> droid: ["skill", "slash-command", "hook"], // No native agent - uses AGENTS.md zed: ["rule", "slash-command", "extension"], // No native skill/agent - uses AGENTS.md amp: ["skill", "slash-command"], // Native skills (.agents/skills/) and commands (.agents/commands/) + codex: ["skill", "agent"], // Native skills (.agents/skills/) and agents (.agents/agents/) // Formats not listed use progressive disclosure for all skill/agent/command subtypes } as const; diff --git a/packages/webapp/src/app/blog/agent-skills-support/page.tsx b/packages/webapp/src/app/blog/agent-skills-support/page.tsx index 1b80ebbc..9b2c2c9b 100644 --- a/packages/webapp/src/app/blog/agent-skills-support/page.tsx +++ b/packages/webapp/src/app/blog/agent-skills-support/page.tsx @@ -147,7 +147,7 @@ This skill helps you write comprehensive API tests.
  • GitHub Copilot: .github/skills/<name>/SKILL.md (VS Code Insiders with chat.useAgentSkills enabled)
  • Claude Code: .claude/skills/<name>/SKILL.md
  • Factory Droid: .factory/skills/<name>/SKILL.md
    • -
  • OpenAI Codex CLI: .codex/skills/<name>/SKILL.md
    • +
  • OpenAI Codex CLI: .agents/skills/<name>/SKILL.md
  • VS Code: Native support in progress
    • @@ -381,7 +381,7 @@ prpm install @acme/api-testing --format copilot --subtype skill`} Codex CLI - .codex/skills/<name>/SKILL.md + .agents/skills/<name>/SKILL.md Subdirectory with SKILL.md diff --git a/prpm.json b/prpm.json index e609f4ef..b0e1db17 100644 --- a/prpm.json +++ b/prpm.json @@ -575,6 +575,35 @@ ".claude/skills/creating-agents-md/SKILL.md" ] }, + { + "name": "creating-agent-skills-skill", + "version": "1.0.0", + "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", + "format": "claude", + "subtype": "skill", + "tags": [ + "meta", + "agent-skills", + "codex", + "copilot", + "amp", + "agentskills-io", + "package-creation" + ], + "files": [ + ".agents/skills/creating-agent-skills/SKILL.md" + ], + "conversion": { + "cursor": { + "alwaysApply": false, + "globs": [ + "**/.agents/skills/**/SKILL.md", + "**/.github/skills/**/SKILL.md", + "**/.codex/skills/**/SKILL.md" + ] + } + } + }, { "name": "creating-kiro-agents-skill", "version": "1.0.0", From 4ad99ca51a71f24f338136d0c6a41201c41bdf56 Mon Sep 17 00:00:00 2001 From: Khaliq Date: Tue, 24 Feb 2026 12:16:23 +0100 Subject: [PATCH 2/2] pr feedback --- packages/cli/src/commands/convert.ts | 7 +++++-- packages/converters/src/from-codex.ts | 8 ++++++-- packages/converters/src/to-codex.ts | 3 +++ 3 files changed, 14 insertions(+), 4 deletions(-) diff --git a/packages/cli/src/commands/convert.ts b/packages/cli/src/commands/convert.ts index 7abb3338..a31d338b 100644 --- a/packages/cli/src/commands/convert.ts +++ b/packages/cli/src/commands/convert.ts @@ -221,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('.agents/skills') || filepath.includes('.agents/agents')) { - return 'codex'; + if (filepath.includes('.agents/skills')) { + return 'codex-skill'; + } + if (filepath.includes('.agents/agents')) { + return 'codex-agent'; } // Use robust content detection from converters diff --git a/packages/converters/src/from-codex.ts b/packages/converters/src/from-codex.ts index c980ae2a..68b0da0a 100644 --- a/packages/converters/src/from-codex.ts +++ b/packages/converters/src/from-codex.ts @@ -70,6 +70,9 @@ function parseFrontmatter(content: string): { frontmatter: Record; /** * 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 @@ -77,8 +80,9 @@ function parseAllowedTools(toolsString: string): string[] { .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 diff --git a/packages/converters/src/to-codex.ts b/packages/converters/src/to-codex.ts index 98c452c3..5ea2c5fd 100644 --- a/packages/converters/src/to-codex.ts +++ b/packages/converters/src/to-codex.ts @@ -582,6 +582,9 @@ export function generateFilename(pkg?: CanonicalPackage): string { if (pkg?.subtype === 'skill') { return 'SKILL.md'; } + if (pkg?.subtype === 'agent') { + return 'AGENT.md'; + } return 'AGENTS.md'; }