asiaostrich/ai-instruction-standards

AI Instruction File Standards Guide

Language: English | 繁體中文

Version: 2.0.0 Last Updated: 2026-04-28 Applicability: All AI coding tools

---

Core Standard: This skill implements AI Instruction File Standards. For comprehensive methodology documentation, refer to the core standard.

AI Skills Hierarchy | AI 技能層級

This skill is part of a three-layer AI collaboration system:

| Layer | Skill | Question it Answers | |-------|-------|-------------------| | Behavior (Immediate) | /ai-collaboration | "How should AI respond accurately?" | | Configuration (Session) | /ai-instruction-standards (this) | "What to write in CLAUDE.md / AGENTS.md?" | | Architecture (Long-term) | /ai-friendly-architecture | "How to structure code for AI?" |

Purpose

This skill helps create and maintain AI instruction files with proper separation between universal standards and project-specific configurations, across all major AI coding tools.

---

Quick Reference

Supported AI Tools (2026-04-28)

CLI / Agent Tools (Terminal)

| Tool | Primary File | Workflow Mechanism | MCP | |------|-------------|-------------------|-----| | Claude Code | CLAUDE.md + .claude/rules/*.md | Skills (.claude/skills/ → /{name}) | ✅ | | Gemini CLI | GEMINI.md | .gemini/commands/*.toml → /{name} | ✅ | | OpenAI Codex CLI | AGENTS.md (+ AGENTS.override.md) | Team commands; /review built-in | ✅ | | OpenCode | AGENTS.md (CLAUDE.md compatible) | Built-in only (/init /undo /share) | ✅ |

AI-native IDE / Editor Integration

| Tool | Primary File | Workflow Mechanism | MCP | |------|-------------|-------------------|-----| | Cursor | .cursor/rules/*.mdc ⚠️ | @-mentions; /multitask | ✅ | | GitHub Copilot | .github/copilot-instructions.md | .github/prompts/*.prompt.md → /{name} | ✅ | | Windsurf | .windsurfrules / .windsurf/rules/*.md | .windsurf/workflows/*.md → /{name} | ✅ | | Cline | .clinerules | None | ✅ |

⚠️ Cursor: .cursorrules is deprecated — migrate to .cursor/rules/*.mdc

---

Cross-Tool Universal Standard: AGENTS.md

AGENTS.md is the emerging de-facto cross-tool instruction standard:

Supported by: Gemini CLI, OpenAI Codex CLI, OpenCode, GitHub Copilot, Windsurf, Cursor Not supported by: Claude Code (uses CLAUDE.md), Cline (uses .clinerules)

Recommendation: Use AGENTS.md as the universal baseline for cross-tool projects, then add tool-specific files for advanced features (Skills, Workflows, Prompts).

---

Core Principle: Universal vs Project-Specific

| Type | Contains | Example | |------|----------|---------| | Universal | Generic rules | "Run tests before committing" | | Project-Specific | Concrete commands | "Run npm test before committing" |

---

Recommended Layout

# [Project Name] - AI Instructions

## Universal Standards
<!-- Rules applicable to ANY project -->
- Commit message format
- Code review checklist
- Testing standards
- Anti-hallucination rules

---

## Project-Specific Configuration
<!-- Unique to THIS project -->

### Tech Stack
[Your technologies here]

### Quick Commands
[Your build/test/deploy commands]

### File Structure
[Your project structure]

---

Tool-Specific Setup Guides

Claude Code

CLAUDE.md                        # Main instructions (hierarchical: global → project → subdir)
.claude/rules/                   # Glob-scoped additional rules
.claude/skills/{name}/SKILL.md   # Custom slash commands → /{name}
.claude/agents/{name}.md         # Subagent definitions

Gemini CLI

GEMINI.md                          # Main instructions
.gemini/commands/{name}.toml       # Custom slash commands → /{name}
.gemini/agents/{name}.yaml         # Subagent definitions

Example .gemini/commands/review.toml:

description = "Run code review checklist"
prompt = "Review the following changes: !{git diff HEAD}"

OpenAI Codex CLI

AGENTS.md                  # Main instructions (Git root → cwd traversal)
AGENTS.override.md         # Temporary override (highest priority)
~/.codex/AGENTS.md         # Global fallback
.codex/agents/             # Custom agent definitions

OpenCode

AGENTS.md                       # Primary (auto-recognized)
CLAUDE.md                       # Also recognized (migration compatibility)
.opencode/agents/               # Custom agent definitions
opencode.json (instructions)    # Glob-pattern file references

Cursor

.cursor/rules/                  # MDC format rules (replaces .cursorrules)
  {name}.mdc                    # Frontmatter: description, globs, alwaysApply
AGENTS.md                       # Also supported for agent context

MDC frontmatter example:

---
description: "TypeScript coding standards"
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

Migration: If you have .cursorrules, move content to .cursor/rules/*.mdc.

GitHub Copilot

.github/copilot-instructions.md         # Always-on, all chats
.github/instructions/*.instructions.md  # File-glob scoped (applyTo frontmatter)
.github/prompts/*.prompt.md             # Reusable templates → /{name} slash commands
.github/agents/*.agent.md               # Custom agents with tool access control
AGENTS.md                               # Also recognized

Windsurf

.windsurfrules                   # Project rules (team-shareable)
.windsurf/rules/*.md             # MDC frontmatter structured rules
.windsurf/workflows/*.md         # Reusable task sequences → /{name}
AGENTS.md                        # Also recognized

Workflow example (.windsurf/workflows/review.md):

Run a code review:
1. Run `git diff HEAD`
2. Check for BLOCKING issues (security, correctness)
3. Check for IMPORTANT issues (design, tests)
4. Output findings with BLOCKING/IMPORTANT/SUGGESTION prefixes

---

Multi-Tool Project Configuration

When a project uses multiple AI tools:

project/
├── AGENTS.md                            # Universal baseline (cross-tool)
├── CLAUDE.md                            # Claude Code (extends AGENTS.md)
├── GEMINI.md                            # Gemini CLI
├── .cursor/rules/
│   └── standards.mdc                    # Cursor
├── .windsurf/
│   └── workflows/                       # Windsurf workflows
│       ├── review.md
│       └── checkin.md
└── .github/
    ├── copilot-instructions.md          # Copilot always-on
    └── prompts/
        └── review.prompt.md             # Copilot slash command

Best Practice: Write universal content in AGENTS.md once, then import/reference it from tool-specific files to avoid duplication.

---

Content Guidelines

Universal Content (Keep Generic)

| Category | Good Examples | |----------|---------------| | Commit Standards | "Follow Conventional Commits format" | | Code Review | "Use BLOCKING, IMPORTANT, SUGGESTION prefixes" | | Testing | "Maintain 80% coverage minimum" | | AI Behavior | "Always read code before analyzing" |

Avoid in Universal Sections:

• Specific commands (npm test, pytest)
• Hardcoded paths (cli/src/, /var/www/)
• Version numbers (Node.js 18, Python 3.11)
• Project names and URLs

Project-Specific Content

| Category | Examples | |----------|----------| | Tech Stack | Node.js 18, React 18, PostgreSQL 15 | | Commands | npm run lint, ./scripts/deploy.sh | | File Structure | src/, cli/, tests/ | | Team Conventions | Traditional Chinese comments |

---

Maintenance Checklist

Before committing changes to AI instruction files:

• [ ] Universal sections contain no project-specific paths, commands, or versions
• [ ] Project-specific sections are clearly marked
• [ ] Cross-references to standards documents are correct
• [ ] Format matches existing sections
• [ ] If using Cursor: .cursorrules migrated to .cursor/rules/*.mdc
• [ ] If multi-tool project: AGENTS.md covers the universal baseline

---

Configuration Detection

Detection Order

1. Check for existing CLAUDE.md, AGENTS.md, GEMINI.md, or equivalent files
2. Detect which AI tools are in use (check for .cursor/, .windsurf/, .github/copilot-instructions.md, etc.)
3. Analyze content structure for universal/project-specific separation
4. If not found, suggest creating structured AI instruction file

First-Time Setup

If no AI instruction file found:

1. Ask: "This project doesn't have an AI instruction file. Which AI tools do you use?"
2. Recommend AGENTS.md for cross-tool projects, CLAUDE.md for Claude Code only
3. Determine project type and tech stack
4. Generate template with appropriate sections
5. Add to .gitignore if contains sensitive info

---

Next Steps Guidance

After /ai-instructions completes, suggest:

• Create or update project's CLAUDE.md / AGENTS.md ⭐ Recommended — Apply standards immediately
• Run /ai-friendly-architecture to optimize AI collaboration at the architecture level
• Run /ai-collaboration to review AI behavior guidelines

---

Related Standards

• AI Instruction File Standards - Core standard
• Documentation Writing Standards - Writing guidelines
• Anti-Hallucination Guidelines - AI accuracy rules
• AI-Friendly Architecture - Context optimization

---

Version History

| Version | Date | Changes | |---------|------|---------| | 2.0.0 | 2026-04-28 | Add Gemini CLI, OpenAI Codex CLI; update Cursor (MDC format, deprecated .cursorrules); update OpenCode (AGENTS.md primary); update Copilot (multiple file types); update Windsurf (Workflows); add AGENTS.md cross-tool standard section | | 1.0.0 | 2026-01-25 | Initial release |

---

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards