Harden Skills And Documentation · feiskyer/codex-settings@74f9e98 · GitHub
Skip to content

Commit 74f9e98

Browse files
feiskyerfeiskyer
committed
Harden Skills And Documentation
1 parent 7a0df04 commit 74f9e98

21 files changed

Lines changed: 1599 additions & 277 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions

‎AGENTS.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Repository Guidelines
2+
3+
## Repository Structure
4+
5+
- `config.toml` is the shared Codex CLI configuration and points to the local `copilot-gateway` provider at `localhost:4141`.
6+
- Root-level `*.config.toml` files are optional Codex Profiles (`chatgpt`, `azure`, `github-copilot`, and `openrouter`). Keep the `<name>.config.toml` naming required by `codex --profile <name>`.
7+
- `skills/<name>/SKILL.md` contains reusable workflows. Put deterministic helpers in `scripts/`, detailed references in `references/`, UI metadata in `agents/openai.yaml`, and offline regression tests in `tests/`.
8+
- `prompts/` contains historical Custom Prompts retained for migration reference. Do not add new workflows there; use a Skill instead.
9+
- `litellm_config.yaml` is only for the optional GitHub Copilot through LiteLLM profile. It is not the backend used by the default `config.toml`.
10+
11+
## Validation Commands
12+
13+
Run checks that match the files you changed. The standard offline suite is:
14+
15+
```bash
16+
# TOML syntax
17+
python3 -c 'import pathlib, tomllib; [tomllib.loads(p.read_text()) for p in pathlib.Path(".").glob("**/*.toml")]'
18+
19+
# Skill structure
20+
for skill in skills/*; do
21+
test ! -f "$skill/SKILL.md" || \
22+
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py "$skill"
23+
done
24+
25+
# Python scripts and offline tests
26+
python3 -m compileall -q skills
27+
ruff check skills
28+
for test_dir in skills/*/tests; do
29+
test ! -d "$test_dir" || python3 -m unittest discover -s "$test_dir" -v
30+
done
31+
32+
# Bundled shell and JavaScript helpers
33+
bash -n skills/brainstorming/scripts/start-server.sh \
34+
skills/brainstorming/scripts/stop-server.sh
35+
node --check skills/brainstorming/scripts/server.cjs
36+
node --check skills/brainstorming/scripts/helper.js
37+
```
38+
39+
Run provider integration checks only when the related provider files change:
40+
41+
- Strict Codex config: with the relevant provider available, run `CODEX_HOME="$PWD" codex --strict-config exec --ephemeral --sandbox read-only --skip-git-repo-check -c mcp_servers.chrome.enabled=false -c web_search="disabled" "Reply exactly OK"`.
42+
- Default gateway: start `copilot-gateway`, then run `codex` or `codex doctor --summary`.
43+
- LiteLLM profile: start `litellm --config ~/.codex/litellm_config.yaml`, then run `codex --profile github-copilot`.
44+
- ChatGPT profile: authenticate with `codex login`, then run `codex --profile chatgpt`.
45+
- External API Skills: prefer mocked/offline tests. Use real credentials only for an explicitly requested integration test.
46+
47+
## Style and Skill Conventions
48+
49+
- TOML uses two-space indentation where indentation applies, aligned `=` signs within related blocks, double-quoted strings, and grouped tables.
50+
- Name Profiles, Skills, prompts, and scripts with lowercase kebab-case unless the platform requires another filename.
51+
- Skill frontmatter contains only `name` and `description`. Put requirements and compatibility notes in the body.
52+
- Write Skill instructions in imperative form. Keep the core workflow concise and move repeatable or fragile behavior into bundled scripts.
53+
- Add or refresh `agents/openai.yaml` when a Skill is created or materially renamed. Its `default_prompt` must mention `$skill-name`.
54+
- Scripts must expose `--help`, validate local inputs before network/API calls, return non-zero on failure, and create output parent directories when appropriate.
55+
- Tests must not require paid API calls, browser cookies, interactive approval, or live third-party services unless the user explicitly requests an integration run.
56+
57+
## Commit and Pull Request Guidelines
58+
59+
- Use concise title-case imperative commit subjects, consistent with repository history.
60+
- Keep commits scoped; do not include local Codex runtime state, credentials, generated logs, or unrelated working-tree changes.
61+
- In pull requests, list affected configs or Skills, validation commands run, intentionally skipped integration checks, and any compatibility assumptions.
62+
- Use redacted placeholders such as `sk-dummy` in examples.
63+
64+
## Security
65+
66+
- Never commit API keys, access tokens, cookies, real authorization headers, or private logs.
67+
- Review `shell_environment_policy`, sandbox, network, MCP, and browser-cookie behavior when changing integrations.
68+
- Do not silently broaden permissions or enable browser-cookie access. Explain the need and obtain user approval first.
69+
- Follow `SECURITY.md` for vulnerability reporting.

