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

Lee el formato existente de agent-instructions y la guía de autoría de skills, y compáralos con la estructura descrita de instructions/.instructions.md y .ai/**/.md. Revisa cómo el frontmatter YAML de los skills y el motor de composición gestionan actualmente las dependencias de contexto. Se considera terminado cuando la arquitectura por capas y los patrones de skills procedurales estén documentados y cualquier cambio necesario en el esquema required_reading esté especificado claramente.

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.