diff --git a/.agents/skills/create-lab-guide/SKILL.md b/.agents/skills/create-lab-guide/SKILL.md index 877c4e3f217a..047a5276d120 100644 --- a/.agents/skills/create-lab-guide/SKILL.md +++ b/.agents/skills/create-lab-guide/SKILL.md @@ -1,55 +1,44 @@ --- name: create-lab-guide -description: > - Create a guide page for a Labspace. This includes writing the markdown content for the guide, - structuring it according to Docker docs conventions, and ensuring it provides clear instructions - and information about the Labspace. Includes learning about the lab itself, extracting out its - learning objectives, and combining all of that into a well-structured guide markdown file. +description: "Clone a dockersamples Labspace repo, extract learning objectives and module structure from labspace.yaml, and produce a Hugo guide page under content/guides/ with correct frontmatter, labspace-launch shortcode, and Docker docs style compliance. Use when asked to create a lab guide, write a Labspace page, add a Docker lab tutorial, migrate a lab to docs, or document a hands-on lab." --- # Create Lab Guide -You are creating a new guide page for a labspace. The guide should be structured according to Docker docs conventions, -with clear sections, learning objectives, and instructions for users to get the most out of the lab. +Create a guide page for a Docker Labspace: clone the source repo, extract +structure from `labspace.yaml`, write the Hugo markdown page, and validate. ## Inputs -The user provides one or more guides to migrate. Resolve these from the inventory below: - - **REPO_NAME**: GitHub repo in the `dockersamples` org (e.g. `labspace-ai-fundamentals`) ## Step 1: Clone the labspace repo -Clone the guide repo to a temporary directory. This gives you all source files locally — no HTTP calls needed. - ```bash -git clone --depth 1 https://github.com/dockersamples/{REPO_NAME}.git /{REPO_NAME} +TMPDIR=$(mktemp -d) +git clone --depth 1 https://github.com/dockersamples/{REPO_NAME}.git "$TMPDIR/{REPO_NAME}" ``` -Where `` is a temporary directory on your system (e.g. the output of `mktemp -d`). - -## Step 2: Learn and extract key information about the lab - -The repo structure is: +## Step 2: Extract key information -- `/{REPO_NAME}/README.md` — the main README for the lab -- `/{REPO_NAME}/labspace/labspace.yaml` — a YAML document outlining details of the lab, including the sections/modules and the path to their content -- `/{REPO_NAME}/labspace/*.md` — the content for each section/module (only reference the files specified in `labspace.yaml`) -- `/{REPO_NAME}/.github/workflows/` — the GHA workflow that publishes the labspace. It includes the repo URL for the published Compose file, which will be useful for the "launch" command -- `/{REPO_NAME}/compose.override.yaml` - lab-specific Compose customizations +Read these files from the cloned repo: -1. Read `README.md` to understand the purpose of the lab. -2. Read the `labspace/labspace.yaml` to understand the structure of the lab and its sections/modules. -3. Read the `labspace/*.md` files to extract the learning objectives, instructions, and any code snippets. -4. Extract a short description that can be used for the `description` and `summary` fields in the guide markdown. -5. Determine if a model will be pulled when starting the lab by looking at the `compose.override.yaml` file and looking for the any top-level `model` specifications. +| File | Purpose | +|------|---------| +| `README.md` | Lab purpose and overview | +| `labspace/labspace.yaml` | Module structure and content paths | +| `labspace/*.md` | Module content (only files listed in `labspace.yaml`) | +| `.github/workflows/*.yml` | Published Compose file URL for the launch command | +| `compose.override.yaml` | Check for top-level `model` specs (triggers `model-download` param) | +Extract: +1. A short description for the `description` and `summary` frontmatter fields. +2. Learning objectives from the module content. +3. Whether a model download is required (`compose.override.yaml` → top-level `model` key). -## Step 2: Write the guide markdown +## Step 3: Write the guide markdown -The markdown file must be located in the `guides/` directory and have a filename of `lab-{GUIDE_ID}.md`. - -Sample markdown structure, including frontmatter and content: +Place the file at `content/guides/lab-{GUIDE_ID}.md`. ```markdown --- @@ -60,7 +49,7 @@ description: | summary: | A short summary of the lab for the guides listing page. 2-3 lines. keywords: AI, Docker, Model Runner, agentic apps, lab, labspace -aliases: # Include if the lab is an AI-related lab +aliases: # Include only for AI-related labs - /labs/docker-for-ai/{REPO_NAME_WITHOUT_LABSPACE_PREFIX}/ params: tags: [ai, labs] @@ -85,7 +74,6 @@ By the end of this Labspace, you will have completed the following: - Objective #1 - Objective #2 - Objective #3 -- Objective #4 ## Modules @@ -94,33 +82,35 @@ By the end of this Labspace, you will have completed the following: | 1 | Module #1 | Description of module #1 | | 2 | Module #2 | Description of module #2 | | 3 | Module #3 | Description of module #3 | -| 4 | Module #4 | Description of module #4 | -| 5 | Module #5 | Description of module #5 | -| 6 | Module #6 | Description of module #6 | ``` -Important notes: +Conditional rules: +- All lab guides **must** include `labs` in `params.tags`. +- AI-related labs: also add `ai` tag and an alias under `/labs/docker-for-ai/`. +- If a model download is required: add `model-download: true` to the `labspace-launch` shortcode. + +## Step 4: Apply Docker docs style rules + +Follow STYLE.md and COMPONENTS.md. Key rules: -- The learning objectives should be based on the content of the labspace as a whole. -- The modules should be based on the sections/modules outlined in `labspace.yaml`. -- All lab guides _must_ have a tag of `labs` -- If the lab is AI-related, it should also have a tag of `ai` and aliases for `/labs/docker-for-ai/{REPO_NAME}/` -- If the lab pulls a model, add a `model-download: true` parameter to the `labspace-launch` shortcode to show a warning about model downloads. +| Avoid | Use instead | +|-------|-------------| +| "we", "let's" | Imperative voice or "you" | +| "simply", "easily", "just" | Remove the hedge word | +| "allows you to" / "enables you to" | "lets you" or rephrase | +| "click" | "select" | +| Bold for emphasis / product names | Bold only for UI elements | +| "currently", "new", "recently" | Remove time-relative language | +Use `console` as the language hint for shell blocks with `$` prompts. +Use contractions ("it's", "you're", "don't"). -## Step 3: Apply Docker docs style rules +## Step 5: Validate -These are mandatory (from STYLE.md and AGENTS.md): +1. Confirm frontmatter has `title`, `description`, `keywords`, and `params.tags` including `labs`. +2. Run `npx prettier --write ` to format. +3. Run `docker buildx bake lint vale` and fix any errors. +4. Re-read the file and verify: correct shortcode syntax, objectives match source content, modules match `labspace.yaml`, no vendored paths edited. -- **No "we"**: "We are going to create" → "Create" or "Start by creating" -- **No "let us" / "let's"**: → imperative voice or "You can..." -- **No hedge words**: remove "simply", "easily", "just", "seamlessly" -- **No meta-commentary**: remove "it's worth noting", "it's important to understand" -- **No "allows you to" / "enables you to"**: → "lets you" or rephrase -- **No "click"**: → "select" -- **No bold for emphasis or product names**: only bold UI elements -- **No time-relative language**: remove "currently", "new", "recently", "now" -- **No exclamations**: remove "Voila!!!" etc. -- Use `console` language hint for interactive shell blocks with `$` prompts -- Use contractions: "it's", "you're", "don't" +Do not proceed to commit until validation passes.