The Complete Guide to OpenAI Skills: Supercharge Your AI Coding Assistant with 38 Powerful Tools

In the era of AI-assisted development, developers are no longer satisfied with AI generating simple code snippets. We expect it to act like a senior engineer capable of executing complex tasks, from deploying applications to conducting security audits.

This guide provides an in-depth analysis of the OpenAI Skills repository, a powerful ecosystem containing 38 skills designed to extend the capabilities of Codex (OpenAI’s coding agent). We will explore how these skills work, how they are categorized, and how they can transform a generic AI assistant into a specialized “expert agent” equipped with domain-specific knowledge.

Image Source: Unsplash

What Are Agent Skills, and Why Are They the Next Milestone in AI Interaction?

Core Question: How do we move beyond simple “prompts” to enable AI to truly understand and execute complex task workflows?

Agent Skills are folders containing instructions, scripts, and resources that AI agents can discover and use to perform specific tasks. This is a “write once, use everywhere” paradigm.

Imagine traditional AI interaction is like giving verbal instructions to a smart intern. They might understand the general idea, but they don’t know your company’s specific standards or the intricate steps of a tedious task. Agent Skills, however, are like equipping that intern with a detailed “Standard Operating Procedure (SOP)” and a “specialized toolbox.”

The Anatomy of a Skill

Every skill follows a unified structure, allowing Codex to load and understand them efficiently:

  • SKILL.md: This is the required main file containing YAML frontmatter metadata (name, description) and Markdown instructions. It acts as the brain of the skill.
  • scripts/: Executable scripts, which can be in Python, Bash, or any other language. These are the hands of the skill.
  • references/: Reference documentation and materials. This serves as the skill’s knowledge base.
  • assets/: Files used in the output, such as templates or icons. These are the skill’s resource kit.

How Skills Are Understood and Executed

Skills utilize a system called “progressive disclosure” to efficiently manage the context window and prevent information overload:

  1. Metadata Layer: The skill’s name and description are always in the context (approx. 100 words), letting Codex know the skill exists and its basic purpose.
  2. Instruction Layer: The body of the SKILL.md is loaded only when the skill is triggered (usually under 5k words).
  3. Resource Layer: Scripts and other resources are called only when Codex actually needs to perform a specific operation.

“

Reflection & Insight:
The shift from prompt engineering to skill engineering is not just a formality; it’s a paradigm shift. In the past, we tried to describe every detail in natural language. Now, we can encapsulate code, documentation, and workflows within skills. This means AI capabilities are no longer limited solely by the model’s training data but can be infinitely expanded through community and enterprise accumulation.

The Landscape of 38 Skills: System, Curated, and Experimental

Core Question: How are these 38 skills organized, and where should I start?

The OpenAI Skills repository organizes skills into three primary folders, each representing a different level of maturity and use case.

Category Folder Quantity Characteristics
System Skills .system/ 2 Core functionality, auto-installed, manages the ecosystem
Curated Skills .curated/ 31 Production-ready skills verified for stability
Experimental Skills .experimental/ 5 Experimental features, exploring boundaries, use with caution

Below, we dive into these skills to see what problems they solve in real-world scenarios.

System Core Skills: The Foundation of Building and Management

Core Question: How can I create my own skills and easily manage them?

System skills are automatically installed in the latest version of Codex. They do not handle business logic directly but provide foundational support for the entire skill ecosystem.

1. skill-creator: Skill Creation Guide

Purpose: Provides a comprehensive framework for users to create or update skills.

Creating a skill isn’t just about writing documentation; it requires following the principle of “Simplicity is King.” This skill emphasizes that Codex is already highly intelligent; we only need to add the context it lacks.

Setting Degrees of Freedom:
The skill-creator provides a valuable framework for setting the strictness of instructions, which is crucial for ensuring the stability of AI execution:

  • High Freedom: Text-based instructions. Applicable when multiple methods are valid, like “write a technical blog.” This is like walking in an open field—many paths lead to the destination.
  • Medium Freedom: Pseudocode or parameterized scripts. Applicable when a preferred pattern exists but some variation is acceptable.
  • Low Freedom: Specific scripts with few parameters. Applicable when operations are fragile and error-prone, and consistency is critical. This is like walking on a tightrope—you must strictly follow the rails.

Use Case: If you need to encapsulate your company’s specific code review logic or create a standardized API documentation generation workflow for your team, this skill is your starting point.

2. skill-installer: Skill Installer

Purpose: Installs Codex skills from a curated list or a GitHub repo.

