From d4cf6810512aa21a7a41404cc355f0c482d9a893 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 4 May 2026 14:29:08 -0400 Subject: [PATCH 1/2] add cross-references skill --- .claude/skills/cross-references/SKILL.md | 77 ++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 .claude/skills/cross-references/SKILL.md diff --git a/.claude/skills/cross-references/SKILL.md b/.claude/skills/cross-references/SKILL.md new file mode 100644 index 000000000..9e537388d --- /dev/null +++ b/.claude/skills/cross-references/SKILL.md @@ -0,0 +1,77 @@ +--- +name: cross-references +description: > + TRIGGER when: documenting new functionality — whether on a new page or as new behavior added + to an existing page. Examples: a new feature gets its own page; an existing page gains a new + setting, mode, or capability; a feature has touchpoints in other product areas (dashboard + settings, search behavior, AI scope, etc.). Also trigger when the user asks "where else + should this be linked?", "how do I cross-reference X?", or "make sure this is covered in + ". + DO NOT TRIGGER for: copy edits, restructures that don't add functionality, link URL fixes + (use the `links` skill), or content with no related touchpoints elsewhere. +--- + +# Cross-referencing pages + +When new functionality is documented — whether on a new page or as new behavior added to an existing page — related pages elsewhere in the docs usually need pointers to it. Without those pointers, the canonical content is hard to discover from the angles a reader is most likely to come in from. + +## Pick a canonical home, reference from elsewhere + +One page owns the full explanation; every other page that touches the topic links *to* it rather than restating it. + +- Walkthroughs, setup steps, and concept explanations live on the canonical page. +- Reference pages get a sentence + link, not a paragraph of duplicated detail. +- If you find yourself copying more than a sentence or two into a reference page, the content probably belongs on the canonical page (or in a shared section). + +## Find the targets + +Whenever you add new functionality, sweep the docs for related touchpoints before assuming you're done: + +```bash +grep -rln "\|" fern/products --include="*.mdx" +``` + +Then read each candidate to find the natural insertion point. Common targets: + +- **Behavior pages** — e.g., a feature affects search → cross-link from `customization/search.mdx`. +- **Dashboard pages** — e.g., a feature has dashboard settings → cross-link from `dashboard/pages/`. +- **Adjacent feature pages** — e.g., Ask Fern, RBAC, localization, when scope or behavior overlaps. +- **Overview / landing pages** — sometimes a card on a hub page is warranted; usually only when the feature is a top-level setup step, not a configuration detail. + +## Pick the form + +| Form | Use when | +|------|----------| +| Inline sentence in an existing paragraph | The reference fits a list of similar items already on the page (e.g., "for sites with X, Y, or [new thing]"). | +| `` callout | The reference is a real but secondary consideration that would distract from the main flow if inlined. | +| New section (`##`) | The target page genuinely needs to document the feature from its own angle (e.g., dashboard config for the feature). | +| New page | Only if the feature has substantial standalone content that doesn't fit elsewhere. | + +Default to the lightest form that works. New pages and new sections add maintenance surface; inline sentences and Notes don't. + +## Bidirectional links + +Reference pages always link *to* canonical. Linking back from canonical to a reference page is optional — only do it when the reference page has additional detail the canonical page doesn't cover (e.g., dashboard click-paths). Most cross-references are one-way. + +## Anchor links: heading-only + +Internal anchors only resolve for `##` / `###` headings. Things that look like headings but aren't: + +- `` inside `` — JSX prop, no anchor generated. +- ``, ``, `` — same. + +If you want to deep-link to a step or tab, add a real `##` heading nearby, or link to the page without an anchor and let the reader scroll. + +## Constructing the link itself + +For the URL syntax (slugs, `/learn/...` paths, internal-link rules), use the `links` skill. + +## Sweep checklist + +After documenting any new functionality, before declaring the work done: + +1. Grep for the feature/setting name and 1–2 related keywords across `fern/products/**/*.mdx`. +2. For each hit on a different page, decide: is a cross-reference warranted? +3. For each warranted cross-ref, pick the lightest form that fits. +4. If the functionality has dashboard settings, verify `fern/products/dashboard/pages/` covers them — usually folded into the most relevant existing page, not a new page. +5. Verify every link you wrote (slug correct, anchor exists if used). From c030c5cf49dd9f76a0e652f3d6604f254c4fb38f Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 14 May 2026 11:55:24 -0400 Subject: [PATCH 2/2] integrate cross references skill into agents.md --- .claude/skills/cross-references/SKILL.md | 77 ------------------------ AGENTS.md | 71 ++++++++++++++++++++++ 2 files changed, 71 insertions(+), 77 deletions(-) delete mode 100644 .claude/skills/cross-references/SKILL.md diff --git a/.claude/skills/cross-references/SKILL.md b/.claude/skills/cross-references/SKILL.md deleted file mode 100644 index 9e537388d..000000000 --- a/.claude/skills/cross-references/SKILL.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -name: cross-references -description: > - TRIGGER when: documenting new functionality — whether on a new page or as new behavior added - to an existing page. Examples: a new feature gets its own page; an existing page gains a new - setting, mode, or capability; a feature has touchpoints in other product areas (dashboard - settings, search behavior, AI scope, etc.). Also trigger when the user asks "where else - should this be linked?", "how do I cross-reference X?", or "make sure this is covered in - ". - DO NOT TRIGGER for: copy edits, restructures that don't add functionality, link URL fixes - (use the `links` skill), or content with no related touchpoints elsewhere. ---- - -# Cross-referencing pages - -When new functionality is documented — whether on a new page or as new behavior added to an existing page — related pages elsewhere in the docs usually need pointers to it. Without those pointers, the canonical content is hard to discover from the angles a reader is most likely to come in from. - -## Pick a canonical home, reference from elsewhere - -One page owns the full explanation; every other page that touches the topic links *to* it rather than restating it. - -- Walkthroughs, setup steps, and concept explanations live on the canonical page. -- Reference pages get a sentence + link, not a paragraph of duplicated detail. -- If you find yourself copying more than a sentence or two into a reference page, the content probably belongs on the canonical page (or in a shared section). - -## Find the targets - -Whenever you add new functionality, sweep the docs for related touchpoints before assuming you're done: - -```bash -grep -rln "\|" fern/products --include="*.mdx" -``` - -Then read each candidate to find the natural insertion point. Common targets: - -- **Behavior pages** — e.g., a feature affects search → cross-link from `customization/search.mdx`. -- **Dashboard pages** — e.g., a feature has dashboard settings → cross-link from `dashboard/pages/`. -- **Adjacent feature pages** — e.g., Ask Fern, RBAC, localization, when scope or behavior overlaps. -- **Overview / landing pages** — sometimes a card on a hub page is warranted; usually only when the feature is a top-level setup step, not a configuration detail. - -## Pick the form - -| Form | Use when | -|------|----------| -| Inline sentence in an existing paragraph | The reference fits a list of similar items already on the page (e.g., "for sites with X, Y, or [new thing]"). | -| `` callout | The reference is a real but secondary consideration that would distract from the main flow if inlined. | -| New section (`##`) | The target page genuinely needs to document the feature from its own angle (e.g., dashboard config for the feature). | -| New page | Only if the feature has substantial standalone content that doesn't fit elsewhere. | - -Default to the lightest form that works. New pages and new sections add maintenance surface; inline sentences and Notes don't. - -## Bidirectional links - -Reference pages always link *to* canonical. Linking back from canonical to a reference page is optional — only do it when the reference page has additional detail the canonical page doesn't cover (e.g., dashboard click-paths). Most cross-references are one-way. - -## Anchor links: heading-only - -Internal anchors only resolve for `##` / `###` headings. Things that look like headings but aren't: - -- `` inside `` — JSX prop, no anchor generated. -- ``, ``, `` — same. - -If you want to deep-link to a step or tab, add a real `##` heading nearby, or link to the page without an anchor and let the reader scroll. - -## Constructing the link itself - -For the URL syntax (slugs, `/learn/...` paths, internal-link rules), use the `links` skill. - -## Sweep checklist - -After documenting any new functionality, before declaring the work done: - -1. Grep for the feature/setting name and 1–2 related keywords across `fern/products/**/*.mdx`. -2. For each hit on a different page, decide: is a cross-reference warranted? -3. For each warranted cross-ref, pick the lightest form that fits. -4. If the functionality has dashboard settings, verify `fern/products/dashboard/pages/` covers them — usually folded into the most relevant existing page, not a new page. -5. Verify every link you wrote (slug correct, anchor exists if used). diff --git a/AGENTS.md b/AGENTS.md index 0e4c68ecf..2951e9e68 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -88,6 +88,77 @@ The correct link is: - **Same-page anchors**: `#section-name` — these don't need a full path. - **Anchors on internal links**: `/learn/docs/config/navigation#section-availability` — append `#anchor` to the URL path. +## Cross-referencing + +When new functionality is documented — whether on a new page or as new behavior added to an existing page — related pages elsewhere in the docs usually need pointers to it. Without those pointers, the canonical content is hard to discover from the angles a reader is most likely to come in from. + +### Pick a canonical home + +One page owns the full explanation; every other page that touches the topic links *to* it rather than restating it. + +- Walkthroughs, setup steps, and concept explanations live on the canonical page. +- Reference pages get a sentence + link, not a paragraph of duplicated detail. +- If you find yourself copying more than a sentence or two into a reference page, the content probably belongs on the canonical page. + +### Find the targets + +Sweep the docs for related touchpoints before assuming you're done: + +```bash +grep -rln "\|" fern/products --include="*.mdx" +``` + +Then read each candidate to find the natural insertion point. Common targets: + +- **Behavior pages** — e.g., a feature affects search → cross-link from `customization/search.mdx`. +- **Dashboard pages** — e.g., a feature has dashboard settings → cross-link from `dashboard/pages/`. +- **Adjacent feature pages** — e.g., Ask Fern, RBAC, localization, when scope or behavior overlaps. +- **Overview / landing pages** — sometimes a card on a hub page is warranted; usually only when the feature is a top-level setup step, not a configuration detail. + +### Pick the form + +| Form | Use when | +|------|----------| +| Inline sentence in an existing paragraph | The reference fits a list of similar items already on the page (e.g., "for sites with X, Y, or [new thing]"). | +| `` callout | The reference is a real but secondary consideration that would distract from the main flow if inlined. | +| New section (`##`) | The target page genuinely needs to document the feature from its own angle (e.g., dashboard config for the feature). | +| New page | Only if the feature has substantial standalone content that doesn't fit elsewhere. | + +Default to the lightest form that works. New pages and new sections add maintenance surface; inline sentences and Notes don't. + +### Frame by function, not by plumbing + +Lead the cross-reference with what each feature *does* and how they complement or differ. Don't headline the connection with shared config infrastructure — same YAML key, sibling files in the same directory, same lifecycle. + +- Good: "X decides A; Y decides B." Contrast on function. +- Bad: "Y is also configured under the same `agents` key." Contrast on plumbing. + +If the only thing linking two features is that they live in the same key, that's not a cross-reference worth writing. Config mechanics belong on the page that is itself about configuration. + +### Bidirectional links + +Reference pages always link *to* canonical. Linking back from canonical to a reference page is optional — only do it when the reference page has additional detail the canonical page doesn't cover (e.g., dashboard click-paths). Most cross-references are one-way. + +### Anchor links + +Internal anchors only resolve for `##` / `###` headings. Things that look like headings but aren't: + +- `` inside `` — JSX prop, no anchor generated. +- ``, ``, `` — same. + +If you want to deep-link to a step or tab, add a real `##` heading nearby, or link to the page without an anchor and let the reader scroll. + +### Sweep checklist + +After documenting any new functionality, before declaring the work done: + +1. Grep for the feature/setting name and 1–2 related keywords across `fern/products/**/*.mdx`. +2. For each hit on a different page, decide: is a cross-reference warranted? +3. For each warranted cross-ref, pick the lightest form that fits. +4. Frame each cross-ref by what each feature does, not by shared config keys or directory structure. +5. If the functionality has dashboard settings, verify `fern/products/dashboard/pages/` covers them — usually folded into the most relevant existing page, not a new page. +6. Verify every link you wrote — see *Link checking* above for URL construction. + ## Changelog entries Changelog entries live in `fern/products/docs/pages/changelog/` and `fern/products/dashboard/pages/changelog/`. Filename format: `YYYY-MM-DD.mdx`.