feat(marketing): add cross-Agent Skill authoring guide

COPY.md

@@ -74,6 +74,15 @@ These are the visual layer's half of the voice. `DESIGN.md` defers to them.
 
 ## Copy principles
 
+### Authoring articles
+
+Lead with one complete example and the common path.
+Keep runtime requirements beside the affected step.
+Explain Agent differences without promising identical behavior.
+Link authoring Skills when they help the next task. Avoid repeated product pitches.
+Attribute technical claims to current primary documentation.
+Keep editorial evidence under `docs/editorial/`, outside published content.
+
 **Personality.** Confident, warm, editorial. Think independent technical magazine, not startup landing page. We sound like a developer sharing their honest opinion over coffee, not a company selling a product.
 
 1. **Human first.** Write for developers, about developers. The technology (AI, agents, protocols) is infrastructure; the people and their expertise are the story.

app/pages/index.vue

@@ -1046,6 +1046,12 @@ function recentUpdateDescription(item: RecentUpdateCard): string {
             <p class="mt-4 max-w-2xl text-base leading-relaxed text-muted text-pretty">
               Choose a package you publish or a project you maintain. Get the steps to draft a Skill, review it, and ship it in your repository.
             </p>
+            <p class="mt-3 max-w-2xl text-base leading-relaxed text-muted">
+              Start with a
+              <NuxtLink to="/learn/create-agent-skills" class="text-default underline">
+                complete portable Skill example
+              </NuxtLink>.
+            </p>
             <ul class="home-eco-logos mt-5 list-none p-0" aria-label="Package ecosystems">
               <li
                 v-for="ecosystem in authoringEcosystems"

docs/editorial/portable-skills/BRIEF.md

@@ -0,0 +1,88 @@
+# Portable Skills pilot
+
+Scope: one article at `/learn/create-agent-skills`, plus natural links from Learn and project authoring.
+Reader: a maintainer who wants one reusable Skill across Claude Code, Codex and Gemini CLI.
+Question: how do I create Claude Skills that also work with other Agents?
+Outcome: write an instruction-only example, expose documented discovery paths, then test selection and output.
+Loop 1 action: run the existing project-authoring Skill, then publish a readable source others can run.
+Keep its run command first. Link package-specific work to the existing authoring guides.
+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.
+
+Foundations: [sources](SOURCES.md), [claims](VERIFIED-CLAIMS.md), [voice](../../../COPY.md), [figures](SCREENSHOTS.md).
+Claims: P01 through P08. Primary sources opened 2026-10-05.
+SEO: `how to create claude skills`, US 2840, 390/month estimate, KD 30.
+Contribution: complete Skill, discovery table, portable replacements and concrete test inputs.
+Outline: shared format, example, discovery, runtime limits, checks, authoring links.
+Example: `review-release-notes/SKILL.md`, reviews supplied release notes against a supplied diff.
+Replay: supply a diff exporting `timeoutMs = 5000` and notes claiming a default of 10 seconds.
+Expect a finding citing the supplied diff, then corrected notes stating 5 seconds.
+The export does not prove a runtime default. Flag that unsupported inference too.
+Negative input: ask for CSS colors. Expect no activation through task matching.
+Missing input: supply notes without a diff. Expect a request for release evidence before review.
+No runtime or credentials required for the example.
+Checks: parser, links, H1, metadata, canonical, robots, desktop/mobile, client navigation and record exclusion.
+Use [replay evidence](REPLAY.md) for observed sessions and remaining execution limits.
+Admission: add this route to the freeze audit and admit it using P06.
+Cull: remove admission to emit noindex and exclude from the sitemap.
+Review at the existing 2026-11-11 SEO gate.
+Publication authority: open a PR for Harlan. The production workflow deploys after merge.
+Article label names Codex as drafter. Never claim human review before it occurs.
+
+## Review ledger
+
+Brief: reviewed by independent brief_review Agent on 2026-10-05.
+Resolved findings: corrected quickstart scope, concrete replay inputs, bounded Loop 1 action.
+Invocation: `Use review-release-notes to check these notes against this diff`.
+Session scope: fresh local Claude Code, Codex and Gemini CLI sessions.
+Moved the project guide's generic review lines into the new concrete review checklist.
+Article: factual and editorial review passed by independent article_review Agent on 2026-10-05.
+Factual review found that correct output alone does not prove activation.
+Added discovery-list and activation-trace checks, plus a matching prompt without the Skill name.
+Added the specification's leading and trailing hyphen constraint.
+
+## Observed checks, 2026-10-05
+
+- Nuxt parsed the article into the Learn collection. One H1, specific title and description.
+- Built preview served canonical `https://skilld.dev/learn/create-agent-skills` and `index,follow`.
+- Pages sitemap included the article and excluded editorial records. Editorial source route returned 404.
+- Desktop 1440px and mobile 390px rendered without document overflow. Mobile table scrolls within its container.
+- Client navigation from Learn and the project guide reached the article and review anchor.
+- Extracted the published example and parsed it through `loadSkilldMaintainedSkill`.
+- Both modified authoring Skills parsed and ran through local `skilld run`.
+- The article's remote run command resolved `generate-project-skill` through skilld.dev.
+- Site lint passed with existing warnings. Typecheck, production build and all 2,867 tests passed.
+- `skilld-harness` lint, typecheck, build and all 102 tests passed.
+
+The first concurrent check run failed because generated Nuxt files moved during the build.
+The sequential rerun passed. These initial checks did not exercise authenticated or real model execution paths.
+No article screenshots ship. Private layout captures remain in `~/scratch/portable-skills/`.
+
+Humanize pass: kept the concrete procedure; removed any claim that format proves runtime completion.
+Final factual review preserved model limits, dates, source links and replay expectations.
+
+## Content-refresh re-review, 2026-10-05
+
+Parent revision: `b2ad27337190367aaefe18d0c1169af948fa8b4e`.
+Independent reviewers: article_review and brief_review. Coordinator: Codex.
+Findings: isolate the missing-input session, qualify the exported value, explain Gemini consent,
+and preserve dated trial evidence with complete replay instructions.
+Humanize pass: clarified permission configuration while retaining shared authorization rules.
+Added [replay evidence](REPLAY.md). Cross-Agent completion stays unresolved.
+Final article SHA-256: `10c533da43a4196e022b2dfe174344088e713213ca1d0237ed300880d17ddd62`.
+Both independent reviewers accepted that exact digest on 2026-10-05 after checking the corrections and replay evidence.
+Coordinator acceptance: Codex inspected the final article, source checks and revised records.
+Remaining limit: Claude and Gemini task completion, plus production delivery, require separate observation.
+Collection pass: formatted the Learn introduction's `SKILL.md` as code after the renderer autolinked the bare filename.
+
+## Internal linking follow-up, 2026-10-05
+
+User requested a linking strategy for the article.
+See [link map and evidence limits](LINKING.md).
+Add contextual entry points from the homepage, the three covered Agent pages and package-review steps.
+Only homepage, Claude Code and Codex are indexable donors under the existing admission rules.
+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.

docs/editorial/portable-skills/LINKING.md

@@ -0,0 +1,69 @@
+# Internal linking strategy
+
+Checked 2026-10-05. Target: `/learn/create-agent-skills`.
+Reader question: how do I write one Skill and check it across coding Agents?
+The article keeps the authoring query. Agent pages keep their discovery and use queries.
+
+## Evidence and limits
+
+- Source inspection found two existing inbound pages: Learn and project authoring.
+- Both use `noindex,follow`. This limits the strategy to more than authoring-page links.
+- NuxtSEO 0.5.3, Site `s_08aae654`, retained `audit link-structure` shows the authoring chooser in header links.
+- The chooser also uses `noindex,follow`. Header frequency does not establish ranking value.
+- `audit link-opportunities` covered 397 of 1,825 pages and returned zero suggestions.
+  This partial crawl does not establish that no useful links exist.
+- Retained Search Console `pages`, period `28d`, returned 60 rows with no further page.
+  The homepage row had 82 impressions and zero clicks. No relevant Agent or authoring guide row appeared.
+  Missing rows do not prove zero demand. These data cannot identify a donor with proven click traffic.
+- Crawl capture dates and the exact Search Console window dates were absent from these responses.
+  Treat retained counts as planning context, not a measurement of this branch or a traffic forecast.
+
+## Link map
+
+| Source | Placement | Anchor | Destination | Role |
+| --- | --- | --- | --- | --- |
+| `/` | Existing maintainer authoring section | complete portable Skill example | Article root | Direct path from the indexable homepage |
+| `/agents/claude-code` | After the Skill explanation | Create a Claude Code Skill | Article root | Indexable discovery page to authoring procedure |
+| `/agents/codex` | After discovery explanation | Write a Skill that works across Agents | Article root | Indexable discovery page to cross-Agent procedure |
+| `/agents/gemini-cli` | After discovery explanation | Create a portable Agent Skill | Article root | Useful reader path; noindex source |
+| Five package authoring guides | Review step | the cross-Agent selection and task checks | Article review fragment | Reuse the checklist when reviewing each package Skill |
+| `/learn` | Existing guide card | Create Skills for Claude Code, Codex and Gemini CLI | Article root | Existing navigation path |
+| `/learn/author-project-skills` | Existing review step | the cross-Agent checks | Article review fragment | Existing project-authoring path |
+
+The package guides cover npm, PyPI, Go, Rust and Ruby.
+They remain noindex. Their links serve readers; they are not counted as indexable donor pages.
+No source admission or robots rule changes.
+
+## Constraints
+
+Use standard rendered anchors with `href` and concise text that describes the destination.
+Place links beside the question they answer. Do not add a sitewide footer link or repeat exact keywords everywhere.
+Keep the source citations in the article. External citations and internal navigation serve different purposes.
+Keep the existing run command and authoring CTA. No parallel provider-specific tutorial is needed.
+
+Authority: [Google's link best practices](https://developers.google.com/search/docs/crawling-indexing/links-crawlable).
+Google recommends contextual internal links and descriptive text. It specifies no ideal link count.
+The expected benefit is easier discovery and a clearer authoring relationship. No ranking lift is claimed.
+
+## Verification and measurement
+
+Check every source's server-rendered anchor, robots and canonical.
+Follow source links through client navigation. Confirm the destination heading and review fragment.
+Check homepage and Agent-page desktop/mobile placement without altering their main action.
+Keep this record outside the content collections, navigation and sitemap.
+
+After the production workflow delivers the reviewed revision, observe the live links and target canonical.
+Capture a dated Search Console baseline after delivery. Retain the exact start and end dates.
+Compare it with an equal-length dated later window for the target's impressions, clicks and queries.
+A traffic change alone cannot establish that internal links caused it.
+At the existing 2026-11-11 SEO gate, use that evidence to keep, revise or cull the article.
+An empty query response is not proof that the links failed.
+
+## Observed preview checks, 2026-10-05
+
+The built Worker returned HTTP 200 and server-rendered target links from all eleven source routes.
+Their canonical and robots directives confirmed the three indexable donors and eight noindex reader paths.
+The target review fragment exists. The pages sitemap includes the article and excludes editorial records.
+The strategy record's public route returned 404.
+Independent article_review accepted the final donor copy, link placements and measurement limits.
+The article's accepted file digest remains unchanged.

docs/editorial/portable-skills/REPLAY.md

@@ -0,0 +1,86 @@
+# Example replay evidence
+
+Observed 2026-10-05 against article parent commit `b2ad27337190367aaefe18d0c1169af948fa8b4e`.
+The example's Skill body is unchanged by the content-refresh corrections.
+These trials test the article example, not generation by the maintainer authoring Skills.
+
+## Starting state
+
+Create an isolated scratch project. Copy the article's complete fenced `SKILL.md` into:
+
+- `.claude/skills/review-release-notes/SKILL.md`
+- `.agents/skills/review-release-notes/SKILL.md`
+
+Use the same bytes for both copies. No other project Skill was present.
+Existing user configuration remained available. No model override was supplied.
+Codex was 0.160.0, configured model `gpt-6.1-sol`, reasoning effort `medium`.
+Claude Code was 2.1.288. Initialization reported `claude-opus-5-5`.
+Gemini CLI was 0.54.0. It failed before a model was observed.
+Account limits may prevent another operator from reproducing model execution.
+
+## Explicit and matching input
+
+Save this as `input.txt` in the scratch project:
+
+```text
+Use review-release-notes to check these notes against this diff.
+Diff for config.ts:
++ export const timeoutMs = 5000
+Draft release notes:
+The new timeout defaults to 10 seconds.
+```
+
+From that project, run:
+
+```sh
+timeout 120 codex exec --json --sandbox read-only --skip-git-repo-check - < input.txt > explicit.ndjson 2> explicit.err
+```
+
+For a separate matching trial, replace only the first line with:
+`Check these release notes against this diff.`
+Run the same command in a fresh process, using separate output files.
+
+Both observed traces read `.agents/skills/review-release-notes/SKILL.md` with exit code 0.
+Both identified 5 seconds rather than 10 seconds and qualified the unsupported default claim.
+Sanitized explicit result: “Added a timeout setting of 5 seconds.”
+Sanitized matching result: “The timeout is set to 5 seconds.”
+These are local observations, not fixed model outputs or universal selection guarantees.
+
+## Missing input and unrelated task
+
+Run each command separately from the same scratch project. Do not resume an earlier session.
+
+```sh
+timeout 120 codex exec --json --sandbox read-only --skip-git-repo-check 'Use review-release-notes to check these draft release notes: The new timeout defaults to 10 seconds.' > missing.ndjson 2> missing.err
+timeout 120 codex exec --json --sandbox read-only --skip-git-repo-check 'Suggest three CSS background colors for a documentation site.' > unrelated.ndjson 2> unrelated.err
+```
+
+Missing input: the trace read the exact Skill, then requested the release diff before reviewing.
+Sanitized result: “Please paste the release diff so I can verify the 10-second default.”
+Unrelated task: the trace contained one response proposing CSS colors, with no Skill read or activation.
+Neither observation establishes matching behavior for other prompts.
+
+## Claude and Gemini attempts
+
+From the same scratch project and explicit input:
+
+```sh
+timeout 120 claude -p --output-format stream-json --verbose --no-session-persistence --allowedTools Read Skill < input.txt > claude.ndjson 2> claude.err
+timeout 120 gemini --prompt 'Use review-release-notes to check these notes against this diff. Diff for config.ts: + export const timeoutMs = 5000. Draft release notes: The new timeout defaults to 10 seconds.' --approval-mode plan --skip-trust --output-format stream-json > gemini.ndjson 2> gemini.err
+```
+
+Claude initialization listed `review-release-notes`. Its weekly usage limit blocked execution, with zero model tokens.
+This establishes discovery only. It does not establish selection or task completion.
+Gemini returned `IneligibleTierError`: this client was unsupported for the account's Gemini Code Assist tier.
+This establishes no discovery or execution result. Do not generalize it into a Skill compatibility defect.
+If Gemini requests activation, review and approve it before treating the full Skill as loaded.
+
+Raw traces remain private in `~/scratch/portable-skills/`.
+The sanitized observations and complete prompts above preserve the evidence needed for another replay.
+
+## Content-refresh acceptance
+
+Reviewers checked the article's file digest rather than treating a commit SHA as a content digest.
+Accepted article SHA-256: `10c533da43a4196e022b2dfe174344088e713213ca1d0237ed300880d17ddd62`.
+Independent article_review and brief_review accepted this digest and the corrections on 2026-10-05.
+Cross-Agent task completion remains unresolved under claim P08.

docs/editorial/portable-skills/SCREENSHOTS.md

@@ -0,0 +1,10 @@
+# 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.
+
+Capture layout evidence with task-named `dev-browser --headless`.
+Keep captures in `~/scratch/portable-skills/`.
+Check desktop at 1440px and mobile at 390px, including table and code overflow.
+Inspect pixels before reporting layout success. Never fabricate an interface image.
+Record source density, display width, caption and alt text before introducing future figures.

docs/editorial/portable-skills/SOURCES.md

@@ -0,0 +1,19 @@
+# Sources
+
+Checked 5 October 2026. Prefer current primary documentation over announcements.
+Search results discover sources; they do not verify claims.
+
+| Authority | Exact source | Scope and limit |
+| --- | --- | --- |
+| Agent Skills | https://agentskills.io/specification | Format, naming and references. No identical Agent behavior guarantee. |
+| Agent Skills | https://agentskills.io/skill-creation/quickstart | Terminal-based dice example and selection limits. Not an instruction-only trial. |
+| Anthropic | https://code.claude.com/docs/en/skills | Claude Code discovery, invocation and extensions. |
+| [OpenAI](https://openai.com) | https://learn.chatgpt.com/docs/build-skills | Codex local discovery. Not every [ChatGPT](https://chatgpt.com) surface. |
+| Google | https://geminicli.com/docs/cli/skills/ | Gemini CLI discovery aliases and management. |
+| skilld | https://github.com/skilld-dev/skilld/tree/main/skills | Authoring Skills. Inspection does not prove an Agent run. |
+| Google Search Central | https://developers.google.com/search/docs/crawling-indexing/links-crawlable | Crawlable anchors, descriptive text and contextual internal links. No promised ranking gain. |
+
+Discovery: follow documentation links. Reopen changeable claims before publication.
+NuxtSEO 0.5.3, Site `s_08aae654`, US locale `2840`, research date 2026-10-05.
+Provider estimates do not promise traffic or ranking.
+Records under `docs/editorial/` sit outside collection roots in `layers/marketing/content/`.