This is your entry point to extending Codex’s capabilities. With simple commands, you can bring community or open-source skills into your environment.

Installation Examples:

# Install a curated skill (by name)
$skill-installer gh-address-comments

# Install an experimental skill
$skill-installer install the create-plan skill from the .experimental folder

# Install from a GitHub URL
$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan

“

Note: After installing a skill, you must restart Codex to load the new skills.

Curated Skills: Development Tools Covering the Full Lifecycle

Core Question: Which ready-made skills can immediately improve my development, deployment, and design efficiency?

Curated skills are 31 skills that have been verified and are suitable for production use. We can categorize them by functional domain.

2.1 Development & Debugging: Closing the Loop from Code to Test

develop-web-game: Web Game Development

Purpose: Build and iterate on web games using a Playwright automated testing loop.

The biggest difficulty in game development is “invisible state.” This skill defines a strict automated testing loop:

  1. Implement small changes.
  2. Run the Playwright test script (simulating user input).
  3. Inspect screenshots and text state.
  4. Review console errors.
  5. Iterate adjustments.

Key Insight: To ensure test determinism, this skill strongly recommends implementing a window.advanceTime(ms) hook. This allows Playwright to reliably control frame advancement, avoiding test failures caused by timing discrepancies.

playwright: Browser Automation

Purpose: Automate real browser operations via the Playwright CLI.

Besides game development, this skill is equally powerful in general web automation. It provides a set of standard wrapper commands, allowing you to operate a browser like you operate a terminal.

Core Command Examples:

"$PWCLI" open https://example.com
"$PWCLI" snapshot
"$PWCLI" click e15
"$PWCLI" type "Playwright"
"$PWCLI" screenshot

gh-address-comments & gh-fix-ci: GitHub Workflows

These two skills target the GitHub collaboration process specifically.

  • gh-address-comments: Handles PR review comments. It checks comments, numbers and summarizes fixes, asks the user which to address, and applies them. This greatly simplifies the post-review cleanup.
  • gh-fix-ci: Fixes CI failures. It locates failing PR checks, fetches GitHub Actions logs, summarizes failure snippets, and proposes a fix plan.

Use Case: When you open GitHub and see red X marks, or receive a pile of review comments in a PR, these skills help you automatically organize your thoughts and execute fixes.

2.2 Deployment & Hosting: One-Click Cloud Deployment

This category includes multiple cloud platform deployment skills supporting rapid application push to production.

vercel-deploy: Vercel Deployment

Purpose: Instantly deploy apps to Vercel using an auth-less preview flow.

Its workflow is very streamlined:

  1. Packages the project into a .tar.gz (automatically excluding node_modules and .git).
  2. Auto-detects the framework from package.json.
  3. Uploads to the deployment service.
  4. Returns a Preview URL and a Claim URL.

This is very useful for quickly sharing prototypes or previews without complex configuration.

cloudflare-deploy: Cloudflare Deployment

Purpose: Deploy to the Cloudflare platform using Workers, Pages, and other services.

Cloudflare’s product line is very rich, and this skill provides a detailed decision tree to help developers choose the right product. It is not just a deployment tool but an architecture consultant.

  • Need to run code? It guides you to choose Workers (edge functions), Pages (full-stack apps), or Durable Objects (stateful coordination).
  • Need to store data? It recommends KV (key-value), D1 (SQLite), R2 (object storage), or Vectorize (vector database).
  • Need AI/ML? It points to Workers AI or Vectorize.

“

Reflection & Insight:
The evolution of deployment skills signals a lowering of the DevOps barrier. In the past, we needed to write complex YAML files or configure CI/CD pipelines. Now, through descriptive instructions and encapsulated scripts, AI can directly understand the intent of “I want to deploy this Node.js app to Cloudflare’s edge network” and automatically select the most appropriate compute resources (like Workers) and storage solutions (like D1).

2.3 Docs & Content: Breaking Format Barriers

Core Question: How can we get AI to accurately handle documents with complex layouts, rather than just extracting plain text?

doc: DOCX Document Processing

Purpose: Read, create, or edit .docx documents, with a focus on format and layout fidelity.

The biggest pain point in processing Word documents is formatting chaos. This skill sets strict quality expectations: avoiding clipped/overlapping text, and ensuring tables and charts are legible.

Workflow:

  1. Prioritize visual review (using soffice or pdftoppm to convert DOCX to PDF then to PNG).
  2. Use python-docx for editing.
  3. Re-render and check after every meaningful change.

pdf: PDF Processing

Purpose: Read, create, or review PDF files.

Recommended toolchain:

  • Generation: reportlab.
  • Extraction: pdfplumber or pypdf (text only).
  • Visual Check: pdftoppm (render to PNG).

jupyter-notebook & spreadsheet: Data & Experiments

These two skills target data science and analysis scenarios.

  • jupyter-notebook: Creates clean, reproducible notebooks, split into experimental exploration and tutorial modes.
  • spreadsheet: Processes Excel files using openpyxl and pandas, prioritizing native formats and charts.

2.4 Design & Visual: From Pixels to Code

Core Question: How can we achieve seamless connection between design and development, or even generate multimedia content?

figma & figma-implement-design: Figma Integration

This is the gold standard for design-to-code conversion.

  • figma: Fetches design context using the Figma MCP server.
  • figma-implement-design: Specifically for implementing code with 1:1 visual fidelity.

Required Workflow:

  1. Get design context (structured data).
  2. Get visual reference (screenshots).
  3. Download required assets (icons, fonts).
  4. Convert to project-convention code framework.
  5. Implement and verify against Figma.

Use Case: A designer provides a Figma link. Codex can automatically analyze the component structure, color variables, and generate corresponding React/Tailwind code, even handling responsive layouts.

imagegen, sora, speech, transcribe: Multimedia Generation & Processing

This set of skills demonstrates AI’s capabilities in the multimodal space.

  • imagegen: Generates or edits images via the OpenAI Image API. Supports concept art, background removal, etc. Defaults to the gpt-image-1.5 model.
  • sora: Video generation. It includes a decision tree: if you have a video ID and need changes -> “remix”; if you need multiple prompts -> “batch create”.
  • speech: Text-to-speech. Default model gpt-4o-mini-tts-2025-12-15, supports batch generation.
  • transcribe: Audio transcription. Supports speaker separation using the gpt-4o-transcribe-diarize model to distinguish different speakers.

2.5 Project Management: Connecting Development to Business

Core Question: How can we automatically associate code changes with project and task management systems?

linear: Linear Issue Management

Purpose: Manage issues, projects, and team workflows in Linear.

It provides a complete set of tools to operate the Linear API: list_issues, create_issue, update_issue, and more.

Practical Workflow Examples:

  • Sprint Planning: Review open issues, pick top priorities, and create a new Cycle.
  • Bug Triage: List critical bugs, rank by user impact, and move to “In Progress.”
  • Release Planning: Create a project with milestones and generate issues with estimates.

notion-knowledge-capture: Notion Knowledge Capture

Purpose: Capture conversations and decisions into structured Notion pages.

This solves the “discuss and forget” problem. The workflow includes: clarifying content (decisions, FAQs) -> identifying database templates -> extracting context -> creating drafts and linking.

Additionally, there are specialized skills for meeting prep (notion-meeting-intelligence), research docs (notion-research-documentation), and spec implementation (notion-spec-to-implementation).

2.6 Security: Integrating Security into the Development Flow

Core Question: How can we automate security audits and threat modeling without sacrificing development speed?

security-best-practices: Security Best Practices

Purpose: Perform language and framework-specific security best practice reviews.

It has three modes of operation:

  1. Primary Mode: Write secure-by-default code from this point forward.
  2. Secondary Mode: Passively detect vulnerabilities while writing code.
  3. Report Mode: Generate a comprehensive security report.

security-threat-model: Security Threat Modeling

Purpose: Repository-based threat modeling, enumerating trust boundaries, assets, attacker capabilities, etc.

This is a highly advanced skill featuring an 8-step rigorous workflow:

  1. Scope and extract the system model.
  2. Derive boundaries, assets, and entry points.
  3. Calibrate assets and attacker capabilities.
  4. Enumerate threats as abuse paths.
  5. Prioritize using explicit likelihood and impact reasoning.
  6. Validate service context and assumptions with the user.
  7. Recommend mitigations.
  8. Run a quality check.

Use Case: When developing a new payment interface or user authentication system, using this skill can automatically generate a threat modeling document, helping the team identify potential risks before coding.

“

Reflection & Insight:
The introduction of security skills is a significant step towards automating DevSecOps. Typically, threat modeling and security auditing are time-consuming and require expert knowledge. By encoding expert security knowledge into Skills, ordinary development teams can get real-time security guidance during the coding phase, which is far more effective than post-hoc audits.

Experimental Skills: Exploring Future Workflows

Core Question: Which cutting-edge features are being tested, and how will they change our way of working?