‎COMPATIBILITY.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# 兼容性策略
2+
3+
## 支持模式
4+
5+
`main` 分支采用滚动更新模式，目标是当前稳定版 Codex CLI。模型提供商 API、模型标识符、实验性功能开关和浏览器集成都可能独立变化，因此每个 Pull Request 都应使用当时安装的稳定版 Codex CLI 验证其修改范围。
6+
7+
在项目发布第一个正式版本之前，`main` 是唯一受支持的版本线。未来发布版本时，应使用语义化版本标签，并在发布说明中记录已验证的 Codex CLI 版本和模型提供商相关假设。
8+
9+
## 兼容性要求
10+
11+
- `config.toml` 和根目录下的 `*.config.toml` Profiles 应通过变更所使用稳定版 Codex CLI 的严格配置校验。
12+
- Skills 应遵循当前的 `SKILL.md` 和 `agents/openai.yaml` 结构，并能在支持 Skills 的 Codex 产品形态中使用。
13+
- Python、Shell 和 JavaScript 脚本应在对应 Skill 中说明非标准前置依赖，并提供无需凭据即可执行的 `--help` 或语法检查方式。
14+
- 外部模型名称、MCP 服务、浏览器 DOM 选择器和模型提供商认证流程属于兼容性边界，不视为永久稳定接口。
15+
- `prompts/` 下的历史文件仅作为迁移参考，不属于当前主动支持的 Skill 接口。
16+
17+
## 破坏性变更
18+
19+
以下情况属于需要明确说明的兼容性变更：
20+
21+
- 删除或重命名 Profile 或 Skill
22+
- 改变所需凭据或认证方式
23+
- 扩大默认权限或网络访问范围
24+
- 改变输出文件格式
25+
- 删除已经文档化的命令行参数
26+
27+
此类变更应在 Commit 或 Pull Request 中明确标注，并提供迁移说明。

‎CONTRIBUTING.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# 贡献指南
2+
3+
感谢你参与改进这个 Codex 配置与 Skills 仓库。
4+
5+
## 开始之前
6+
7+
1. 阅读 `AGENTS.md`，了解当前仓库结构、开发约定和验证命令。
8+
2. 每次变更只聚焦一个模型提供商、Skill、工作流或文档问题。
9+
3. 如果提案会改变默认权限、认证方式、模型提供商行为，或同时影响多个 Skill 的公开接口，请先创建 Issue 讨论。
10+
11+
## 开发要求
12+
13+
- 不要把真实凭据或用户本地运行状态提交到仓库。
14+
- 对重复、脆弱或需要确定性执行的逻辑，应在 Skill 的 `scripts/` 目录中提供脚本，不要要求 Agent 每次临时生成。
15+
- 为脚本、解析器、参数处理、文件行为和常见失败路径，在 `skills/<name>/tests/` 下添加离线测试。
16+
- `SKILL.md` 只保留 Skill 触发后 Agent 真正需要的核心流程；较长的参考资料应放在 `references/` 中。
17+
- 当 Skill 的用途、显示名称或默认调用方式发生变化时，同步更新 `agents/openai.yaml`。
18+
19+
## 验证
20+
21+
运行 `AGENTS.md` 中与改动相匹配的检查。至少应完成：
22+
23+
1. 解析所有修改过的 TOML 文件。
24+
2. 对每个修改过的 Skill 运行 `quick_validate.py`。
25+
3. 对修改过的脚本运行语法检查和离线测试。
26+
4. 确认命令行脚本无需凭据也能显示 `--help`。
27+
5. 提交前运行 `git diff --check`。
28+
29+
不要仅为了满足 Pull Request 检查而调用真实付费 API。如果确实需要集成测试，应使用权限最小的凭据、清理日志中的敏感信息，并记录可复现的人工步骤，但不要公开任何密钥。
30+
31+
## Pull Request 要求
32+
33+
Pull Request 应包含：
34+
35+
- 问题与解决方案的简要说明
36+
- 受影响的配置或 Skills
37+
- 已执行的自动化和人工验证
38+
- 有意跳过的集成测试及原因
39+
- 对安全、权限或兼容性的影响
40+
41+
不要混入无关格式化、个人配置或其他工作区修改。
42+
43+
## 兼容性与发布
44+
45+
`main` 是滚动更新分支，目标是当前稳定版 Codex CLI。完整支持策略见 `COMPATIBILITY.md`。如果变更会主动放弃兼容性或改变公开工作流，应在 Pull Request 和发布说明中明确指出。

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,9 @@ codex --profile chatgpt
154154
├── litellm_config.yaml # GitHub Copilot/LiteLLM 示例
155155
├── skills/ # Codex Skills 及其脚本和参考资料
156156
├── prompts/ # 历史 Custom Prompts
157+
├── CONTRIBUTING.md # 贡献流程和验证要求
158+
├── SECURITY.md # 安全问题报告策略
159+
├── COMPATIBILITY.md # 兼容性和版本支持策略
157160
└── LICENSE # MIT License
158161
```
159162

@@ -295,6 +298,8 @@ codex mcp list
295298

296299
欢迎通过 [Issues](https://github.com/feiskyer/codex-settings/issues) 和 [Pull Requests](https://github.com/feiskyer/codex-settings/pulls) 提交改进。
297300

301+
完整流程见 [CONTRIBUTING.md](CONTRIBUTING.md)，安全问题请按 [SECURITY.md](SECURITY.md) 私下报告，版本与兼容性边界见 [COMPATIBILITY.md](COMPATIBILITY.md)。
302+
298303
提交前请确认：
299304

300305
1. 没有包含真实密钥、个人配置或敏感日志。

‎SECURITY.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# 安全策略
2+
3+
## 支持范围
4+
5+
安全修复会应用到 `main` 分支；如果未来存在正式版本，则同时支持最新发布版本。更早的仓库快照和特定模型提供商示例仅提供尽力而为的支持。
6+
7+
## 报告安全问题
8+
9+
不要在公开 Issue 中披露漏洞、凭据、访问令牌、Cookie、私有 Prompt 或用户数据。
10+
11+
优先使用本仓库的 GitHub 私密漏洞报告功能，或创建 GitHub Security Advisory 草稿。如果私密报告不可用，请通过仓库所有者 GitHub 主页提供的联系方式建立私密沟通渠道；首次联系时只提供建立私密渠道所需的最少信息。
12+
13+
报告中建议包含：
14+
15+
- 受影响的文件、Skill 或配置
16+
- 实际影响和可能的攻击场景
17+
- 最小复现步骤
18+
- 相关的 Codex、Python、Node.js 或模型提供商版本
19+
- 建议的缓解或修复方案
20+
21+
所有密钥都应使用脱敏占位符。如果真实凭据已经泄露，请在发送报告前立即撤销或轮换。
22+
23+
## 安全问题范围
24+
25+
以下问题属于本仓库的安全报告范围：
26+
27+
- 未经预期的权限提升
28+
- 凭据、Cookie 或敏感信息泄露
29+
- 不安全的命令构造
30+
- 路径遍历或越界文件访问
31+
- 不受信任的 MCP 执行
32+
- 浏览器 Cookie 使用不当
33+
- 日志或输出产物泄露私密信息
34+
35+
第三方服务故障、上游模型行为，以及无法通过本仓库形成实际利用路径的依赖漏洞，通常应优先报告给对应的上游项目。

‎skills/claude-skill/SKILL.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,17 @@
11
---
22
name: claude-skill
33
description: Use when work should be delegated to Claude Code CLI, especially headless `claude -p` runs, automation scripts, CI jobs, resumable sessions, or requests to use Claude/Claude Code for a task.
4-
compatibility: Requires Claude Code CLI (`claude`) installed and authenticated on the target machine.
54
---
65

76
# Claude Code Headless Mode
87

98
Use this skill when the job should be executed through Claude Code itself, not solved inline. Focus on commands and workflows that match current stable Claude Code behavior.
109

10+
## Requirements
11+
12+
- Install and authenticate the Claude Code CLI (`claude`) on the target machine.
13+
- Treat the installed CLI's `claude --help` output as the compatibility source of truth.
14+
1115
## Core Rules
1216

1317
- Treat `claude --help` on the target machine as the compatibility floor. CLI flags move faster than blog posts and copied examples.

‎skills/claude-skill/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions

0 commit comments

Comments
 (0)