How Skills Are Defined and Formatted in AI-Berkshire: A Complete Guide

AI-Berkshire defines each skill as a self-contained markdown file under the skills/ directory, using a standardized structure that supports Claude-Code slash commands and auto-generates Codex skill packages via the scripts/sync-codex-skills.py utility.

The AI-Berkshire repository treats research workflows as version-controlled, executable specifications. Rather than hardcoding logic in Python modules, the project stores canonical skill definitions as markdown documents that both human operators and automated agents can parse. This architecture enables complex multi-agent pipelines—such as the author-editor-reader workflow for WeChat article generation—while maintaining strict data integrity through embedded validation hooks.

The Self-Contained Markdown Architecture

Every skill in AI-Berkshire lives as a standalone .md file within the skills/ directory. According to the repository layout documented in AGENTS.md, these files serve as the single source of truth for both Claude-Code command dispatching and the generated Codex skill packages under codex-skills/.

The markdown format is deliberate. Claude-Code parses these files to extract:

• The command name (from the H1 heading)
• Required arguments (from the "Supported input format" section)
• Agent prompts (from fenced code blocks)
• Validation rules (from "Redlines" tables)

This eliminates the need for separate configuration files; the documentation itself is executable.

Anatomy of a Skill File

A valid skill file follows a rigid structural contract designed to be read by both humans and the sync-codex-skills.py converter.

H1 Title and Brief Description

The file opens with an ATX-style H1 containing the skill name, followed immediately by a one-sentence description of the operation:

# 微信公众号文章：作者-编辑-读者三Agent协作

对 $ARGUMENTS 进行深度研究，产出一篇可直接发布的微信公众号文章。

The $ARGUMENTS placeholder signals to the command dispatcher that this skill requires user input.

Input Format Specification

The next section defines the expected argument structure using backticks for example values:

## 支持输入格式

主题描述，例如：`大模型OPD技术解读`

Phased Workflow Design

Complex skills decompose into numbered stages reflecting the multi-agent pipeline. As seen in skills/wechat-article.md, the workflow progresses through distinct phases:

• 阶段一：研究与素材收集 (Research & Material Collection)
• 阶段二：作者Agent写初稿 (Author Agent Drafting)
• 阶段三：编辑Agent润色 (Editor Agent Refinement)
• 阶段四：读者Agent评审 (Reader Agent Review)

Each phase contains decision tables mapping dimensions to default values:

| 维度 | 需要确认 | 默认值 |
|------|----------|--------|
| 目标读者 | 技术背景程度 | 有点技术背景但非该领域专家 |
| 文章深度 | 科普/中深度/硬核 | 中深度 |

Prompt Templates With Variable Substitution

Agent-specific system prompts reside in fenced code blocks using the text specifier. These templates include brace-delimited variables such as {目标字数} or {完整初稿} that the runner substitutes at execution time:

你是一位深度技术写作者（Author Agent），需要写一篇微信公众号文章。

## 目标读者

{根据第一步确认的读者画像}

## 写作风格要求

- 纯中文表达...
...
请写出完整的文章初稿，约{目标字数}字。

Separate blocks exist for each agent role (Author, Editor, Reader), allowing the skill to orchestrate handoffs between specialized LLM instances.

Output Requirements and Storage Conventions

Skills specify deterministic output paths to ensure reproducibility. The WeChat article skill, for example, mandates:

• File naming: reports/…/公众号-<主题>-<YYYYMMDD>.md
• Asset storage: assets/<主题简称>/
• Citation requirements: URLs appended to the markdown footer

These conventions are documented in dedicated tables under "文件命名与存储" sections.

Redlines and Validation Rules

Data integrity constraints appear as numbered lists or tables under "Redlines" headings. Common requirements include:

1. No hallucinated data (不虚构数据)
2. LaTeX formatting for formulas (公式必须用 LaTeX)
3. Real image insertion (真实图片插入)

These rules map directly to validation utilities invoked during execution.

Multi-Agent Pipeline Design

Most skills in AI-Berkshire model collaborative workflows rather than single-prompt operations. The skills/investment-research.md and skills/wechat-article.md files both implement a staged agent pattern:

1. Research Phase: Information gathering and source verification
2. Drafting Phase: Content generation via Author Agent
3. Editing Phase: Style and accuracy refinement via Editor Agent
4. Review Phase: Final validation via Reader Agent or external tools

This design leverages the markdown structure to serialize agent state between phases, with the output of one fenced code block becoming the input variable for the next.

Validation and Quality Enforcement

Skills embed explicit verification steps by referencing shared utilities in the tools/ directory. The specification allows skills to invoke:

• tools/financial_rigor.py – Validates financial data accuracy and sourcing
• tools/report_audit.py – Checks compliance with research quality rules

These hooks are documented in the Validation Rules section of each skill file and execute before the final artifact generation, ensuring that redlines such as "no AI-tone" or "LaTeX for formulas" are mechanically enforced rather than merely suggested.

Synchronization to Codex Skill Packages

The repository maintains a strict separation between source definitions and generated artifacts. The helper script scripts/sync-codex-skills.py converts each skills/*.md file into a corresponding Codex package under codex-skills/*/SKILL.md.

Critical architectural rule: The generated Codex artifacts must never be edited directly. All modifications flow through the markdown source files in skills/, ensuring that Claude-Code commands and Codex implementations remain synchronized. The conversion script handles:

• Extracting the H1 title for the skill name
• Parsing argument specifications
• Packaging prompt templates for the Codex runtime

Summary

• Canonical source: All skill definitions reside as markdown files in skills/, with skills/wechat-article.md and skills/investment-research.md serving as reference implementations.
• Structural contract: Each file contains H1 title, input format, phased workflow sections, agent prompt templates (with variable substitution), output conventions, and redline validation rules.
• Multi-agent orchestration: Skills define pipelines that hand off context between specialized Author, Editor, and Reader agents using fenced code blocks as prompt boundaries.
• Mechanical enforcement: Validation hooks to tools/financial_rigor.py and tools/report_audit.py ensure data integrity constraints are checked before final output.
• Generation workflow: The scripts/sync-codex-skills.py utility converts markdown sources to Codex packages under codex-skills/, maintaining AI-Berkshire as the single source of truth.

Frequently Asked Questions

What is the relationship between skills/ markdown files and the codex-skills/ directory?

The skills/ directory contains the human-editable, canonical markdown definitions. The codex-skills/ directory contains auto-generated packages derived from these sources via scripts/sync-codex-skills.py. You should never edit files under codex-skills/ directly; instead, modify the markdown source and run the sync script to regenerate the Codex-compatible artifacts.

How does variable substitution work in skill prompts?

Skill files use brace notation (e.g., {目标字数}, {完整初稿}) to denote placeholders. When the Claude-Code runner executes the skill, it substitutes these variables with values gathered from previous phases or user input. This allows multi-agent workflows to pass context—for example, the Editor Agent receives the Author Agent's output by referencing the {完整初稿} variable in its prompt template.

Why are validation rules embedded directly in the markdown rather than in separate code files?

Embedding redlines (such as "不虚构数据" or "公式必须用 LaTeX") within the skill specification serves dual purposes: it acts as documentation for human operators while providing executable constraints for the validation tools. The tools/financial_rigor.py and tools/report_audit.py utilities parse these sections to enforce compliance, ensuring that business-logic constraints are version-controlled alongside the prompts themselves.

Can I create a new skill by copying an existing markdown file?

Yes. The recommended approach is to copy an existing file like skills/wechat-article.md or skills/investment-research.md, modify the H1 title to reflect the new command name, and adjust the phased workflow sections and prompt templates to match your specific research requirements. After saving the new file, run scripts/sync-codex-skills.py to generate the corresponding Codex package, making the skill available to both Claude-Code and the Codex runtime.

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