From 01e29f6fd547f3cb34f96ca1abb32eb18fafec32 Mon Sep 17 00:00:00 2001 From: anupras-mohapatra-arm Date: Thu, 2 Jul 2026 09:32:13 -0500 Subject: [PATCH 1/6] adding section for skill usage to writing style page --- .../appendix-2-writing-style.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) 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..5f5d448c72 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,27 @@ 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 these guidelines. +Agent Skills are located in the project reporsitory at `.github/skills`, and. Skills cover Learning Path structure, writing style guidelines, as well as accessibility-related considerations such as alt-text for images. +Skills are invoked automatically depending on your prompts. For example, to check for style violations on a given page, you can prompt: +```text +Review this page for style violations. +``` + +To check whether the Learning Path is structurally sound, you can prompt: + +```text +Review this Learning Path for structure. +``` + +You can explore other skills in the skills directory and tailor prompts based on the `description` metadata for AI-assisted authoring that's consistent with other Learning Paths. From aa293bce1962edd2c543e1ef81d9ef8f40aaa08c Mon Sep 17 00:00:00 2001 From: anupras-mohapatra-arm Date: Thu, 2 Jul 2026 09:49:59 -0500 Subject: [PATCH 2/6] nit --- .../_example-learning-path/appendix-2-writing-style.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 5f5d448c72..cf4065eec1 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 @@ -202,15 +202,15 @@ Learning Paths are intended for software developers with differing experience le 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 these guidelines. -Agent Skills are located in the project reporsitory at `.github/skills`, and. Skills cover Learning Path structure, writing style guidelines, as well as accessibility-related considerations such as alt-text for images. +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. -Skills are invoked automatically depending on your prompts. For example, to check for style violations on a given page, you can prompt: +Skills are invoked automatically depending on your prompts. For example, to check for style violations on a given page, you can prompt something similar to: ```text Review this page for style violations. ``` -To check whether the Learning Path is structurally sound, you can prompt: +To check whether the Learning Path is structurally sound, you can prompt something similar to: ```text Review this Learning Path for structure. From 31e1524af667f2d14d037cef41d156c6563a492f Mon Sep 17 00:00:00 2001 From: anupras-mohapatra-arm Date: Thu, 2 Jul 2026 10:22:38 -0500 Subject: [PATCH 3/6] clarifying skill invocation --- .../_example-learning-path/appendix-2-writing-style.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) 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 cf4065eec1..81358063da 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 @@ -200,15 +200,16 @@ Learning Paths are intended for software developers with differing experience le ## 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 these guidelines. +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. -Skills are invoked automatically depending on your prompts. For example, to check for style violations on a given page, you can prompt something similar to: +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 for style violations. +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: @@ -216,4 +217,4 @@ To check whether the Learning Path is structurally sound, you can prompt somethi Review this Learning Path for structure. ``` -You can explore other skills in the skills directory and tailor prompts based on the `description` metadata for AI-assisted authoring that's consistent with other Learning Paths. +By using words such as "Learning Path" and "structure", the prompt invokes the `learning-path-structure-review` skill. The AI assistant returns with suggestions focused on whether each page is task oriented and the Learning Path has necessary files and sections. From 7f6d544448df300ef558e5d91859d5992e00f6c8 Mon Sep 17 00:00:00 2001 From: anupras-mohapatra-arm Date: Thu, 2 Jul 2026 10:29:31 -0500 Subject: [PATCH 4/6] more clarification --- .../_example-learning-path/appendix-2-writing-style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 81358063da..e7fdb78c1f 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 @@ -217,4 +217,4 @@ To check whether the Learning Path is structurally sound, you can prompt somethi 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 focused on whether each page is task oriented and the Learning Path has necessary files and sections. +By using words such as "Learning Path" and "structure", the prompt invokes the `learning-path-structure-review` skill. The AI assistant returns with suggestions focused on whether each page is task oriented and whether the Learning Path has necessary files and sections. From befaa1e6b68db440e7e7b535fd473e54fa3380e1 Mon Sep 17 00:00:00 2001 From: anupras-mohapatra-arm Date: Thu, 2 Jul 2026 10:33:53 -0500 Subject: [PATCH 5/6] more clarification and minor skill tweak --- .github/skills/learning-path-structure-review/SKILL.md | 4 ++-- .../_example-learning-path/appendix-2-writing-style.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/skills/learning-path-structure-review/SKILL.md b/.github/skills/learning-path-structure-review/SKILL.md index 08b3aa94e4..46908b33e4 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 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. - 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 e7fdb78c1f..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 @@ -217,4 +217,4 @@ To check whether the Learning Path is structurally sound, you can prompt somethi 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 focused on whether each page is task oriented and whether the Learning Path has necessary files and sections. +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. From 2a6ce7d1ad38a04a0c7b085799eb4728dc624d4f Mon Sep 17 00:00:00 2001 From: anupras-mohapatra-arm Date: Thu, 2 Jul 2026 10:38:50 -0500 Subject: [PATCH 6/6] scenario-based skill tweak --- .github/skills/learning-path-structure-review/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/skills/learning-path-structure-review/SKILL.md b/.github/skills/learning-path-structure-review/SKILL.md index 46908b33e4..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/job-to-be-done. + - 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, with each section ideally focusing on one job-to-be-done. + - 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`: