# Codex Skills for Beginners: Automating AI Agent Workflows > A comprehensive hands-on guide to building and executing Codex Skills: SKILL.md anatomy, explicit vs. auto-triggering, skills vs. scripts vs. tools, Skills API, and safety boundaries. ## 1. What Is a Codex Skill: Moving from Ad-Hoc Prompts to Repeatable Workflows During regular development with **Codex**, engineers repeatedly type the same initial instructions: which files to check, what code quality criteria to apply, which architecture rules to enforce, and how to format the output. Having to reiterate these constraints across every new session slows down development velocity and introduces accidental variability. A **Codex Skill** is a saved, reusable operational workflow designed for a specific class of tasks. Creating a skill is not model fine-tuning: the underlying neural weights of the AI remain completely untouched. Instead, the agent is provided with a structured procedural protocol that it dynamically loads into its context window only when the corresponding task arises. ```mermaid flowchart LR subgraph AdHoc ["Traditional Approach (Manual Prompting)"] User1["User"] -->|Enters repetitive instructions every time| Prompt["Large Ad-Hoc Prompt"] Prompt --> Agent1["Codex"] end subgraph Modular ["Skills-Based Architecture"] User2["User"] -->|Concise Command: $code-review| Agent2["Codex"] SkillsDir["Skills Repository (SKILL.md)"] -->|Dynamic Instruction Ingestion| Agent2 Agent2 --> Output["Standardized Output"] end ``` > [!NOTE] > In OpenAI's ecosystem, skills are already treated as the standard for developer automation. For example, when upgrading a codebase to modern model families, OpenAI provides the `openai-docs` skill, which encapsulates up-to-date SDK knowledge without requiring the engineer to paste manual documentation snippets. --- ## 2. Decision Criteria: When to Build a Skill vs. Write a Prompt Skills are specifically designed for workflows that exhibit clear repeatability, a deterministic sequence of steps, or strict output formatting requirements. | Evaluation Criterion | Standard Ad-Hoc Prompt | Codex Skill | | :--- | :--- | :--- | | **Frequency of Execution** | One-off exploratory task | Recurring scenario (daily, per pull request, or pre-release) | | **Workflow Complexity** | 1–2 simple sequential instructions | Multi-step regulated pipeline with validation gates | | **Supplementary Assets** | None needed | Requires helper scripts, styleguides, or checklists | | **Output Constraints** | Arbitrary text or code generation | Strict report schema (markdown table, JSON structure) | | **Permissions and Safety** | Session defaults | Explicitly codified permissions (read-only vs. write) | ### Prime Candidates for Skill Packaging - **Pre-Release Codebase Audit:** Running linters, detecting stray debugging artifacts (`console.log`, `TODO`), validating TypeScript types. - **Standardized Code Review:** Verifying code against internal engineering conventions without applying unvetted mutations. - **Release Notes Compilation:** Parsing merged pull requests, grouping changes into semantic categories, and updating `CHANGELOG.md`. - **Component Modernization:** Step-by-step refactoring of legacy component patterns using approved migration templates. > [!TIP] > **The Rule of Three for Developers:** If you find yourself explaining the exact same sequence of instructions to Codex for the third time ("read this file first, run this test suite, do not change code, output findings as a table"), it is time to convert that procedure into a Skill. --- ## 3. Activation Mechanics: Explicit $name Invocation vs. Semantic Auto-Matching Codex supports two complementary activation modes: direct deterministic execution by the user and autonomous semantic recognition by the agent. ### Explicit Invocation The user directly references the skill by prepending a dollar sign `$` to its name: ```bash $code-review inspect recent changes on feature/auth ``` This execution mode provides 100% deterministic predictability: Codex immediately activates the specified skill, adopts its instructions as the primary operational protocol, and binds them to the user's arguments. ### Semantic Auto-Matching If no `$name` prefix is specified, Codex parses the prompt and semantically matches it against the `description` fields of all available skills: ```mermaid flowchart TD Req["User Prompt: 'Prepare release notes for v2.1.0'"] --> Router{"Semantic Intent Router"} Router -->|Match: description release-notes| LoadSkill["Ingest .codex/skills/release-notes/SKILL.md"] Router -->|No Match| Standard["Standard chat turn without skill overhead"] LoadSkill --> Exec["Execute Standardized Pipeline"] ``` ```text High-Precision Description (High Semantic Accuracy): description: Audits modified repository files for regressions, type errors, and style violations prior to release. Use during PR reviews. Vague Description (Poor Match Signal): description: Helps developers write better software. ``` --- ## 4. Skill Anatomy and SKILL.md Structure: Metadata, Instructions, and Assets A minimal skill consists of a single file: `SKILL.md`. More mature skills can bundle executable scripts, reference guides, and output templates within their folder structure. ```text project-review/ ├── SKILL.md # Core file (metadata + instructions) ├── scripts/ └── check-deps.sh # Helper script for deterministic checks ├── references/ └── styleguide.md # Reference guide: team code conventions └── templates/ └── report-template.md # Template for final audit reports ``` ### Anatomy of `SKILL.md` The file is partitioned into two functional sections: a YAML Frontmatter metadata header followed by standard Markdown instructions. ```markdown --- name: project-review description: Conducts comprehensive pre-release code audits, verifies type safety, and outputs structured issue reports without mutating code. --- Audit Instructions: 1. Execute "npm run typecheck" to identify TypeScript compile errors. 2. Inspect the git diff relative to the main branch. 3. Categorize findings into three tiers: Critical, Warning, Suggestion. 4. Do NOT modify any source files autonomously. 5. Format the final summary conforming to templates/report-template.md. ``` > [!IMPORTANT] > **The Principle of Conciseness:** Do not bloat `SKILL.md` with long philosophical explanations. The more succinct and actionable the text, the less context window space it occupies, and the more reliably the agent adheres to instructions. --- ## 5. Storage Scopes: Project-Level vs. Personal Global Skills Codex categorizes skills into two distinct storage scopes based on their intended audience: ```mermaid flowchart TD subgraph GlobalScope ["Personal Global Skills (~/.codex/skills/)"] G1["Personal commit message formatter"] G2["License header generator"] end subgraph ProjectScope ["Project-Level Skills (.codex/skills/)"] P1["Repository architecture auditor"] P2["Prisma migration and DTO builder"] P3["Production release checklist"] end Dev["Developer"] -->|Personal ergonomics| GlobalScope Team["Team via Git"] -->|Shared engineering standards| ProjectScope ``` ### Project-Level Skills (`.codex/skills/` or `.agents/skills/`) Located at the root of the project repository and tracked in Git. - **Purpose:** Standardizing workflows across the entire engineering team. - **Advantage:** Any developer or CI/CD runner checking out the repository immediately inherits the same set of agent skills. ### Personal Global Skills (`~/.codex/skills/`) Located in the user's home directory. - **Purpose:** Personal productivity workflows unique to an individual developer. - **Advantage:** Accessible across all repositories and terminal sessions on that machine. --- ## 6. Hands-On Workshop: Creating a PR Review Skill with $skill-creator The fastest and most reliable way to scaffold a new skill is using the built-in `$skill-creator` meta-tool provided within Codex. ### Step 1. Launching the Creator Wizard In your active Codex dialog, invoke: ```bash $skill-creator ``` Describe your intended workflow in clear natural language: ```text Create a project-level skill named "pr-validator". Objective: Validate modified files in the current pull request. Rules: 1. Run npm run lint and npm test. 2. Check whether new utility files have corresponding unit tests. 3. Strictly forbid the agent from modifying code autonomously. 4. Format output as a markdown table: File, Line, Issue, Severity. ``` ### Step 2. Reviewing the Generated Artifact The wizard creates `.codex/skills/pr-validator/` and writes `SKILL.md`: ```markdown --- name: pr-validator description: Validates pull request changes by running lint and test suites, checking test coverage for new modules, and returning an issue table without modifying code. --- Execution Steps: 1. Identify modified files using git diff against the target branch. 2. Execute "npm run lint" and capture any linter warnings or errors. 3. Execute "npm test" to ensure regression safety. 4. Verify whether newly created source files in src/ have corresponding test files in tests/. 5. Strict constraint: Do NOT modify any project files under any circumstances. 6. Present the audit findings in a markdown table: | File | Line | Issue | Severity | ``` ### Step 3. Testing the Skill in a Fresh Session Open a new Codex session and test the newly registered skill: ```bash $pr-validator audit my local branch before opening the PR ``` Verify that the agent invokes the test runner, refuses to mutate files autonomously, and presents findings in the requested table schema. --- ## 7. The Triad of Agent Capabilities: Skill, Script, and Tool Developers often confuse skills, scripts, and tools (MCP). They complement one another, but solve fundamentally different engineering problems. ```mermaid flowchart TD subgraph Triad ["Autonomous Agent Capability Triad"] Skill["SKILL
'Reasoning & Workflow'
Guides sequence, context, and operational logic"] Script["SCRIPT
'Deterministic Execution'
Performs reliable, fast computation on disk"] Tool["TOOL (MCP)
'Senses & Actuators'
Provides external API, terminal, and database access"] end Skill -->|Orchestrates| Script Skill -->|Invokes| Tool Script -->|Executed via| Tool ``` ### Capability Comparison Matrix | Component | Primary System Role | Execution Model | Concrete Example | | :--- | :--- | :--- | :--- | | **Skill** | **Workflow regulation and reasoning** | Parsed and interpreted by the model | Step-by-step security review checklist | | **Script** | **Deterministic computational action** | Executed directly in OS shell | Python script parsing git version tags | | **Tool (MCP)** | **Environment interaction interface** | Invoked via Tool Calling protocol | MCP server querying GitHub Pull Requests | > [!NOTE] > A Skill explains **what** to do and in **what sequence**. A Script performs exact operations reliably without token bloat. A Tool grants the permission and interface to communicate with the outside world. --- ## 8. Programmatic Management via Skills API and Versioning Beyond local filesystem files, OpenAI provides a programmatic **Skills API** for enterprise automation, team registries, and custom agent backends. ```bash # Create a new skill programmatically via HTTP API curl https://api.openai.com/v1/skills \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "schema-migrator", "description": "Validates and applies database migrations safely", "instructions": "Inspect Prisma schema, ensure zero destructive drop columns..." }' ``` ### Why Versioning Matters for Agent Skills 1. **Production Immutability:** Updating a skill creates a discrete new version (`v1`, `v2`). Production CI/CD pipelines lock to explicit version tags, preventing runtime breakage from experimental prompt changes. 2. **Instant Rollback:** If an updated prompt causes unexpected regressions, teams can immediately revert to the previous version identifier. 3. **A/B Testing:** Evaluate two alternate prompt structures concurrently against production benchmarks to measure accuracy and token consumption. --- ## 9. Security, Autonomy Boundaries, and Human Confirmation Rules Skills directly govern what operations an AI agent executes on your machine. Clear guardrails separating autonomous actions from dangerous mutations are essential. ```mermaid flowchart LR Action["Agent Operation"] --> Decision{"Operation Risk Profile"} Decision -->|Safe: Read-Only| Auto["Execute autonomously without pausing
(Reading files, running tests)"] Decision -->|Destructive: Write / Network| Confirm["Require explicit engineer approval
(Deleting files, deploying code)"] ``` ### Trust Level Matrix :::tabs @tab Permitted Autonomously - Inspecting source code, configurations, and documentation. - Reviewing build logs and compiler errors in the terminal. - Executing isolated unit test suites in read-only mode. - Formatting audit tables and generating markdown summaries. @tab Requires Human Confirmation - Mutating global configuration files (`package.json`, `.env`). - Deleting, moving, or overwriting existing files in the repository. - Executing network requests or transmitting payload data to external APIs. - Creating commits or pushing branches to remote Git origins. ::: > [!WARNING] > **Avoid Constraint Repetition:** Do not repeat "do not modify files" in every bullet point. Stating the constraint clearly once in a dedicated security section prevents the agent from becoming hyper-passive and requesting permission for harmless read operations. --- ## 10. Summary Cheat Sheet and Production Readiness Checklist Keep this checklist handy whenever designing or auditing custom skills in Codex. ### Developer CLI Cheat Sheet ```bash # ─── Codex Skills Management ───────────────────────────────────── $skill-creator # Launch built-in skill authoring wizard $ # Explicit deterministic skill invocation /skills # List all active skills available in session # ─── Repository File Locations ─────────────────────────────────── .codex/skills//SKILL.md # Project-level skill (tracked in Git) ~/.codex/skills//SKILL.md # Personal global skill (workstation-wide) ``` ### Skill Release Readiness Checklist - [ ] **Kebab-Case Name:** Under 64 characters, lowercase alphanumeric with hyphens (`[a-z0-9-]`). - [ ] **Dual-Condition Description:** Clearly explains both *what the skill does* and *when to trigger it*. - [ ] **Compact Body:** `SKILL.md` body is under 500 lines, focused solely on project-specific rules. - [ ] **Sequential Instructions:** Workflow steps are ordered with numbers (`1.`, `2.`, `3.`) to avoid ambiguity. - [ ] **Clear Security Scope:** Explicitly marks which files can be read and which actions mandate human approval. - [ ] **Verified in Clean Session:** Validated via explicit `$name` invocation and semantic auto-matching.