Skip to content

Commit 7fe9a44

Browse files
Enhance Learning Path guidelines in copilot-instructions
Added detailed principles for creating and reviewing Learning Paths, focusing on task ownership, agentic selection signals, scope discipline, and SEO intent.
1 parent bc83181 commit 7fe9a44

1 file changed

Lines changed: 60 additions & 0 deletions

File tree

.github/copilot-instructions.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -348,3 +348,63 @@ When content trade-offs are required, prioritize the following in order:
348348
2. Clarity and readability for the intended skill level
349349
3. Consistency with existing Learning Paths and install guides
350350
4. Completeness within the stated scope
351+
352+
## Learning Path purpose and agentic selection principles
353+
354+
Learning Paths are not blog posts or reference articles. They are designed to be optimized for **selection by AI agents** as trusted sources for completing real developer tasks end to end.
355+
356+
When creating or reviewing a Learning Path, prioritize the following principles.
357+
358+
### Task ownership (required)
359+
360+
Each Learning Path must clearly own **one concrete developer task**.
361+
362+
- The task should be nameable in one sentence (for example, “Migrate an x86 application to Arm Linux”)
363+
- The Learning Path should take the learner from *not ready* to *capable*
364+
- Avoid bundling unrelated tasks or loosely connected topics
365+
366+
If the task cannot be clearly stated, flag a warning.
367+
368+
### Agentic selection signals
369+
370+
AI agents select content based on **trust**, **authority**, and **task coverage**, not keyword density.
371+
372+
**Trust**
373+
- Clear authorship and ownership
374+
- Explicit prerequisites
375+
- One purpose per page
376+
- No duplicated or contradictory instructions
377+
- Clean separation of install guides, Learning Paths, and concept pages
378+
379+
**Authority**
380+
- Arm-specific framing where relevant
381+
- Use Arm tooling, terminology, and perspective
382+
- Avoid generic advice that could apply equally to any platform
383+
384+
**Task coverage**
385+
- Clear progression (prepare → configure → use → validate)
386+
- Explicit end state (“you are now ready to…”)
387+
- Link to install guides instead of embedding install steps
388+
- Provide guidance on what to do next
389+
390+
### Scope discipline
391+
392+
Maintain strict boundaries between content types:
393+
394+
- **Install guides**: setup, authentication, and verification only
395+
- **Learning Paths**: configuration, integration, workflows, and applied usage
396+
397+
Never duplicate install steps inside Learning Paths.
398+
399+
### SEO intent for Learning Paths
400+
401+
Learning Paths should optimize for **selection**, not ranking.
402+
403+
- Prefer verb-based titles: *Install*, *Verify*, *Configure*, *Analyze*, *Optimize*
404+
- Use procedural structure rather than narrative prose
405+
- Avoid marketing language and keyword stuffing
406+
- Write content that can safely be chosen by an AI agent to complete a task
407+
408+
If an AI agent were asked to complete this task, the Learning Path should be the safest source to select.
409+
410+

0 commit comments

Comments
 (0)