[ { "id": "/skills/semantic-html/", "type": "skill", "title": "Semantic HTML", "url": "/skills/semantic-html/", "description": "Create accessible, semantic HTML for web content.", "category": "", "body": "Semantic HTML for accessible web content.", "extra": "{\"level\"=>1, \"text\"=>\"Uses basic semantic tags correctly (e.g., main, nav, article) instead of generic divs, and ensures images have appropriate alt attributes.\", \"associated_courses\"=>[\"course-accessible-html-foundations\"]} {\"level\"=>2, \"text\"=>\"Structures forms with proper labels, applies correct heading hierarchies (H1-H6), and understands when to use button vs. anchor tags for keyboard navigation.\", \"associated_courses\"=>[\"course-accessible-html-foundations\", \"course-wcag-review-workflow\"]} {\"level\"=>3, \"text\"=>\"Implements advanced WAI-ARIA roles, states, and properties where native HTML falls short, ensuring complex UI components (like modals or tabs) are screen-reader accessible.\", \"associated_courses\"=>[\"course-machine-readable-taxonomy\"]} {\"level\"=>4, \"text\"=>\"Audits existing codebases using automated tools (e.g., Axe, Lighthouse) and manual screen reader testing (NVDA, VoiceOver) to identify and remediate WCAG compliance failures.\", \"associated_courses\"=>[\"course-machine-readable-taxonomy\"]} {\"level\"=>5, \"text\"=>\"Establishes organization-wide accessibility guidelines, authors reusable accessible component libraries, and mentors engineering teams on inclusive design patterns.\"}" } , { "id": "/skills/taxonomy-design/", "type": "skill", "title": "Taxonomy Design", "url": "/skills/taxonomy-design/", "description": "Model related concepts into stable machine-readable structures.", "category": "", "body": "Taxonomy design for stable machine-readable skill structures.", "extra": "{\"level\"=>2, \"text\"=>\"Applies established tags, categories, and metadata schemas consistently to content, and identifies basic relationships between existing terms.\"} {\"level\"=>3, \"text\"=>\"Creates and maintains simple flat or hierarchical vocabularies for specific content types, ensuring terms are clear, mutually exclusive, and unambiguous.\", \"associated_courses\"=>[\"course-machine-readable-taxonomy\"]} {\"level\"=>4, \"text\"=>\"Designs faceted taxonomies and controlled vocabularies based on user research and search log analysis, establishing clear parent-child relationships and synonyms (variant terms).\"} {\"level\"=>5, \"text\"=>\"Develops comprehensive taxonomy governance policies, bridges disparate metadata structures across different systems, and conducts card-sorting or tree-testing to validate structures.\"} {\"level\"=>6, \"text\"=>\"Architects enterprise-wide knowledge graphs and complex ontologies, integrates semantic web standards (SKOS, OWL), and aligns taxonomy strategy with machine learning and AI discovery systems.\"}" } , { "id": "/courses/accessible-html-foundations/", "type": "course", "title": "Accessible HTML Foundations", "url": "/courses/accessible-html-foundations/", "description": "Introductory course covering semantic HTML, labels, and keyboard access.", "provider": "", "body": "Introductory course covering semantic HTML, labels, and keyboard access.", "extra": "" } , { "id": "/courses/machine-readable-taxonomy/", "type": "course", "title": "Machine-Readable Taxonomy Design", "url": "/courses/machine-readable-taxonomy/", "description": "Course on structuring domain concepts into stable data models.", "provider": "", "body": "Course on structuring domain concepts into stable data models.", "extra": "" } , { "id": "/courses/wcag-review-workflow/", "type": "course", "title": "WCAG Review Workflow", "url": "/courses/wcag-review-workflow/", "description": "Practical course for reviewing UI markup against WCAG 2.2 AA checks.", "provider": "", "body": "Practical course for reviewing UI markup against WCAG 2.2 AA checks.", "extra": "" } , { "id": "/docs/about-levels/", "type": "doc", "title": "About the levels", "url": "/docs/about-levels/", "description": "What the level numbers mean", "body": "The levels in this framework are based on those in the SfIA framework. Each level describes how much responsibility, independence and influence a person has: Level 1: Awareness Understands the concept and basic terminology Level 2: Basic application Applies the skill with guidance in simple situations Level 3: Working practice Performs the skill independently in routine work Level 4: Advanced practice Adapts the skill to varied situations and constraints Level 5: Expert practice Leads complex application of the skill across teams or systems Level 6: Strategic influence Shapes how the skill is used across an organization Level 7: Transformational leadership Defines direction and drives major change at the highest level", "extra": "" } , { "id": "/docs/agent-prompts/", "type": "doc", "title": "Prompts for AI Agents", "url": "/docs/agent-prompts/", "description": "How to prompt your AI agent to help you add skills and courses", "body": "Either talk to your developer, or follow the instructions at Introduction for site developers in order to get a copy of the site that you can work on. Interactive prompt: add a skill with associated data Add a new skill to this skills framework and include all associated data. Work in two phases. Phase 1: Interactive intake (no file edits yet) Ask me for all required inputs (skill basics, category, level descriptors, associated courses, metadata), then wait for my answers. Summarize captured inputs and ask for confirmation. Phase 2: Apply changes after confirmation - Update `_data/skills.yml` - Add category in `_data/categories.yml` if needed - Update `_data/level_descriptors.yml` - Update `_data/courses.yml` for linked courses - Create `collections/_skills/<slug>.md` - Create any needed `collections/_courses/<slug>.md` - Validate links and refs across files - Run `./scripts/validate_metadata.sh` Output: - Files changed - Validation result Interactive prompt: add a course with associated links Add a new course to this skills framework and wire it to the correct skill level descriptors. Work in two phases. Phase 1: Interactive intake (no file edits yet) Ask me for course details, slug/URL, linked skill refs, target level numbers, descriptor strategy (reuse/new), and metadata. Summarize captured inputs and ask for confirmation. Phase 2: Apply changes after confirmation - Update `_data/courses.yml` - Update `_data/level_descriptors.yml` to include the course in associated courses - Create `collections/_courses/<slug>.md` - Create descriptors only if required - Validate references and URLs - Run `./scripts/validate_metadata.sh` Output: - Files changed - Validation result", "extra": "" } , { "id": "/docs/content-configuration/", "type": "doc", "title": "Branding and site setup", "url": "/docs/content-configuration/", "description": "", "body": "This project uses a whole-site configuration data file, stored in _data/content.yml. This file contains instructions for branding and for metadata defaults. Note: If you know Jekyll, you know that normally these site-wide configurations are stored in _config.yml. I have decided to keep _config.yml only for developers who know what their doing. Whereas content.yml can be changed relatively safely by non-developers. What does the file control? Home page text snippets (for example home_text) Branding: site name tag line primary/secondary/accent colors link colors (link_color, link_hover_color, link_visited_color) font family Organization details: name URL logo path SEO defaults: default description default image twitter card type Why it matters Values from _data/content.yml are used by templates and metadata includes, including: _includes/head.html _includes/navigation.html _includes/footer.html Keeping this file accurate ensures consistent branding and high-quality metadata across the entire site. Branding colors must also remain accessible: configured text/link colors are validated against a white background using WCAG 2.2 AA contrast thresholds. Recommended update process Edit _data/content.yml. Build locally: bundle exec jekyll build Run metadata validation: ./scripts/validate_metadata.sh If you changed colors, ensure the script passes color contrast checks for: branding.primary_color branding.accent_color branding.link_color branding.link_hover_color branding.link_visited_color branding.secondary_color", "extra": "" } , { "id": "/docs/github-pages-deployment/", "type": "doc", "title": "Deploying on Github pages", "url": "/docs/github-pages-deployment/", "description": "How to make your site available to the public on Github Pages", "body": "Note: Github Pages is currently free, and has been for years. Of course, that may change… Step 1: Configure _config.yml Within _config.yml set: url: your GitHub Pages domain baseurl: \"\" for user/organization sites \"/<repo>\" for project sites Step 2: Enable Pages with actions Commit and push the workflow file. In GitHub, open Settings > Pages. Set Source to GitHub Actions. Step 3: Push your code to Github Push to main Check that the included workflow has completed properly in Github’s Actions tab. Note: If you need to make changes to the workflow, you will find it here: .github/workflows/deploy-pages.yml", "extra": "" } , { "id": "/docs/how-to-add-edit-categories/", "type": "doc", "title": "How to add/edit a skills category", "url": "/docs/how-to-add-edit-categories/", "description": "", "body": "Either talk to your developer, or follow the instructions at Introduction for site developers in order to get a copy of the site that you can work on. AI-assisted approach If you use an AI coding tool, you can ask it to review this site and to add the categories you need. Manual approach Find the _data/categories.yml file. This contains the categories into which the skills are organised. Each category is described by a YAML list item containing a dictionary of keys and their values. Add categories at the bottom of this file by copying an existing category, or delete the lines containing categories you no longer need. If you edit the category_ref key value, then make you change that value wherever it’s mentioned in the skills files. Category keys reference Key Purpose category_ref a unique ID for the category. This field is referred to by the skills themselves. Make sure they match up with what you use in the skills. name a human-readable name description a short description to be shown to the website users Sample categories YAML file - category_ref: accessibility name: Accessibility description: Designing and reviewing interfaces for inclusive use. - category_ref: data-modeling name: Data Modeling description: Structuring domain data for reuse and interoperability. Warning: Do not change any of the field names, like description. If you do, the data in this field may not be shown on the published site.", "extra": "" } , { "id": "/docs/how-to-add-edit-courses/", "type": "doc", "title": "How to add/edit courses", "url": "/docs/how-to-add-edit-courses/", "description": "", "body": "Either talk to your developer, or follow the instructions at Introduction for site developers in order to get a copy of the site that you can work on. AI-assisted approach If you use an AI coding tool, you can ask it to review this site and to add the courses you need, with appropriate connections to the skills. Manual approach Find the courses in collections/_courses/. Each course has its own file, each containing two parts: the frontmatter (between --- markers), the content (below the second --- marker). The frontmatter helps to keep things organised. The content is anything that helps fill out the description of the course. Like the categories, the frontmatter contains a list of key / value pairs. Either edit a file, or create a new one, ensuring the frontmatter exists correctly. Edit the related skills to include any new course references as required. Courses keys reference Key Description course_ref A unique reference ID title The name of the course description A short description of the course image The location of an optional image used when sharing on social media provider The name of the course provider. Make sure this remains consistent between courses from the same organisation. external_url The web address for the course on the provider’s website Sample course frontmatter --- course_ref: course-my-course title: My Course description: Short summary for metadata and previews. image: provider: SkillPath Academy url: /courses/accessible-html-foundations/ external_url: https://example.com/courses/accessible-html-foundations ---", "extra": "" } , { "id": "/docs/how-to-add-edit-glossary-items/", "type": "doc", "title": "How to add/edit glossary items", "url": "/docs/how-to-add-edit-glossary-items/", "description": "", "body": "Either talk to your developer, or follow the instructions at Introduction for site developers in order to get a copy of the site that you can work on. AI-assisted approach If you use an AI coding tool, you can ask it to review this site and to add the items you need. Manual approach Find the list of glossary entries in: _data/glossary.csv Edit or add entries as required - making sure that the definitions are surrounded by quotes The first time a glossary entry appears on a page (outside of a heading), it will be highlighted with a link. Users can click on it to open the definition.", "extra": "" } , { "id": "/docs/how-to-add-edit-skills/", "type": "doc", "title": "How to add/edit skills", "url": "/docs/how-to-add-edit-skills/", "description": "", "body": "Either talk to your developer, or follow the instructions at Introduction for site developers in order to get a copy of the site that you can work on. AI-assisted approach If you use an AI coding tool, you can ask it to review this site and to add the skills you need, with appropriate level descriptors. Manual approach Find the skills in the collections/_skills/ directory. Each skill has its own file, each containing two parts: the frontmatter (between --- markers), and the content (below the second --- marker). The frontmatter helps to keep things organised. The content is anything that helps fill out the description of the skill. Like the categories, the frontmatter contains a list of key / value pairs. Either edit a file, or create a new one, ensuring the frontmatter exists correctly. Add any related courses as separate files. Ensure the course references are correct inside the level descriptors. Skills keys reference Key Description skill_ref A unique reference ID title The human-readable name of the skill category_ref The reference ID of the skill’s category. This is the connection between skills and categories. description A short description of the skill as a whole image The location of an image, if you want one, that will show when sharing on social media level_descriptors A YAML list of of the levels for this skill, and the text that goes with that level. Note how the list is formatted in the sample below. level_descriptors / level The level number level_descriptors / text Description of the skill at this level level_descriptors / associated_courses A comma-separated array of course references. Note the square brackets around the array, and the quotes around each reference Don’t forget to add the course file before adding links to it in a skill. Sample skill frontmatter --- skill_ref: semantic-html title: Semantic HTML category_ref: accessibility layout: skill description: Create accessible, semantic HTML for web content. image: level_descriptors: - level: 1 text: \"Uses basic semantic tags correctly (e.g., main, nav, article) instead of generic divs, and ensures images have appropriate alt attributes.\" associated_courses: [\"course-accessible-html-foundations\"] - level: 2 text: \"Structures forms with proper labels, applies correct heading hierarchies (H1-H6), and understands when to use button vs. anchor tags for keyboard navigation.\" associated_courses: [\"course-accessible-html-foundations\", \"course-wcag-review-workflow\"] - level: 3 text: \"Implements advanced WAI-ARIA roles, states, and properties where native HTML falls short, ensuring complex UI components (like modals or tabs) are screen-reader accessible.\" associated_courses: [\"course-machine-readable-taxonomy\"] - level: 4 text: \"Audits existing codebases using automated tools (e.g., Axe, Lighthouse) and manual screen reader testing (NVDA, VoiceOver) to identify and remediate WCAG compliance failures.\" associated_courses: [\"course-machine-readable-taxonomy\"] - level: 5 text: \"Establishes organization-wide accessibility guidelines, authors reusable accessible component libraries, and mentors engineering teams on inclusive design patterns.\" ---", "extra": "" } , { "id": "/docs/how-to-use-site/", "type": "doc", "title": "How to use this site", "url": "/docs/how-to-use-site/", "description": "", "body": "The published website produced by this template framework is designed to allow both humans and machines (AI agents particularly) to read and navigate the skills. Structure The skills are placed into categories. Each category can hold as many skills as you wish, but we recommend no more than 10 in each. A skill has a title, a reference code and then up to seven level descriptors. This approach is based on the same model as has been successfully used by the SfIA skills framework for the past 20 years. I recommend that you review how the SfIA framework operates - particularly the concept of “levels of responsibility” before starting to work on your own framework. I have provided the ability to add references to courses. These are linked to specific levels within a skill, so that users can find courses to help them to attain that level. How humans will use the site The site can be browsed directly, or users can search for specific terms. Key pages: Skills Courses Search Documentation For machines and AI agents All the skills and courses are designed to be consumed easily by machines. The site includes special features to enable machines to walk through and gather the information: Stable URLs for skill and course pages Canonical, Twitter, OpenGraph and JSON-LD metadata Machine-readable endpoints: /skills.json /courses.json /search-index.json Discoverability files: /llms.txt /robots.txt /sitemap.xml You don’t need to worry about these. They are all generated automatically, and agents will know what to do with them.", "extra": "" } , { "id": "/docs/", "type": "doc", "title": "Documentation", "url": "/docs/", "description": "", "body": "This site is built using Jekyll, a static site generator. It is designed to provide a framework to help you create and publish your own skills framework. Jekyll allows you to manage your content separately from the design and structure of the website. Use the menu on this page to get started. If you have any questions or suggestions for improvement, please raise them on Github License This product has an MIT license. Please make sure you review this to ensure it meets your needs.", "extra": "" } , { "id": "/docs/intro-site-developers/", "type": "doc", "title": "Introduction for site developers", "url": "/docs/intro-site-developers/", "description": "How to get started using the Jekyll site-generation platform", "body": "These instructions are designed for non-developers to get this website running on your machine, ready for you to edit the content. You will be using a coding environment called Visual Studio Code or VS Code for short. Alongside that, you will be using a program called Docker. This allows the Jekyll system to run inside a container exactly as it does on my machine, without affecting anything on the rest of your computer. The first part of these instructions is about getting this environment working. The second part is about how to download and setup the skills framework website within the environment. Step 1: Install the free tools you need Download VS Code: * Go to code.visualstudio.com and download the version for your computer (Windows or Mac). Run the VS Code installer and use the default settings. This is the visual editor where you will view your website files. Download Docker Desktop: * Go to docker.com/products/docker-desktop and download it. Run the installer. If it asks you to restart your computer during or after installation, go ahead and do so. Crucial Step: Once installed, open the Docker Desktop application. It needs to be actively running in the background for this to work. Step 2: Set up VS code for containers Now, we need to give VS Code the ability to read the devcontainer configuration files that come with this website. Open VS Code. On the far left sidebar, click on the icon that looks like four squares (the Extensions marketplace). In the search bar at the top, type Dev Containers. Find the extension made by Microsoft and click the blue Install button. Step 3: Create your own fork of this website There are two ways of making a copy of a git repository. One is ‘cloning’. You use this when you always want to have the most up-to-date version of whatever the development team has produced, and maybe even contribute back to the main repository at some point. The other is ‘forking’. You use a fork when you want your own copy of the repository, to make it into something that will be completely independent of the main repository. Think of it like taking a master template and making a complete, independent copy of it under your own GitHub account. This way, you can change anything you want without accidentally breaking the original template. You will need a fork of this website. Open your web browser and go to the original project link: github.com/berthelemy/skills-framework. Look at the very top-right corner of the webpage. You will see a button labeled Fork (it usually has an icon that looks like a split path). Click it. On the next screen, GitHub will ask where you want to fork it. Select your own personal GitHub account (or an organisational account if you have one). Note: If you don’t yet have a Github account, please create one. Leave the settings as they are (you can keep the name skills-framework) and click the green Create fork button at the bottom. After a few seconds, GitHub will redirect you to your new personal copy. You will know it worked because the top-left of the page will now say [Your-Username]/skills-framework, and right below it, it will say “forked from berthelemy/skills-framework”. Step 4: Copy your new repository link Now that you have your own copy, you need to copy its link — not the original one. On your new personal GitHub page, click the green Code button. Make sure the HTTPS tab is selected. Click the Copy icon (the two overlapping squares) to copy your personal link to your clipboard. Step 5: Clone your fork into VS Code Open VS Code on your computer. Click on View in the top menu, select Command Palette…, type Git: Clone, and press Enter. Paste the link you just copied into the top bar and press Enter. Choose a folder on your computer where you want to save this website (like your Documents folder) and click Select Repository Location. When the pop-up appears in the bottom-right corner asking if you want to open the cloned repository, click Open. Step 4: Fire up the devcontainer As soon as the project opens, VS Code will detect its devcontainer files. Look for the pop-up in the bottom-right corner that says “Folder contains a Dev Container configuration file.” Click Reopen in Container. Wait a few minutes for Docker to build your environment. Once it is loaded, open a new terminal (Terminal > New Terminal) and type: bundle exec jekyll serve Click the http://127.0.0.1:4000/ link that appears in your terminal to view your personal version of the Skills Framework! Whenever you make changes and “Push” them using the version control steps you will make them available in your repository. Note: This whole process might look really long-winded, but that’s only because it’s written down. Once everything is installed, the next time you just have to open the project inside VS Code and you’ll be back to where you were. Step 5: Running the site locally You’ll want to be able to see how changes you make affect the site. To do this you need to get Jekyll to build the site and to run a small web server so you can view the site in your browser. In VS Code, go to the Terminal menu and click: New terminal A terminal space will open at the bottom of VS Code. Look for the prompt, which will say something like vscode ➜ /workspaces/skills-framework (main) $ At the prompt, type bundle exec jekyll serve and press Enter In your browser, go to http://127.0.0.1:4000/ and you should see an exact copy of this website, ready for you to work on. Any changes you make to the site in VS Code will automatically refresh and update in your browser. When you are done working, you can simply close VS Code and close Docker Desktop. Note: If you make any changes to _config.yml you will need to stop the web server (CTRL-C) and rebuild the site with bundle exec jekyll serve", "extra": "" } , { "id": "/docs/remove-alert/", "type": "doc", "title": "How to remove the information box", "url": "/docs/remove-alert/", "description": "", "body": "When you want to remove the information box at the top of the screen, there are two ways to do this: 1. Remove the ‘include’ command Find the file _layouts/default.html Within this file remove (or comment out) the line that says: {% include alert.html %} 2. Remove the alert code from the include Find the file _includes/alert.html Delete (or comment out) the contents of this file", "extra": "" } , { "id": "/docs/version-control/", "type": "doc", "title": "Version control", "url": "/docs/version-control/", "description": "How to keep a record of changes", "body": "When multiple people work on a website, or when you want to save your progress so you can undo mistakes later, you use Git. For a non-developer, think of Git like “Track Changes” in Microsoft Word, but for an entire folder of files. Instead of hitting “Save,” you create a permanent checkpoint called a Commit, and then you send those checkpoints to GitHub. Since you are using VS Code, you can do this using a visual menu—no coding required. The 3-Step routine for making changes Whenever you want to edit your website, follow this simple routine. 1. Get the latest updates (Pull) Before you start typing, you want to make sure you have any changes your teammates might have made while you were away. On the far-left sidebar of VS Code, click the Source Control icon (it looks like a little branch with three dots). Click the three dots (…) at the top of that side panel to open the menu. Click Pull. This downloads the latest version of the site to your computer. 2. Save your work permanently (Commit) Go ahead and edit your files (like updating a skill). When you are happy with your changes and want to save a checkpoint: Go back to the Source Control panel on the left. You will see a list of files you changed under the word “Changes”. Hover over the word “Changes” and click the plus sign (+) that appears. This “stages” your files, telling Git you want to save them. In the box that says Message, type a short note explaining what you did (e.g., Updated the April announcement blog post). Click the blue Commit button. Your checkpoint is now saved on your computer! 3. Share it with the world (Push) Right now, your changes are only saved on your personal computer. To send them to GitHub so everyone else can see them (and so the live website updates): Click the blue button that says Sync Changes (or Publish Branch). Alternatively, click those three dots (…) at the top of the panel again and click Push. 💡 Two golden rules for beginners Commit often: It is much better to make five small checkpoints (e.g., “Fixed typo”, “Added new image”, “Updated paragraph”) than one giant checkpoint at the end of the week. If you make a mistake, it’s much easier to undo a small step. Don’t panic if things break: Because you are using Git, nothing is permanent. If you accidentally delete a file or break the layout, you can always revert back to your last successful “Commit” checkpoint.", "extra": "" } ]