Incorporate layered instruction architecture and procedural skill patterns into agent-instructions format
还没有人认领这个 Issue。
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 35/100
- Issue 类型
- 文档
- 描述清晰度
- 基本清楚
- 活跃度
- 冷清
调研方向
阅读现有的 agent-instructions 格式和 skill 编写指南，然后将其与所述的 instructions/.instructions.md 和 .ai/**/.md 结构进行比较。检查 skill YAML frontmatter 和 composition engine 当前如何处理上下文依赖。完成的标准是：分层架构和过程式 skill 模式已完成文档记录，并且任何所需的 required_reading schema 变更都已明确规定。
由索引模型根据 Issue 内容生成。
描述
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 viaapplyToglobs - 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:
- Required Reading - explicit list of rule docs the agent must read first (like
#include) - Procedure - numbered steps with exact file paths, exact code templates, exact naming conventions
- File Checklist - table of every file created/modified with action column
- 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.
- 主要语言
- JavaScript
- 星标
- 111
- 派生
- 24
- PR 合并指标
- 30 天内没有已合并 PR
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 没有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
microsoft/PromptKit 的其他 Issue
-
难度 5/5 一周以上 新手友好度 35/100
-
难度 5/5 一周以上 新手友好度 35/100
-
难度 5/5 一周以上 新手友好度 38/100
-
难度 5/5 一周以上 新手友好度 30/100
-
Investigate: structured feedback classification as a cross-cutting protocol可能重新可做 @abeltrano 于 193 天前认领，目前没有进行中的 PR。 未关闭enhancement
查看 microsoft/PromptKit 的全部 Issue
相似的 Issue
-
难度 2/5 1-3 小时 新手友好度 78/100
维护者通常 1 天内回复
-
难度 1/5 1 小时以内 新手友好度 85/100
-
[quality] Nothing keeps docs/skills/manifest.md in sync with docs/skills/*.md可能已有人在做 @hivecommons-hive 今天认领。 未关闭agent/quality hive/covered-by-pr hive/hosted-available-lke648397-260827-5n31 quality testing
难度 2/5 1-3 小时 新手友好度 78/100
维护者通常 1 天内回复
-
agent:blocked agent:ready
难度 2/5 1-3 小时 新手友好度 74/100
turbot/guardrails-fn#46 · 2 条评论 ·
维护者通常 1 天内回复
-
needs verification
难度 2/5 1-3 小时 新手友好度 65/100
维护者通常 6 天内回复