Skip to content

Commit 8947f82

Browse files
LancernLancern
committed
chore: create an agent skill for migrating cppreference pages
1 parent d0ef04f commit 8947f82

File tree

3 files changed

+153
-0
lines changed

3 files changed

+153
-0
lines changed

‎.agents/skills/migrate-cppref-page/SKILL.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
name: migrate-cppref-page
3+
description: Migrate a requested cppreference page into this cppdoc repository. Use when the user asks to port a specific cppreference slug or URL such as `cpp/memory` into `src/content/docs`, preserving technical meaning while rewriting the page into CppDoc MDX with existing components, revision metadata, and internal links.
4+
---
5+
6+
# Migrate Cppref Page
7+
8+
Migrate one cppreference page into the local `cppdoc` checkout.
9+
10+
Resolve the destination from `migrate/slug_map.json`, study nearby migrated pages, then write or update the corresponding MDX page under `src/content/docs`.
11+
12+
## Workflow
13+
14+
1. Parse the requested cppreference page slug or URL.
15+
2. Read [`references/workflow.md`](./references/workflow.md).
16+
3. Find the destination slug in `migrate/slug_map.json`.
17+
4. Stop and ask the user if the slug map entry is missing or `null`.
18+
5. Fetch or read the cppreference source page, then inspect existing cppdoc pages in the same area before writing anything.
19+
6. Create or update the target MDX page with repo-native structure and components.
20+
7. Run `npm run format` after editing files.
21+
22+
## Working Rules
23+
24+
- Treat this as a repo migration task, not a literal HTML-to-MDX transcription task.
25+
- Preserve technical meaning, declarations, examples, headings, notes, and revision distinctions from cppreference.
26+
- Prefer the layout and phrasing patterns already used by neighboring cppdoc pages over mechanically copying cppreference markup.
27+
- Use existing CppDoc components instead of raw HTML whenever a matching component exists.
28+
- If no matching component exists, think whether a new component is valuable and ask the user whether to create it.
29+
- Keep imports minimal and consistent with current files in the destination area.
30+
- Keep each prose paragraph on a single source line when practical.
31+
- Use double quotes and explicit semicolons in any TypeScript or JavaScript edits.
32+
- Leave `_meta.yml` alone unless a missing section label makes the new page unreachable or inconsistent.
33+
34+
## Destination And Source
35+
36+
- Resolve the CppDoc slug from `migrate/slug_map.json`. If you cannot find the corresponding CppDoc slug in this JSON file, stop and ask the user to update the slug map before proceeding.
37+
- Write the page to `src/content/docs/<cppdoc-slug>.mdx`.
38+
- If the user gives a slug like `cpp/memory`, infer the source URL as `https://en.cppreference.com/w/cpp/memory.html`.
39+
- If web access is unavailable, ask the user for the source page contents or a local artifact instead of guessing.
40+
41+
## Page Construction
42+
43+
- Start from a clean frontmatter block with `title`.
44+
- Add `cppdoc.revision` when the whole page is bounded by a language revision range.
45+
- Reuse established components such as `DocLink`, `DeclDoc`, `Decl`, `DescList`, `Desc`, `ParamDocList`, `ParamDoc`, `Revision`, `RevisionBlock`, `CHeader`, `CppHeader`, `Missing`, and `Incomplete` where appropriate.
46+
- Prefer `DocLink` for internal cross references and convert cppreference links to absolute cppdoc destinations.
47+
- Avoid native HTML tables and other raw layout tags unless no existing component or simple Markdown structure can express the content.
48+
- Mark intentionally unmigrated targets with `Missing` rather than inventing destinations.
49+
- Keep examples, return values, notes, and see-also sections when they materially help readers.
50+
51+
## Validation
52+
53+
- Check that the destination file path matches the slug map entry.
54+
- Check imports for unused or missing components.
55+
- Check revision annotations at both page level and block level.
56+
- Check that internal links point to plausible cppdoc paths.
57+
- Run `npm run format`.
58+
- Report any unresolved mapping gaps, missing components, or source ambiguities in the final response.

‎.agents/skills/migrate-cppref-page/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Migrate Cppreference Page"
3+
short_description: "Migrate one cppreference page into cppdoc"
4+
default_prompt: "Use $migrate-cppref-page to migrate the cppreference page `cpp/memory` into this cppdoc checkout."

‎.agents/skills/migrate-cppref-page/references/workflow.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Workflow Reference
2+
3+
## Quick checklist
4+
5+
1. Resolve the requested cppreference slug or URL.
6+
2. Look up the destination slug in `migrate/slug_map.json`.
7+
3. Open the destination directory under `src/content/docs`.
8+
4. Read 2-3 nearby migrated pages to copy local structure and tone.
9+
5. Read the migration and component guides that matter for the page shape.
10+
6. Fetch the cppreference source page.
11+
7. Write the MDX page.
12+
8. Format the repo with `npm run format`.
13+
14+
## Commands
15+
16+
Resolve a slug quickly:
17+
18+
```bash
19+
node -e 'const m=require("./migrate/slug_map.json"); console.log(JSON.stringify(m.find(x => x.cppref === "cpp/memory"), null, 2));'
20+
```
21+
22+
Inspect nearby migrated pages:
23+
24+
```bash
25+
rg --files src/content/docs/cpp/library/memory
26+
rg --files src/content/docs/cpp/library | rg "memory|utility|allocator"
27+
```
28+
29+
Read the most relevant guidance first:
30+
31+
- `src/content/docs/development/migration/guideline.mdx`
32+
- `src/content/docs/development/guide/doc-everything.mdx`
33+
- `src/content/docs/development/guide/revision.mdx`
34+
- `src/content/docs/development/guide/component-docs-for-llm.mdx`
35+
36+
## Path rules
37+
38+
- `c/...` source pages usually map into `src/content/docs/c/...`.
39+
- `cpp/language/...` source pages map into `src/content/docs/cpp/language/...`.
40+
- `cpp/...` library pages often map into `src/content/docs/cpp/library/...`.
41+
- Trust `migrate/slug_map.json` over intuition whenever they differ.
42+
43+
## Writing rules
44+
45+
- Preserve semantics, not cppreference HTML structure.
46+
- Follow existing cppdoc wording and section ordering in neighboring pages.
47+
- Use `DocLink` for internal references.
48+
- Prefer CppDoc components over raw HTML.
49+
- Keep imports explicit and minimal.
50+
- Keep paragraphs single-line where practical.
51+
52+
## Component hints
53+
54+
- Use `DeclDoc` and `Decl` for declarations and syntax forms.
55+
- Use `ParamDocList` for parameter lists.
56+
- Use `DescList` for grouped facilities, overload families, and see-also entries.
57+
- Use `Revision` or `RevisionBlock` when only part of the page changes across standards.
58+
- Use `CHeader` or `CppHeader` for header mentions.
59+
- Use `Missing` for not-yet-migrated internal targets.
60+
61+
## Frontmatter hints
62+
63+
Minimum:
64+
65+
```mdx
66+
---
67+
title: Page Title
68+
---
69+
```
70+
71+
Add page-wide revision metadata only when the whole page is constrained:
72+
73+
```mdx
74+
---
75+
title: Page Title
76+
cppdoc:
77+
revision:
78+
lang: C++
79+
since: C++11
80+
until: C++20
81+
---
82+
```
83+
84+
## Stop conditions
85+
86+
Stop and ask the user when:
87+
88+
- the slug map entry is missing or `null`
89+
- the source page cannot be fetched and no local artifact is available
90+
- the correct destination area is ambiguous
91+
- a required component or pattern does not exist in the repo

0 commit comments

Comments
 (0)