name: ai-instruction-standards
scope: partial
description: |
Create and maintain AI instruction files (CLAUDE.md, .cursorrules, etc.) with proper structure.
Use when: creating AI instruction files, separating universal vs project-specific rules, configuring AI tools.
Keywords: CLAUDE.md, cursorrules, windsurfrules, clinerules, AI instructions, system prompt, 指令檔案, AI 設定.

AI Instruction File Standards Guide

Language: English | 繁體中文

Version: 1.0.0
Last Updated: 2026-01-25
Applicability: Claude Code Skills

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

Purpose

This skill helps create and maintain AI instruction files with proper separation between universal standards and project-specific configurations.

Quick Reference

Supported AI Tools

Core Principle: Universal vs Project-Specific

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]

Detailed Guidelines

For complete standards, see:
- AI Instruction File Standards

AI-Optimized Format (Token-Efficient)

For AI assistants, use the YAML format file for reduced token usage:
- Base standard: ai/standards/ai-instruction-standards.ai.yaml

Content Guidelines

Universal Content (Keep Generic)

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

Labeling Convention

Option A: Section Headers

## Universal Standards
[universal content]

## Project-Specific Configuration
[project-specific content]

Option B: Inline Markers

> ⚠️ **Project-Specific**: This section contains configuration unique to this project.

### Tech Stack
...

Option C: Comment Annotations

<!-- UNIVERSAL: The following applies to all projects -->
### Commit Message Format
...

<!-- PROJECT-SPECIFIC: Customize for your project -->
### Quick Commands
...

Multi-Tool Configuration

When using multiple AI tools, maintain consistency:

project/
├── CLAUDE.md              # Claude Code instructions
├── .cursorrules           # Cursor instructions (can import from CLAUDE.md)
├── .windsurfrules         # Windsurf instructions
└── .github/
    └── copilot-instructions.md  # Copilot instructions

Best Practice: Create a shared docs/ai-standards.md and reference it from each tool's file to avoid duplication.

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

Configuration Detection

This skill supports project-specific configuration.

Detection Order

1. Check for existing CLAUDE.md or equivalent files
2. Analyze content structure for universal/project-specific separation
3. 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. Would you like to create one?"
2. Determine project type and tech stack
3. Generate template with appropriate sections
4. Add to .gitignore if contains sensitive info

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

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards