From ec40d693cfa4959f03840577812baf89fece1b32 Mon Sep 17 00:00:00 2001 From: Harlan Wilton Date: Mon, 5 Oct 2026 17:20:37 +1100 Subject: [PATCH] feat(marketing): add visual portable Skill examples --- docs/editorial/portable-skills/BRIEF.md | 26 +++ docs/editorial/portable-skills/SCREENSHOTS.md | 19 +- .../app/components/MarketingArticle.vue | 184 ++++++++++++++++++ .../content/learn/create-agent-skills.md | 162 ++++++++++++--- 4 files changed, 364 insertions(+), 27 deletions(-) diff --git a/docs/editorial/portable-skills/BRIEF.md b/docs/editorial/portable-skills/BRIEF.md index c957421b..b1d09b9b 100644 --- a/docs/editorial/portable-skills/BRIEF.md +++ b/docs/editorial/portable-skills/BRIEF.md @@ -9,6 +9,7 @@ Keep its run command first. Link package-specific work to the existing authoring This page owns cross-Agent mechanics. The project guide links here instead of gaining a duplicate compatibility section. It does not create an agent-by-agent article series or a general guides expansion. Exclude: every-agent guarantees, hosted-chat uploads, new renderers and unrelated rewrites. +Native figures and source-linked Skill cards use the existing article renderer. Foundations: [sources](SOURCES.md), [claims](VERIFIED-CLAIMS.md), [voice](../../../COPY.md), [figures](SCREENSHOTS.md). Claims: P01 through P08. Primary sources opened 2026-10-05. @@ -86,3 +87,28 @@ The final article and its accepted digest are unchanged. Independent linking review: article_review accepted the placements and donor eligibility. Resolved findings: qualify donor compatibility claims, correct Claude's loaded-context claim, and require dated equal-length Search Console windows without causal attribution. + +## Visual enhancement brief, 2026-10-05 + +User: the article feels weak and needs visuals, diagrams or Skill embeds. +Keep the same route, primary command, complete example and existing review fragment. +Add project discovery and four-stage check diagrams at their relevant steps. +Add a worked expected-result figure beside the exact supplied diff and notes. +Replace the final plain authoring links with source-linked project and package Skill cards. +Reuse the existing native MDC renderer and copyable code blocks. Add no dependency or remote data request. +The [figure plan](SCREENSHOTS.md) owns evidence boundaries and captions. +No screenshot or chart is needed to imply stronger execution evidence than REPLAY.md supports. +Review: an independent brief reviewer checks scope before drafting; an independent article reviewer checks the final rendered revision. +Brief reviewer: brief_review accepted the scope at 95/100. Resolved before drafting: inline Gemini alias, complete-directory semantics, separate check outcomes, synthetic result label and package-version input. +The project discovery columns and duplicated expected-result explanation became native figures. The home-directory table remains reference material. +Factual pass: article_review accepted draft digest `3c19e4eca9d11f3e884371c91bf4a12bb39d92600938b67afe657e374117c856` at 95/100. +Humanize pass: named the diff as the actor instead of “is exported”; retained the value and default caveat. +Added a dated local-trial ledger from REPLAY.md so readers can separate observed results from prescribed checks. +Final review must check the revised ledger and rendered digest; the earlier acceptance does not cover those additions. +Acceptance: server-rendered figures, accurate paths, explicit expected-result label, usable commands and source links. +Verify 390px mobile and 1440px desktop in both themes, captions, contrast, keyboard copying and no document overflow. +Final independent acceptance: article_review checked digest `04a7e2606f7682be655571591ea4d5bd21863d0b5962e57ba772341b1c673e5b` at 98/100. +It inspected the mobile trial ledger and desktop, mobile, light and dark figure captures. No remaining findings. +Local verification: four figures and two authoring cards render in SSR. Widths 390, 768 and 1440 have no overflow. +Article-scoped contrast, heading and accessible-name checks passed in both themes. Keyboard copies matched both run commands. +Typecheck, build, published CLI grammar and 2,926 tests passed. Existing canonical, admission and inbound links remain valid. diff --git a/docs/editorial/portable-skills/SCREENSHOTS.md b/docs/editorial/portable-skills/SCREENSHOTS.md index 0e6f9dcb..c5b7a171 100644 --- a/docs/editorial/portable-skills/SCREENSHOTS.md +++ b/docs/editorial/portable-skills/SCREENSHOTS.md @@ -1,7 +1,22 @@ # Screenshots -The pilot teaches a file format and discovery paths. Use copyable Markdown and a small path table. -No screenshot belongs in the article. Screenshots cannot prove Agent execution. +The pilot teaches a file format and discovery paths. Retain copyable Markdown and the path table. +The user's visual enhancement request supersedes the initial text-only decision. +Use native HTML figures for relationships and expected results, with visible captions. +These figures are explanatory diagrams, not screenshots or execution evidence. + +| Figure | Reader question | Evidence and caption limit | +| --- | --- | --- | +| Project discovery diagram | Where does the same Skill go? | P02-P04. Show full project paths for the example. Gemini also accepts `.agents/skills`. Placement is not automatic synchronization. | +| Four-stage check diagram | What does each check establish? | REPLAY.md and existing article. Stages are checks to perform, not measured Agent passes. | +| Worked result | What should a useful review flag? | Exact published input. An expected result, not a captured Agent answer. The export alone does not prove a runtime default. | +| Authoring Skill cards | Which source helps my next task? | P07. Readable source plus copyable run command. No usage or quality metrics. | +| Local trial ledger | Which outcomes were observed? | REPLAY.md, dated 5 October 2026. Exact versions, Codex model, local scope and Claude/Gemini limits. No benchmark or compatibility score. | + +Keep all figure text in server-rendered HTML. Use real figures and figcaptions. +Use the site's semantic colors, font tokens and border hierarchy. +Stack nodes at narrow widths. Preserve the existing prose, code example and table as the text alternative. +Do not invent interface screenshots, benchmark charts, speed comparisons or Agent completion claims. Capture layout evidence with task-named `dev-browser --headless`. Keep captures in `~/scratch/portable-skills/`. diff --git a/layers/marketing/app/components/MarketingArticle.vue b/layers/marketing/app/components/MarketingArticle.vue index b2c64b9b..6a33efae 100644 --- a/layers/marketing/app/components/MarketingArticle.vue +++ b/layers/marketing/app/components/MarketingArticle.vue @@ -89,4 +89,188 @@ function copyCommand(): void { .learn-article :deep(a:hover) { color: var(--ui-text-muted); } + +/* Native article diagrams retain readable, server-rendered text in both themes. */ +.learn-article :deep(.article-figure) { + margin-block: 2rem; + padding: 1rem; + border: 1px solid var(--ui-border); + border-radius: var(--ui-radius); + color: var(--ui-text); +} + +.learn-article :deep(.article-figure p) { + margin-block: 0.5rem; +} + +.learn-article :deep(.article-figure code) { + white-space: normal; + overflow-wrap: anywhere; +} + +.learn-article :deep(.article-figure figcaption) { + margin-top: 1rem; + color: var(--ui-text-muted); + font-size: 0.875rem; + line-height: 1.6; + text-align: center; +} + +.learn-article :deep(.skill-source) { + position: relative; + width: fit-content; + max-width: 100%; + margin-inline: auto; + padding: 0.75rem 1rem; + border: 1px solid var(--ui-border); + border-radius: var(--ui-radius); + background: var(--ui-bg-muted); + text-align: center; +} + +.learn-article :deep(.discovery-paths) { + position: relative; + display: grid; + gap: 1rem; + margin-top: 1.5rem; + margin-left: 1rem; + padding-left: 1rem; + border-left: 1px solid var(--ui-border); +} + +.learn-article :deep(.discovery-paths::before) { + position: absolute; + top: -1.5rem; + left: -1px; + height: 1.5rem; + border-left: 1px solid var(--ui-border); + content: ''; +} + +.learn-article :deep(.discovery-path) { + position: relative; + min-width: 0; +} + +.learn-article :deep(.discovery-path::before) { + position: absolute; + top: 1.25rem; + left: -1rem; + width: 1rem; + border-top: 1px solid var(--ui-border); + content: ''; +} + +.learn-article :deep(.check-stages) { + display: grid; + gap: 1rem; + padding: 0; + list-style: none; +} + +.learn-article :deep(.check-stages li) { + min-width: 0; + padding: 0; +} + +.learn-article :deep(.check-stages li + li) { + padding-top: 1rem; + border-top: 1px solid var(--ui-border); +} + +.learn-article :deep(.result-pair) { + display: grid; + gap: 1rem; +} + +.learn-article :deep(.result-finding) { + margin-top: 1rem; + padding-top: 1rem; + border-top: 1px solid var(--ui-border); +} + +.learn-article :deep(.authoring-skills) { + display: grid; + gap: 1rem; + margin-block: 1.5rem; +} + +.learn-article :deep(.authoring-skill-card) { + min-width: 0; + padding: 1rem; + border: 1px solid var(--ui-border); + border-radius: var(--ui-radius); +} + +.learn-article :deep(.authoring-skill-card h3) { + margin-top: 0; + font-family: var(--font-mono); + font-size: 1rem; + overflow-wrap: anywhere; +} + +.learn-article :deep(.authoring-skill-card a) { + display: inline-flex; + align-items: center; + min-height: 44px; +} + +.learn-article :deep(.authoring-skill-card pre) { + white-space: pre-wrap; + overflow-wrap: anywhere; +} + +@media (min-width: 640px) { + .learn-article :deep(.skill-source::after) { + position: absolute; + top: 100%; + left: 50%; + height: 0.5rem; + border-left: 1px solid var(--ui-border); + content: ''; + } + + .learn-article :deep(.discovery-paths::before) { + position: absolute; + top: -1rem; + left: calc((100% - 2rem) / 6); + right: calc((100% - 2rem) / 6); + height: 0; + border-left: none; + border-top: 1px solid var(--ui-border); + content: ''; + } + + .learn-article :deep(.discovery-paths) { + grid-template-columns: repeat(3, minmax(0, 1fr)); + margin-left: 0; + padding-left: 0; + border-left: none; + } + + .learn-article :deep(.discovery-path) { + padding-top: 0.75rem; + border-top: 1px solid var(--ui-border); + } + + .learn-article :deep(.discovery-path::before) { + top: -1rem; + left: 50%; + width: 0; + height: 1rem; + border-top: none; + border-left: 1px solid var(--ui-border); + } + + .learn-article :deep(.check-stages), + .learn-article :deep(.result-pair), + .learn-article :deep(.authoring-skills) { + grid-template-columns: repeat(2, minmax(0, 1fr)); + } + + .learn-article :deep(.check-stages li + li) { + padding-top: 0; + border-top: none; + } +} diff --git a/layers/marketing/content/learn/create-agent-skills.md b/layers/marketing/content/learn/create-agent-skills.md index 5d956e1d..b3e61cac 100644 --- a/layers/marketing/content/learn/create-agent-skills.md +++ b/layers/marketing/content/learn/create-agent-skills.md @@ -61,18 +61,50 @@ A source directory such as `skills/review-release-notes/` keeps your authored fi It does not make them discoverable automatically. Expose the complete directory, including any supporting files, through the Agent's documented path: -| Agent | Project discovery path | User discovery path | -| --- | --- | --- | -| [Claude Code](https://code.claude.com/docs/en/skills) | `.claude/skills/` | `~/.claude/skills/` | -| [Codex](https://learn.chatgpt.com/docs/build-skills) | `.agents/skills/` | `~/.agents/skills/` | -| [Gemini CLI](https://geminicli.com/docs/cli/skills/) | `.agents/skills/` or `.gemini/skills/` | `~/.agents/skills/` or `~/.gemini/skills/` | - -For example, Claude Code's project copy belongs at `.claude/skills/review-release-notes/SKILL.md`. -For Codex and Gemini CLI, use `.agents/skills/review-release-notes/SKILL.md`. +::::figure{.article-figure .skill-discovery} +:::div{.skill-source} +**Your reviewed source** + +`skills/review-release-notes/` + +`SKILL.md` and any supporting files +::: + +:::div{.discovery-paths} +::div{.discovery-path} +**[Claude Code](https://code.claude.com/docs/en/skills)** + +`.claude/skills/review-release-notes/SKILL.md` +:: +::div{.discovery-path} +**[Codex](https://learn.chatgpt.com/docs/build-skills)** + +`.agents/skills/review-release-notes/SKILL.md` +:: +::div{.discovery-path} +**[Gemini CLI](https://geminicli.com/docs/cli/skills/)** + +`.gemini/skills/review-release-notes/SKILL.md` + +Also accepts `.agents/skills/`, which takes precedence within the same scope. +:: +::: + +::figcaption +Project discovery paths. Expose the complete Skill directory at each destination; these connections do not synchronize files or prove execution. +:: +:::: + Keep their contents aligned with your source Skill when you update it. +For a user-level Skill available across projects, use the corresponding home-directory path: + +| Agent | User discovery path | +| --- | --- | +| Claude Code | `~/.claude/skills/` | +| Codex | `~/.agents/skills/` | +| Gemini CLI | `~/.agents/skills/` or `~/.gemini/skills/` | Codex documents support for symlinked Skill folders. -Gemini CLI gives `.agents/skills/` precedence over `.gemini/skills/` within the same scope. Check discovery before assuming a copied or linked directory loaded. If an Agent misses an update, follow its documented reload or restart procedure. @@ -101,11 +133,37 @@ Run project commands from the project root, and state that working directory exp Use a fresh local session for each Agent you support. Give the same Skill and inputs to each session. -First, check the Agent's Skill list or selector for `review-release-notes`. -When running a request, inspect its activation message or trace to confirm it loaded this Skill. + +::::figure{.article-figure .skill-checks} +:::ol{.check-stages} +::li +**1. Valid format** + +Check frontmatter, directory name and supporting paths. A parser checks structure. +:: +::li +**2. Discovered** + +Find `review-release-notes` in the Agent's Skill list or selector. +:: +::li +**3. Selected** + +Inspect the activation trace. For Gemini CLI, review and approve consent before the full instructions load. +:: +::li +**4. Completed** + +Check the answer against the supplied diff, including unsupported claims and missing input. +:: +::: +::figcaption +Four separate checks, not a compatibility score. Passing one does not prove the next. A correct answer alone does not prove activation. +:: +:::: + [Gemini CLI](https://geminicli.com/docs/cli/skills/#how-it-works) requests consent before loading the Skill's full instructions. -Approve that request only after reviewing the Skill. A pending or denied request does not prove activation. -A correct answer alone does not prove activation. +A pending or denied request does not prove activation. Start with this explicit request: ```text @@ -118,10 +176,28 @@ Draft release notes: The new timeout defaults to 10 seconds. ``` -Expect a finding that the notes contradict `config.ts`. -Corrected notes should state 5 seconds, or 5000 milliseconds. -The exported value does not establish a runtime default. The Agent should flag that unsupported claim too. -This checks a small supplied diff, not a complete repository review. +::::figure{.article-figure .skill-result} +:::div{.result-pair} +::div +**The draft claim** + +“The new timeout defaults to **10 seconds**.” +:: +::div +**What the diff establishes** + +The diff exports `timeoutMs` as **5000 milliseconds**, or 5 seconds. +:: +::: +::div{.result-finding} +**Expected review** + +Flag the incorrect value and the unsupported runtime-default claim. Suggested notes: “Exported `timeoutMs` with a value of 5000 milliseconds.” +:: +::figcaption +Synthetic example and expected result, not an Agent screenshot. The export does not establish a runtime default. This checks the supplied diff, not a complete repository. +:: +:::: In another fresh session, supply the same inputs with “Check these release notes against this diff.” Leave out the Skill name and check the activation trace again. @@ -135,18 +211,54 @@ Check that task matching does not select the release-note procedure. If it does, narrow the description and repeat that input. Record the Agent version, model, request and observed output. -Distinguish four results: valid format, discovered Skill, selected Skill and completed task. -A parser can prove the first. It cannot prove the other three. The [Agent Skills quickstart](https://agentskills.io/skill-creation/quickstart) also notes that tool-use reliability varies across models. Treat these inputs as checks to run, rather than evidence that every Agent already passed. +:::figure{.article-figure .skill-observations} +**Local trials, 5 October 2026** + +| Agent and version | Observed result with this example | +| --- | --- | +| Codex 0.160.0 | Loaded the Skill for explicit and unnamed matching requests. Corrected the timeout value and flagged the unsupported default claim. | +| Claude Code 2.1.288 | Listed the Skill. Its weekly usage limit prevented task execution. | +| Gemini CLI 0.54.0 | An account-tier restriction prevented execution before discovery could be observed. | + +::figcaption +The Codex trials used the configured gpt-6.1-sol model. Existing user configuration remained available. These observations establish local Codex behavior, not Claude or Gemini task completion. +:: +::: + ## Draft a Skill from your own project -The run command above loads skilld's [generate-project-skill source](https://github.com/skilld-dev/skilld/blob/main/skills/generate-project-skill/SKILL.md). -Give it your project directory and destination, then review the draft before committing. -Follow [Author a Skill for your project](/learn/author-project-skills) for project-specific evidence and maintenance. +Choose an authoring Skill for the source you maintain. Review its instructions before running it. + +::::div{.authoring-skills} +:::section{.authoring-skill-card} +### generate-project-skill + +Give the Agent your project directory and destination. Review the draft before committing. + +```sh +npx skilld run skilld-dev/skilld/generate-project-skill +``` + +[Read the project Skill source](https://github.com/skilld-dev/skilld/blob/main/skills/generate-project-skill/SKILL.md) + +[Follow the project authoring guide](/learn/author-project-skills) +::: +:::section{.authoring-skill-card} +### generate-package-skill + +Give the Agent your package and version. Check examples against the version consumers install. + +```sh +npx skilld run skilld-dev/skilld/generate-package-skill +``` + +[Read the package Skill source](https://github.com/skilld-dev/skilld/blob/main/skills/generate-package-skill/SKILL.md) + +[Choose a package authoring guide](/make-skill) +::: +:::: -If you maintain a package, use the [package authoring guides](/make-skill). -They cover testing examples against the version consumers install. -The [generate-package-skill source](https://github.com/skilld-dev/skilld/blob/main/skills/generate-package-skill/SKILL.md) stays readable in the same repository. Keep one reviewed source for each Skill, and repeat the affected checks when its instructions change.