How to Add a New Skill to the AI-Berkshire Framework: Required Components and Workflow

Adding a new skill to the AI-Berkshire framework requires creating a canonical markdown definition in skills/<skill-name>.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/<skill-name>.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.

• Generated Codex skill (codex-skills/<skill-name>/SKILL.md): A machine-readable version created automatically by 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/<skill-name>.md): A slash-command wrapper produced by scripts/sync-codex-prompts.py that enables Codex CLI invocation via !<skill-name> shortcuts.

Step-by-Step Procedure to Add a Skill

1. Create the Skill Markdown Definition

Add a new file at skills/<skill-name>.md following the established pattern from existing skills such as 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:

# My New Skill: Briefing Generation

对 $ARGUMENTS 生成一份结构化的投资简报.

---

## 支持输入格式

- 主题名称（如 `新能源行业趋势`）
- 目标受众（如 `基金经理`）

## Phase One: Data Collection

使用 `tools/financial_rigor.py` 拉取最新财务数据.

## Phase Two: Content Generation

<Agent prompt template here>

## 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:

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-name>/SKILL.md.

3. Generate the Slash-Command Prompt (Optional)

If your use case requires Codex CLI compatibility with !<skill-name> invocation, run the additional prompt generator:

python3 scripts/sync-codex-prompts.py

This creates codex-prompts/<skill-name>.md containing the prompt wrapper necessary for slash-command access.

4. Verify Generated Artifacts

Confirm the automation produced correct outputs before committing:

# 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 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:

git add skills/<skill-name>.md
git commit -m "Add new skill: <skill-name>"

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 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/<skill-name>.md with the $ARGUMENTS placeholder and workflow definitions.
• Synchronization happens via python3 scripts/sync-codex-skills.py, which generates codex-skills/<skill-name>/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, financial-analysis.md). The 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-name>/SKILL.md or codex-prompts/<skill-name>.md. These are build artifacts generated from skills/<skill-name>.md. Manual changes will be overwritten the next time scripts/sync-codex-skills.py runs, as documented in the project layout section of 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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}