Preface¶

When writing code with AI programming tools like Cursor and Codex CLI, the speed is often an order of magnitude faster than manual coding, but security details are more likely to be overlooked: SQL injection, insecure CORS configurations, Cookies without the HttpOnly flag, public interfaces using auto-incrementing IDs… These issues are not uncommon in boilerplate code generated by AI. Traditional practices rely on security teams to perform Code Reviews or run SAST scans before deployment, which are costly and slow.

OpenAI provides the security-best-practices Agent Skill in the .curated directory of the official openai/skills repository. It embeds security specifications for common frameworks in Python, JavaScript/TypeScript, and Go into the references/ reference documents, allowing Agents to follow established rules when writing new code, conducting passive inspections, or generating security reports. This article introduces its positioning, capabilities, and usage based on verification against the official SKILL.md and reference files.

What is This¶

security-best-practices is one of OpenAI’s officially curated Skills, following the universal Agent Skills format (SKILL.md + resource directory). The official description is: Perform security best practice reviews and provide improvement suggestions for languages and frameworks; only trigger when the user explicitly requests security best practice guidance, security reviews/reports, or secure-by-default coding assistance; only supports Python, JavaScript/TypeScript, Go; not intended for general code reviews, debugging, or non-security-related tasks.

The Skill directory structure (extracted from the official repository) is roughly as follows:

security-best-practices/
├── SKILL.md              # Skill description, workflow and report format
├── references/           # Security specifications for languages/frameworks (MUST/SHOULD level requirements)
│   ├── python-django-web-server-security.md
│   ├── python-fastapi-web-server-security.md
│   ├── python-flask-web-server-security.md
│   ├── javascript-express-web-server-security.md
│   ├── javascript-general-web-frontend-security.md
│   ├── javascript-jquery-web-frontend-security.md
│   ├── javascript-typescript-nextjs-web-server-security.md
│   ├── javascript-typescript-react-web-frontend-security.md
│   ├── javascript-typescript-vue-web-frontend-security.md
│   └── golang-general-backend-security.md
├── agents/               # Agent-related configurations
└── LICENSE.txt

The official README notes that the openai/skills repository has been marked as deprecated, and subsequent Skill examples will be migrated to the OpenAI Plugins repository; the Skills in the current directory can still be installed and used, and teams are advised to follow upstream updates when implementing locally.

Core Features and Highlights¶

1. Automatically Identify Tech Stack and Load Corresponding Specifications¶

The first step of the Skill is to identify all languages and core frameworks in the project (covering both frontend and backend). It then looks up matching documents in the references/ directory: the filename format is <language>-<framework>-<stack>-security.md, and there may also be general specifications independent of specific frameworks, such as <language>-general-<stack>-security.md.

For example, for a full-stack Web project using React + FastAPI, the Agent should load javascript-typescript-react-web-frontend-security.md and python-fastapi-web-server-security.md respectively; if the frontend framework is not specified, the official recommends additionally consulting javascript-general-web-frontend-security.md.

2. Three Working Modes¶

The official SKILL.md defines three complementary operating modes:
1. Secure-by-default Coding (Primary Mode): Follow the MUST/SHOULD requirements in the reference specifications by default when writing new code, suitable for new projects or new modules.
2. Passive Detection: During daily code changes, remind about high-impact vulnerabilities or obvious violations of security guidelines within the scope of changes, focusing on the highest-risk items.
3. Active Security Reporting: When the user explicitly requests a security review or improvement, generate a complete report graded by severity with repair suggestions attached.

If there is no matching document in references/, the Agent can combine known best practices or conduct online searches; when generating a report, it should honestly state that “there is no specific official reference document” to avoid treating inferences as definitive conclusions.

3. 10 Built-in Framework-level Security Specifications¶

The references/ directory currently contains 10 Markdown specifications, each ranging from 30,000 to 50,000 words, written in the form of MUST/SHOULD/MAY normative requirements + audit rules. Taking python-fastapi-web-server-security.md as an example, the covered content includes:
- Security boundaries: Prohibit outputting/logging secrets, prohibit “fake fixes” such as disabling CORS or skipping signature verification
- Input trust model: Query, Body, Header, Cookie, file uploads, and WebSocket messages are all considered untrusted
- Audit sequence: Entry script → ASGI configuration → Middleware/CORS → Authentication and authorization → CSRF → Injection vulnerabilities → SSRF, etc.
- Specific behavioral requirements for the three modes: generation, passive detection, and active reporting

Other reference files cover scenarios such as Django, Flask, Express, Next.js, React, Vue, jQuery frontend, and Go backend. The Agent will read all files related to the current technology stack, not just one single document.

4. Structured Security Report¶

When the user requests a security report, the Skill requires writing the result to security_best_practices_report.md (or a user-specified path), with the format including:
- A brief executive summary at the top
- Sections grouped by severity, with each finding labeled with a numeric ID for easy reference
- Critical-level issues with a one-sentence impact explanation
- Code references must be annotated with file paths and line numbers
- After writing the report, summarize it in the conversation and specify the file save location

5. Cautious Repair Process¶

The Skill has clear constraints on the repair环节 to avoid “breaking the project while fixing security issues”:
- Fix only one finding at a time, with brief comments explaining the security practice basis for the changes
- Evaluate the impact on existing functions before repair, as insecure code may be relied on by other logic
- Follow the user’s existing commit/test workflow; do not bundle multiple unrelated findings into a single commit
- If the project documentation explicitly requires overriding a best practice, the Agent should respect it and note the override in comments instead of conflicting with the user

