Skip to content

Commit 1f2c697

Browse files
harlan-zwharlan-zw
authored
feat(marketing): add visual examples to portable Skill guide (#412)
1 parent 3d87519 commit 1f2c697

4 files changed

Lines changed: 364 additions & 27 deletions

File tree

‎docs/editorial/portable-skills/BRIEF.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Keep its run command first. Link package-specific work to the existing authoring
99
This page owns cross-Agent mechanics. The project guide links here instead of gaining a duplicate compatibility section.
1010
It does not create an agent-by-agent article series or a general guides expansion.
1111
Exclude: every-agent guarantees, hosted-chat uploads, new renderers and unrelated rewrites.
12+
Native figures and source-linked Skill cards use the existing article renderer.
1213

1314
Foundations: [sources](SOURCES.md), [claims](VERIFIED-CLAIMS.md), [voice](../../../COPY.md), [figures](SCREENSHOTS.md).
1415
Claims: P01 through P08. Primary sources opened 2026-10-05.
@@ -86,3 +87,28 @@ The final article and its accepted digest are unchanged.
8687
Independent linking review: article_review accepted the placements and donor eligibility.
8788
Resolved findings: qualify donor compatibility claims, correct Claude's loaded-context claim,
8889
and require dated equal-length Search Console windows without causal attribution.
90+
91+
## Visual enhancement brief, 2026-10-05
92+
93+
User: the article feels weak and needs visuals, diagrams or Skill embeds.
94+
Keep the same route, primary command, complete example and existing review fragment.
95+
Add project discovery and four-stage check diagrams at their relevant steps.
96+
Add a worked expected-result figure beside the exact supplied diff and notes.
97+
Replace the final plain authoring links with source-linked project and package Skill cards.
98+
Reuse the existing native MDC renderer and copyable code blocks. Add no dependency or remote data request.
99+
The [figure plan](SCREENSHOTS.md) owns evidence boundaries and captions.
100+
No screenshot or chart is needed to imply stronger execution evidence than REPLAY.md supports.
101+
Review: an independent brief reviewer checks scope before drafting; an independent article reviewer checks the final rendered revision.
102+
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.
103+
The project discovery columns and duplicated expected-result explanation became native figures. The home-directory table remains reference material.
104+
Factual pass: article_review accepted draft digest `3c19e4eca9d11f3e884371c91bf4a12bb39d92600938b67afe657e374117c856` at 95/100.
105+
Humanize pass: named the diff as the actor instead of “is exported”; retained the value and default caveat.
106+
Added a dated local-trial ledger from REPLAY.md so readers can separate observed results from prescribed checks.
107+
Final review must check the revised ledger and rendered digest; the earlier acceptance does not cover those additions.
108+
Acceptance: server-rendered figures, accurate paths, explicit expected-result label, usable commands and source links.
109+
Verify 390px mobile and 1440px desktop in both themes, captions, contrast, keyboard copying and no document overflow.
110+
Final independent acceptance: article_review checked digest `04a7e2606f7682be655571591ea4d5bd21863d0b5962e57ba772341b1c673e5b` at 98/100.
111+
It inspected the mobile trial ledger and desktop, mobile, light and dark figure captures. No remaining findings.
112+
Local verification: four figures and two authoring cards render in SSR. Widths 390, 768 and 1440 have no overflow.
113+
Article-scoped contrast, heading and accessible-name checks passed in both themes. Keyboard copies matched both run commands.
114+
Typecheck, build, published CLI grammar and 2,926 tests passed. Existing canonical, admission and inbound links remain valid.

‎docs/editorial/portable-skills/SCREENSHOTS.md‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,22 @@
11
# Screenshots
22

3-
The pilot teaches a file format and discovery paths. Use copyable Markdown and a small path table.
4-
No screenshot belongs in the article. Screenshots cannot prove Agent execution.
3+
The pilot teaches a file format and discovery paths. Retain copyable Markdown and the path table.
4+
The user's visual enhancement request supersedes the initial text-only decision.
5+
Use native HTML figures for relationships and expected results, with visible captions.
6+
These figures are explanatory diagrams, not screenshots or execution evidence.
7+
8+
| Figure | Reader question | Evidence and caption limit |
9+
| --- | --- | --- |
10+
| 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. |
11+
| Four-stage check diagram | What does each check establish? | REPLAY.md and existing article. Stages are checks to perform, not measured Agent passes. |
12+
| 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. |
13+
| Authoring Skill cards | Which source helps my next task? | P07. Readable source plus copyable run command. No usage or quality metrics. |
14+
| 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. |
15+
16+
Keep all figure text in server-rendered HTML. Use real figures and figcaptions.
17+
Use the site's semantic colors, font tokens and border hierarchy.
18+
Stack nodes at narrow widths. Preserve the existing prose, code example and table as the text alternative.
19+
Do not invent interface screenshots, benchmark charts, speed comparisons or Agent completion claims.
520

621
Capture layout evidence with task-named `dev-browser --headless`.
722
Keep captures in `~/scratch/portable-skills/`.

‎layers/marketing/app/components/MarketingArticle.vue‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,4 +89,188 @@ function copyCommand(): void {
8989
.learn-article :deep(a:hover) {
9090
color: var(--ui-text-muted);
9191
}
92+
93+
/* Native article diagrams retain readable, server-rendered text in both themes. */
94+
.learn-article :deep(.article-figure) {
95+
margin-block: 2rem;
96+
padding: 1rem;
97+
border: 1px solid var(--ui-border);
98+
border-radius: var(--ui-radius);
99+
color: var(--ui-text);
100+
}
101+
102+
.learn-article :deep(.article-figure p) {
103+
margin-block: 0.5rem;
104+
}
105+
106+
.learn-article :deep(.article-figure code) {
107+
white-space: normal;
108+
overflow-wrap: anywhere;
109+
}
110+
111+
.learn-article :deep(.article-figure figcaption) {
112+
margin-top: 1rem;
113+
color: var(--ui-text-muted);
114+
font-size: 0.875rem;
115+
line-height: 1.6;
116+
text-align: center;
117+
}
118+
119+
.learn-article :deep(.skill-source) {
120+
position: relative;
121+
width: fit-content;
122+
max-width: 100%;
123+
margin-inline: auto;
124+
padding: 0.75rem 1rem;
125+
border: 1px solid var(--ui-border);
126+
border-radius: var(--ui-radius);
127+
background: var(--ui-bg-muted);
128+
text-align: center;
129+
}
130+
131+
.learn-article :deep(.discovery-paths) {
132+
position: relative;
133+
display: grid;
134+
gap: 1rem;
135+
margin-top: 1.5rem;
136+
margin-left: 1rem;
137+
padding-left: 1rem;
138+
border-left: 1px solid var(--ui-border);
139+
}
140+
141+
.learn-article :deep(.discovery-paths::before) {
142+
position: absolute;
143+
top: -1.5rem;
144+
left: -1px;
145+
height: 1.5rem;
146+
border-left: 1px solid var(--ui-border);
147+
content: '';
148+
}
149+
150+
.learn-article :deep(.discovery-path) {
151+
position: relative;
152+
min-width: 0;
153+
}
154+
155+
.learn-article :deep(.discovery-path::before) {
156+
position: absolute;
157+
top: 1.25rem;
158+
left: -1rem;
159+
width: 1rem;
160+
border-top: 1px solid var(--ui-border);
161+
content: '';
162+
}
163+
164+
.learn-article :deep(.check-stages) {
165+
display: grid;
166+
gap: 1rem;
167+
padding: 0;
168+
list-style: none;
169+
}
170+
171+
.learn-article :deep(.check-stages li) {
172+
min-width: 0;
173+
padding: 0;
174+
}
175+
176+
.learn-article :deep(.check-stages li + li) {
177+
padding-top: 1rem;
178+
border-top: 1px solid var(--ui-border);
179+
}
180+
181+
.learn-article :deep(.result-pair) {
182+
display: grid;
183+
gap: 1rem;
184+
}
185+
186+
.learn-article :deep(.result-finding) {
187+
margin-top: 1rem;
188+
padding-top: 1rem;
189+
border-top: 1px solid var(--ui-border);
190+
}
191+
192+
.learn-article :deep(.authoring-skills) {
193+
display: grid;
194+
gap: 1rem;
195+
margin-block: 1.5rem;
196+
}
197+
198+
.learn-article :deep(.authoring-skill-card) {
199+
min-width: 0;
200+
padding: 1rem;
201+
border: 1px solid var(--ui-border);
202+
border-radius: var(--ui-radius);
203+
}
204+
205+
.learn-article :deep(.authoring-skill-card h3) {
206+
margin-top: 0;
207+
font-family: var(--font-mono);
208+
font-size: 1rem;
209+
overflow-wrap: anywhere;
210+
}
211+
212+
.learn-article :deep(.authoring-skill-card a) {
213+
display: inline-flex;
214+
align-items: center;
215+
min-height: 44px;
216+
}
217+
218+
.learn-article :deep(.authoring-skill-card pre) {
219+
white-space: pre-wrap;
220+
overflow-wrap: anywhere;
221+
}
222+
223+
@media (min-width: 640px) {
224+
.learn-article :deep(.skill-source::after) {
225+
position: absolute;
226+
top: 100%;
227+
left: 50%;
228+
height: 0.5rem;
229+
border-left: 1px solid var(--ui-border);
230+
content: '';
231+
}
232+
233+
.learn-article :deep(.discovery-paths::before) {
234+
position: absolute;
235+
top: -1rem;
236+
left: calc((100% - 2rem) / 6);
237+
right: calc((100% - 2rem) / 6);
238+
height: 0;
239+
border-left: none;
240+
border-top: 1px solid var(--ui-border);
241+
content: '';
242+
}
243+
244+
.learn-article :deep(.discovery-paths) {
245+
grid-template-columns: repeat(3, minmax(0, 1fr));
246+
margin-left: 0;
247+
padding-left: 0;
248+
border-left: none;
249+
}
250+
251+
.learn-article :deep(.discovery-path) {
252+
padding-top: 0.75rem;
253+
border-top: 1px solid var(--ui-border);
254+
}
255+
256+
.learn-article :deep(.discovery-path::before) {
257+
top: -1rem;
258+
left: 50%;
259+
width: 0;
260+
height: 1rem;
261+
border-top: none;
262+
border-left: 1px solid var(--ui-border);
263+
}
264+
265+
.learn-article :deep(.check-stages),
266+
.learn-article :deep(.result-pair),
267+
.learn-article :deep(.authoring-skills) {
268+
grid-template-columns: repeat(2, minmax(0, 1fr));
269+
}
270+
271+
.learn-article :deep(.check-stages li + li) {
272+
padding-top: 0;
273+
border-top: none;
274+
}
275+
}
92276
</style>

0 commit comments

Comments
 (0)