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

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.

Read the existing agent-instructions format and skill authoring guidance, then compare them with the described instructions/.instructions.md and .ai/**/.md structure. Review how skill YAML frontmatter and the composition engine currently handle context dependencies. Done means the layered architecture and procedural skill patterns are documented, with any required_reading schema change clearly specified.