# How to Add a New Skill to the AI-Berkshire Framework: Required Components and Workflow > Learn how to add a new skill to the AI-Berkshire framework. Discover the required markdown definition and scripting workflow for seamless integration and Codex compatibility. - Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire) - Tags: how-to-guide - Published: 2026-07-26 --- **Adding a new skill to the AI-Berkshire framework requires creating a canonical markdown definition in `skills/.md` and running `python3 scripts/sync-codex-skills.py` to generate machine-readable artifacts for Codex compatibility.** The AI-Berkshire project (repository: `xbtlin/ai-berkshire`) implements skills as self-contained workflows that agents invoke from either Claude Code or Codex. When you add a new skill to the AI framework, you create a modular, reusable agent workflow defined in human-readable markdown that automatically synchronizes to multiple execution environments through the repository's build scripts. ## Required Components for a New Skill The AI-Berkshire architecture divides skill definitions into three tightly-coupled components. Understanding these locations prevents drift between human-readable sources and machine-executable artifacts. - **Skill source file** (`skills/.md`): The canonical, human-readable definition containing the prompt template, agent flow, and input format specifications. This file serves as the single source of truth; any modification drives all generated artifacts according to the compatibility rules in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md). - **Generated Codex skill** (`codex-skills//SKILL.md`): A machine-readable version created automatically by [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py). The repository treats `skills/*.md` as authoritative, so this file should never be manually edited. - **Generated Codex prompt (optional)** (`codex-prompts/.md`): A slash-command wrapper produced by [`scripts/sync-codex-prompts.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-prompts.py) that enables Codex CLI invocation via `!` shortcuts. ## Step-by-Step Procedure to Add a Skill ### 1. Create the Skill Markdown Definition Add a new file at `skills/.md` following the established pattern from existing skills such as [`wechat-article.md`](https://github.com/xbtlin/ai-berkshire/blob/main/wechat-article.md). The file must include: - A top-level heading with the skill name - A brief description including the `$ARGUMENTS` placeholder for user input - Clear workflow sections (e.g., "阶段一：研究与素材收集") defining Agent prompts or Bash commands - Output file naming conventions and target audience specifications Example structure: ```markdown # My New Skill: Briefing Generation 对 $ARGUMENTS 生成一份结构化的投资简报. --- ## 支持输入格式 - 主题名称（如 `新能源行业趋势`） - 目标受众（如 `基金经理`） ## Phase One: Data Collection 使用 `tools/financial_rigor.py` 拉取最新财务数据. ## Phase Two: Content Generation ## Output File Naming `reports/briefing-{topic}-{YYYYMMDD}.md` ``` ### 2. Run the Sync Script From the repository root, execute the synchronization script to regenerate all Codex-compatible skill files: ```bash python3 scripts/sync-codex-skills.py ``` This script reads every file under `skills/` and overwrites the corresponding `codex-skills/*/SKILL.md` files. Successful completion displays the message "⚙️ Sync completed", confirming the new skill now exists at `codex-skills//SKILL.md`. ### 3. Generate the Slash-Command Prompt (Optional) If your use case requires Codex CLI compatibility with `!` invocation, run the additional prompt generator: ```bash python3 scripts/sync-codex-prompts.py ``` This creates `codex-prompts/.md` containing the prompt wrapper necessary for slash-command access. ### 4. Verify Generated Artifacts Confirm the automation produced correct outputs before committing: ```bash # Verify the generated skill file exists ls codex-skills/my-new-skill/SKILL.md # Inspect the auto-generated content cat codex-skills/my-new-skill/SKILL.md ``` The first few lines of the generated [`SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SKILL.md) should contain an autogenerated description referencing your source file path. For prompt files, verify the markdown header matches your skill name exactly. ### 5. Commit the Source Changes Commit only the canonical source file. Generated files in `codex-skills/` and `codex-prompts/` are recreated on every sync execution and should not be version-controlled unless explicitly required for reproducibility: ```bash git add skills/.md git commit -m "Add new skill: " ``` ## Why This Architecture Works The AI-Berkshire framework enforces three architectural principles that make skill addition reliable: - **Single source of truth**: By mandating that `skills/*.md` serves as the authoritative definition, the project eliminates configuration drift between Claude Code and Codex representations. - **Automation**: The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) script guarantees that modifications propagate instantly to the Codex package, removing manual copy-paste steps that introduce bugs. - **Extensibility**: Adding a skill never requires touching core tooling in `tools/` or modifying existing skills. The required touch-points remain limited to the `skills/` directory and the sync scripts. ## Summary - **Adding a new skill** requires authoring a markdown file in `skills/.md` with the `$ARGUMENTS` placeholder and workflow definitions. - **Synchronization** happens via `python3 scripts/sync-codex-skills.py`, which generates `codex-skills//SKILL.md` automatically. - **Optional CLI integration** requires running `python3 scripts/sync-codex-prompts.py` to create slash-command wrappers in `codex-prompts/`. - **Version control** should track only the source markdown in `skills/`, not the generated artifacts in `codex-skills/` or `codex-prompts/`. ## Frequently Asked Questions ### What file naming convention should I use for new skills? Use lowercase with hyphens for multi-word skill names (e.g., [`investment-memo.md`](https://github.com/xbtlin/ai-berkshire/blob/main/investment-memo.md), [`financial-analysis.md`](https://github.com/xbtlin/ai-berkshire/blob/main/financial-analysis.md)). The [`sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/sync-codex-skills.py) script derives directory names directly from your filename, so consistency ensures predictable paths in `codex-skills/`. ### Do I need to manually edit the generated SKILL.md files? No. Never manually edit files in `codex-skills//SKILL.md` or `codex-prompts/.md`. These are build artifacts generated from `skills/.md`. Manual changes will be overwritten the next time [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) runs, as documented in the project layout section of [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md). ### Can I use external tools within my skill definition? Yes. Reference external tools using their relative paths (e.g., [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)) within your skill markdown. The framework executes these as Bash commands or Agent invocations depending on the context defined in your workflow sections. ### What happens if I forget to run the sync script? If you commit only the source file without running `python3 scripts/sync-codex-skills.py`, the Codex-compatible artifacts will not exist in `codex-skills/`, making the skill unavailable to Codex users. The CI/CD pipeline or other contributors must run the sync to generate the missing files.