diff --git a/.github/skills/learning-path-structure-review/SKILL.md b/.github/skills/learning-path-structure-review/SKILL.md index 08b3aa94e4..0398ab45d3 100644 --- a/.github/skills/learning-path-structure-review/SKILL.md +++ b/.github/skills/learning-path-structure-review/SKILL.md @@ -17,11 +17,11 @@ Use this skill when a Learning Path needs a structural review. Focus on whether - Additional resources and next steps live in `_index.md` `further_reading`, not in `_next-steps.md`. - `_next-steps.md` remains minimal and respects `FIXED, DO NOT MODIFY` template comments. 4. Review the instructional shape: - - The title and opening frame one developer task. + - The title and opening of the Learning Path frame one developer task/job-to-be-done. - The introduction gives context, user goal, and practical value. - Prerequisites are explicit and linked when useful. - Learning objectives are measurable, action-oriented, and limited to three or four bullets. - - Sections progress logically through prepare, configure, use, and validate phases. + - Sections progress logically through prepare, configure, use, and validate phases, with each section ideally focusing on one job-to-be-done. Flag nebulous sections with titles such as "working with x" or "managing y" that include multiple tasks that shouldn't be grouped together (e.g. creating and deleting a VM, or creating a VM and security group rules in the same section). - Validation steps prove the learner reached the promised outcome. - The conclusion or next-step guidance names what the learner can do next. 5. Review `further_reading`: diff --git a/content/learning-paths/cross-platform/_example-learning-path/appendix-2-writing-style.md b/content/learning-paths/cross-platform/_example-learning-path/appendix-2-writing-style.md index 869b549492..6a23ec0df3 100644 --- a/content/learning-paths/cross-platform/_example-learning-path/appendix-2-writing-style.md +++ b/content/learning-paths/cross-platform/_example-learning-path/appendix-2-writing-style.md @@ -193,12 +193,28 @@ Learning Paths are intended for software developers with differing experience le | Software Development Areas | Skills | |------------------------------------- |----------| -| Embedded and Microcontroller | Understanding of programming languages such as C, C++ and assembly. Basic awareness of Linux OS, RTOSes. Fundamental knowledge of hardware and software architecture (not necessarily Arm) | +| Embedded and Microcontroller | | | Server and Cloud | | | Mobile | | | Desktop and Laptop | | +## Use Agent Skills for AI-assisted style compliance +If you're creating a Learning Path with the help of an AI assistant, you can use Agent Skills to check whether your content meets project guidelines. +Agent Skills are located in the project reporsitory at `.github/skills`. Skills cover Learning Path structure, writing style guidelines, as well as accessibility-related considerations such as alt-text for images. +A skill is invoked automatically depending on whether your prompt maps to the skill's `description` metadata. For example, to check for style violations on a given page, you can prompt something similar to: +```text +Review this page in the Learning Path for style. +``` +By using words such as "Learning Path" and "style", the prompt invokes the `writing-style-review` skill. The AI assistant returns with a set of style-related suggestions. + +To check whether the Learning Path is structurally sound, you can prompt something similar to: + +```text +Review this Learning Path for structure. +``` + +By using words such as "Learning Path" and "structure", the prompt invokes the `learning-path-structure-review` skill. The AI assistant returns with suggestions such as whether the Learning Path is task-oriented and has necessary files and sections.