Experimental skills contain 5 functions, representing OpenAI’s thoughts on the future of AI workflows.

3.1 create-plan: Create Plan

Purpose: Create a concise plan when the user explicitly asks for a plan related to a coding task.

This is a very practical skill, especially before starting complex projects. It enforces the following process:

  1. Quickly scan context (README, docs).
  2. Ask follow-up questions only if blocking (at most 1-2).
  3. Create a plan using a template (containing description, scope, action item checklist, open questions).
  4. Output no meta-commentary, only the plan.

This “just do it” style fits the needs of efficient development perfectly.

3.2 wrapped: Codex Wrapped Usage Review

Purpose: Generate a usage review report from local Codex logs.

Like Spotify’s annual review, it can stats for the past 30 days, 7 days, and total focus hours. This is very helpful for individual developers to understand their AI-assisted programming habits.

3.3 GitLab & Test Related Skills

  • gitlab-address-comments: Counterpart to the GitHub version, handles GitLab MR comments.
  • codex-readiness-unit-test & codex-readiness-integration-test: Multi-stage tests for verifying agent execution quality.

Skill Installation and Practical Guide

Core Question: How can I install and start using these skills in my own environment?

Installing Curated Skills

If you want to use a feature in Codex, you can invoke the installer directly. For example, if you want to handle GitHub PR comments:

$skill-installer gh-address-comments

Installing Experimental Skills

Experimental skills require specifying the source explicitly. For example, to install the create-plan skill:

$skill-installer install the create-plan skill from the .experimental folder

Or directly via a GitHub URL:

$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan

Key Step: Restart

Remember: You must restart Codex after installing a skill for the new skills to load. This step is often forgotten, causing skills to appear unavailable.

Conclusion and Actionable Checklist

OpenAI Skills is not just a collection of scripts; it is a system for “solidifying” human expertise and workflows into AI agents. Through the combination of system skills, curated skills, and experimental skills, we can build a fully automated loop covering requirements analysis, coding, testing, deployment, and maintenance.

Practical Summary / Actionable Checklist

  1. Understand the Structure: Remember that a Skill = Instructions + Scripts + Resources.
  2. Install the Tool: Ensure skill-installer is available in your Codex environment.
  3. Try Deployment: Use vercel-deploy or netlify-deploy to quickly deploy a demo.
  4. Optimize Design Flow: Configure the figma MCP and try using figma-implement-design to restore a component.
  5. Strengthen Security: Run security-threat-model on your next sensitive project for risk assessment.
  6. Plan First: Use create-plan to generate an action list before starting large tasks.

One-Page Summary

Skill Category Representative Skills Core Value
System skill-creator Empowers users to customize workflows
Development develop-web-game, playwright Automated testing and browser control
Deployment cloudflare-deploy, vercel-deploy Zero-config or multi-product decision-support cloud deployment
Documentation doc, pdf Document processing that preserves formatting
Design figma-implement-design, imagegen Pixel-perfect restoration and multimedia generation
Management linear, notion-knowledge-capture Bridge connecting code and project management
Security security-threat-model Shift-left security auditing and threat modeling
Experimental create-plan, wrapped Task planning and usage data analytics

Frequently Asked Questions (FAQ)

  1. Q: What should I do if I can’t find a skill after installation?
    A: Please check if you have restarted Codex. Skill loading usually requires a restart to take effect.

  2. Q: Can I modify installed skills?
    A: Yes. Skills are essentially files in folders; you can directly modify the SKILL.md or scripts in scripts/ to customize behavior.

  3. Q: Are experimental skills stable?
    A: Experimental skills (.experimental) are still in development or testing and may change. It is recommended to use them with caution in non-critical tasks.

  4. Q: Do skills support private repositories?
    A: skill-installer supports installing skills from public or private GitHub repositories, provided Codex has the appropriate access permissions.

  5. Q: How do I create my own skill?
    A: Use the built-in skill-creator skill. It provides best practices, templates, and validation tools to guide you in creating compliant skills.

  6. Q: Will skills consume extra Tokens?
    A: Yes. According to the progressive disclosure principle, the skill’s instructions and loaded resources will consume the context window when invoked.

  7. Q: Can multiple skills be active in a project simultaneously?
    A: Yes. Codex will automatically discover and invoke relevant skills based on the current task’s context.

  8. Q: Are skills only applicable to OpenAI’s Codex?
    A: While this repository is designed for Codex, its “instruction + script” architecture concept can be borrowed or adapted by other AI agent frameworks, but compatibility is currently primarily targeted at Codex.