6. Cross-language General Security Recommendations¶

SKILL.md also includes several language-agnostic tips, such as:
- Avoid using small integer auto-incrementing IDs for publicly exposed resources, use UUID4 or random hex instead to reduce enumeration risks
- Development environments usually do not have TLS enabled, do not directly report “TLS not enabled” as a vulnerability; the Secure Cookie flag should only be enabled in HTTPS deployments to avoid interrupting local debugging
- Recommend HSTS with caution, as misconfiguration may cause long-term outages

7. Collaboration with Security Skill Suites¶

In the OpenAI curated directory, security-best-practices, security-threat-model, and security-ownership-map form a security trio: threat modeling → code ownership mapping → best practice enforcement, which can be installed and used in combination as needed.

Installation and Activation¶

security-best-practices follows the universal SKILL.md format and can be used in tools that support Agent Skills such as Codex CLI and Cursor. The following methods are from the official README or public documentation of the Agent Skills ecosystem; please refer to the local environment for tool-specific details.

Method 1: Codex CLI Built-in Installer¶

Execute in the Codex session (curated Skills can be installed directly by name):

$skill-installer security-best-practices

You can also specify the GitHub directory URL:

$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/security-best-practices

After installation, restart Codex to load the new Skill. The default installation path is $CODEX_HOME/skills/ (usually ~/.codex/skills/). Use $skill-installer list to view the installed list.

Method 2: Skills CLI Installation¶

npx skills add https://github.com/openai/skills --skill security-best-practices

Method 3: Manually Copy the Skill Directory¶

The Skill is self-contained, and you need to copy the entire security-best-practices folder (including references/), not just SKILL.md:

# Project-level (Cursor example)
.cursor/skills/security-best-practices/

# Project-level (Claude Code example)
.claude/skills/security-best-practices/

# Codex user-level
~/.codex/skills/security-best-practices/

Note: If you only copy SKILL.md without the references/ directory, the Agent will not be able to load framework-level security specifications, and the review quality will be significantly reduced.

Typical Usage Examples¶

After enabling the Skill, you need to explicitly express security-related intentions to trigger it (it will not replace ordinary code reviews). The following are prompt examples organized based on the official workflow:

Example 1: Security Review of an Existing FastAPI Project

Please conduct a security best practices review of the current FastAPI project,
output a report graded by severity, write it to security_best_practices_report.md,
and annotate file paths and line numbers when referencing code.

Example 2: Secure-by-default Development of New Features

I need to add a user registration interface for Express, please write it according to the security-best-practices
specifications, using secure password hashing, input validation, and reasonable CORS configuration by default.

Example 3: Full-stack Project Coverage for Both Frontend and Backend

This is a full-stack project using Next.js + Django, please check if the frontend and backend comply with
the security requirements of the corresponding frameworks in security-best-practices, and list Critical and High-level issues.

Example 4: Fix a Single Finding

Please provide a minimal change repair solution based on finding #3 in security_best_practices_report.md,
run existing tests after the fix to confirm no regressions.

The Agent will first identify the technology stack, load relevant files in references/, and then perform coding, passive reminder, or report generation according to the mode.

Applicable Scenarios and Notes¶

Who It Is For¶

Developers who use AI to rapidly iterate Web backends or full-stack projects and want to embed security checks during the development phase.
Technical leads who hope to obtain structured security reports at PR or iteration nodes instead of scattered reminders.
Security or platform engineers who are learning how to write Agent Skills and want to reference the design pattern of “specification documents + multi-mode workflow”.

Usage Restrictions¶

Must Be Triggered Proactively: The Skill will not automatically intervene in ordinary requests such as “help me fix a bug” or “optimize performance”; the description must include clear intentions such as security review, secure-by-default, etc.
Limited Language Coverage: The official only covers Python, JavaScript/TypeScript, and Go; for Rust, Java, PHP, etc., you need to rely on the Agent’s general knowledge, and conclusions should be more cautious when there is no bundled reference document.
Requires Complete Skill Directory: references/ is the core value of the Skill, and without it, only general suggestions in SKILL.md will be available.
Does Not Replace Professional Penetration Testing: The Skill targets best practices and common vulnerability patterns, and cannot replace manual red teaming, dependency scanning, or compliance audits.
Respect Project Overrides: If business documentation explicitly requires bypassing a specification, the Agent will cooperate instead of forcibly “fixing”; teams can record the override reason in the project for consistent execution in the future.
Upstream Repository Status: openai/skills has been deprecated, and for long-term use, it is recommended to follow the migration instructions of OpenAI Plugins or Codex Skills documentation.

Summary¶

security-best-practices packages OpenAI’s organized language/framework security specifications into an Agent Skill, allowing AI-assisted development to no longer default to sacrificing security through three paths: “identify technology stack → load references → coding/inspection/reporting”. For Web projects using Python, JavaScript/TypeScript, or Go technology stacks, it is a security baseline Skill worth prioritizing installation in the Codex official curated directory; when used in combination with Skills such as threat modeling and ownership mapping, a more complete security workflow can be formed.

Official Skill repository:
- https://github.com/openai/skills/tree/main/skills/.curated/security-best-practices
- Codex Skills documentation: https://developers.openai.com/codex/skills
- Agent Skills open standard: https://agentskills.io

OpenAI Official Security-Best-Practices: Performing Security Reviews of AI According to Languages and Frameworks