Incorporate layered instruction architecture and procedural skill patterns into agent-instructions format

Đọc định dạng agent-instructions hiện có và hướng dẫn viết skill, sau đó so sánh chúng với cấu trúc instructions/.instructions.md và .ai/**/.md được mô tả. Xem xét cách YAML frontmatter của skill và composition engine hiện xử lý các dependency của context. Được xem là hoàn tất khi kiến trúc phân lớp và các pattern skill mang tính thủ tục đã được ghi lại, đồng thời mọi thay đổi cần thiết đối với schema required_reading đã được đặc tả rõ ràng.

Source

Semantic extraction from Michal Pawlik's monorepo-template (permission granted). The repo demonstrates several AI workflow patterns worth incorporating into PromptKit's agent-instructions` format and skill authoring guidance.

Novel Patterns Identified

1. Layered Instruction Architecture

Separates AI agent instructions into three tiers:

• Routing layer (copilot-instructions.md): maps file paths to instruction sets via applyTo globs
• Entry points (instructions/*.instructions.md): thin files with key patterns + "Required Reading" pointers
• Rule corpus (.ai/**/*.md): deep, detailed, platform-agnostic rule documents

The .ai/ directory is the key insight: it's a standalone knowledge corpus not tied to any AI platform. Instruction files just point to it. Same rules work for Copilot, Claude Code, Cursor, or human developers.

Action: Document this as a recommended architecture in the agent-instructions format for projects with >5 rule documents. The current format produces flat instruction files; layered architecture scales better.

2. Procedural Skill Recipes

Skills follow a deterministic structure:

1. Required Reading - explicit list of rule docs the agent must read first (like #include)
2. Procedure - numbered steps with exact file paths, exact code templates, exact naming conventions
3. File Checklist - table of every file created/modified with action column
4. Error/Status Mapping - concrete reference tables (error type to HTTP status, etc.)

Action: Add a "Skill Authoring Best Practices" section to the agent-instructions format documenting this pattern. Skills should be procedural recipes with exact paths and code templates, not abstract guidance.

3. Required Reading as Context Dependencies

Both skills and instruction files declare "Required Reading" sections that list which rule documents must be loaded before the agent starts work. This acts as a dependency declaration for agent context.

Action: Consider adding a required_reading field to skill YAML frontmatter that the composition engine can use to auto-load dependencies.

What Was NOT Novel

The architectural content (CQRS, Result pattern, Inversify DI, Fastify/Prisma conventions) is well-written project-specific guidance, not generalizable for PromptKit. Good examples of what an .ai/ corpus looks like for a real project, but not reusable content.

Attribution

Michael Pawlik (GitHub: mpawlik) - permission granted for semantic extraction and incorporation.