AGENTS.md, SKILL.md, and DESIGN.md: Structuring AI prompt roles in outsourced development (2026)

With "Role Separation for AI Instruction Files: AGENTS.md, SKILL.md, DESIGN.md, and the Current State of Specification-Driven Development" trending long-term on Zenn, the practice of dividing AI coding agent instructions by role is rapidly becoming standard. Claude Code, Cursor, and GitHub Copilot are all converging on architectures that automatically load *.md placed at the project root, providing the foundation for custom development to "unify AI operational quality across multi-client projects."

Previously, AI instructions commonly followed a style of "stuffing everything into README.md or CLAUDE.md," leading to bloated files, diminished retrieval precision, and rule collisions across clients. This article outlines an architecture for incorporating the role separation of AGENTS.md, SKILL.md, and DESIGN.md into standard custom development workflows. The methodology for "extracting practices directly from the codebase and embedding them" is covered separately in Passing Down 'Our Way' to Claude Code; this article serves to explain the foundational scaffolding that supports it.

Role separation among the three files

Here is the division of roles currently standardizing across the industry.

Because these three files differ in "when they are read" and "in what context they are read," separating them cleanly maximizes the efficiency of the AI's context window.

AGENTS.md — "Who should act and how"

AGENTS.md is the file that defines "what agents are permitted to do and what they must not do."

# AGENTS.md

## このリポジトリで動くエージェントの行動規範

### 禁止事項
- 本番 DB への直接接続
- `git push --force` の使用
- API キーや secret のコード内ハードコード
- `npm install` 時の `--ignore-minimum-release-age` 使用

### コミット・PR ルール
- ブランチ命名: feat/, fix/, refactor/, docs/
- コミットメッセージは prefix(scope): subject 形式
- 1 PR は 400 行以内、超える場合は分割

### ツール使用方針
- ファイル検索は `rg` を優先、`grep -r` は使わない
- パッケージマネージャは pnpm 11 系、npm は使わない
- TypeScript は strict モード必須

SKILL.md — "Procedural runbooks for specific tasks"

SKILL.md gathers "concrete procedures for performing this specific category of work." Multiple files can be placed.

# SKILL.md（マイグレーション作業）

## DB マイグレーション手順

1. `migrations/` 配下に YYYYMMDDHHMM_description.sql を作成
2. up / down の両方を必ず書く
3. 本番適用前に staging で 24 時間検証
4. 適用後は `migrations/applied.log` に記録

## 影響範囲の調べ方

- 該当テーブルを参照しているファイルを `rg "table_name"` で検出
- ORM の型生成スクリプトを再実行

DESIGN.md — "Why decisions were made"

DESIGN.md is the file that documents "architectural decisions and their rationale." It serves a role akin to an aggregate of Architecture Decision Records (ADRs).

# DESIGN.md

## アーキテクチャ概要

[システム構成図]

## 主要判断

### Astro を採用した理由
- SSG 中心、JavaScript 最小化が要件
- WordPress GraphQL 連携が容易

### Cloud Storage ホスティングを選んだ理由
- Vercel 等は不要、SSG で完結
- gsutil rsync で十分なデプロイ性能

This template puts into concrete form the philosophy of "document separation for AI-driven development" covered in Specifications / Context / Harnesses / Requirements, offering a shared design that custom development agencies can leverage across clients.

Templates to build for custom development — Reusable boilerplates across clients

Here is a common boilerplate for rolling out instructions across multiple customer projects in custom development.

[受託標準テンプレ（社内 git template）]
.
├── AGENTS.md           ← 受託共通ルール（禁止事項・コミット規約）
├── DESIGN.md           ← 顧客プロジェクト固有（最初は雛形）
├── skills/
│   ├── SKILL.md        ← 一般的開発スキル
│   ├── SKILL-db.md     ← DB 関連
│   ├── SKILL-deploy.md ← デプロイ手順
│   └── SKILL-review.md ← レビュー手順
└── .claude/
    └── settings.json   ← Claude Code 設定

The core insight is separating them such that "AGENTS.md is common across client projects, while DESIGN.md is customer-specific." This allows agency-wide quality standards to be propagated across all projects through updates to AGENTS.md.

The "30-minute template" for launching client projects

Here is the standard workflow to stand up AI instructions in 30 minutes during kickoff for new custom development engagements.

[Step 1: 5 分] 受託標準テンプレを clone
  └ git clone <internal-template-url> <project>

[Step 2: 5 分] AGENTS.md は無編集（受託共通として使う）
  └ プロジェクト固有の禁止事項のみ追記

[Step 3: 15 分] DESIGN.md の雛形を顧客と埋める
  ├ システム概要
  ├ 主要技術スタック
  ├ 既知の制約（顧客社内ルール）
  └ 連絡ルート

[Step 4: 5 分] SKILL.md の雛形を選択
  ├ 必要な SKILL を skills/ から選び、不要なものを削除
  └ 顧客ドメイン特有のスキルがあれば追加 SKILL を作成

The ability to "complete the onboarding of AI-driven development in 30 minutes" directly enhances agency productivity. A process that previously took 1–2 days to draft custom CLAUDE.md files can be dramatically shortened through templating.

Measuring the impact of role separation — Saving context window length

Here is an example demonstrating how context window consumption changes when splitting into three files.

Structuring instructions to "load SKILL files only when needed" preserves context window headroom and improves comprehension accuracy across the codebase. Half the cases where "the AI keeps repeating the same mistake" in client engagements stem from context exhaustion.

This is an empirical demonstration of the principle that "context efficiency determines cost" covered in Optimizing Claude Code Operational Costs, proving that splitting files is an architecture that directly impacts costs.

Turning SKILL.md into a "reusable catalog"

For agencies managing multiple engagements, organizing SKILL.md into a reusable catalog dramatically reduces onboarding costs.

By gathering these in an internal Git template repository, new projects can assemble their AI instructions simply by "composing modules from the catalog."

Best practices for customer "DESIGN.md handovers"

When a custom development contract concludes, shaping DESIGN.md into a format that the customer can take over and operate is the defining factor in delivery quality.

Deliverables should aim for a state where "successors can seamlessly take over the project simply by reading DESIGN.md." This theme should be treated as one with the "delivery in a form the customer can operate" covered in contracted maintenance for Vercel Open Agents.

Five pitfalls easy to stumble into in custom development

Pitfall 1: Making AGENTS.md customer-specific

Writing customer-specific rules into AGENTS.md prevents updating agency-wide quality standards in bulk; customer-specific details should always reside in DESIGN.md.

Pitfall 2: SKILL.md exceeding 1,000 lines

When a SKILL file is too long, the AI loses track of key points. Aim to break files down keeping "each SKILL under 200 lines."

Pitfall 3: Updates to DESIGN.md stall

Unless an ADR-writing culture takes root, DESIGN.md ends up trapped as an "initial setup snapshot." Enforce "checking whether DESIGN.md was updated during PR reviews" through CI.

Pitfall 4: The customer does not know SKILL.md exists

If SKILL.md is not introduced during handover, the customer cannot incorporate it into operations and it falls into disuse. Always include a "SKILL.md catalog list + usage instructions" in handover documentation.

Pitfall 5: AI continues reading an outdated AGENTS.md

When updates fail to reflect, Claude Code / Cursor caches may still be persisting. Establish an operational rule to "notify the team to /clear whenever AGENTS.md is updated."

Summary — "AI instruction standardization" is the productivity index for custom development

Role separation among AGENTS.md, SKILL.md, and DESIGN.md may seem like a minor adjustment in a single project, but it serves as a standardization foundation that lifts productivity across the entire custom development organization. Achieving a state where "onboarding AI-driven development completes in 30 minutes across every project" creates a substantial margin in profitability six months down the line.

If you want to standardize AI-driven development across your engineering organization or find that AI operational quality is inconsistent across client engagements, please feel free to reach out via our contact form.

Sources

• Role Separation for AI Instruction Files: AGENTS.md, SKILL.md, DESIGN.md, and the Current State of Specification-Driven Development (Zenn)
• Claude Code Official Documentation — Project Settings
• Cursor — Project Rules and Instructions