Split tutorial workflow and writing style skills

.agents/skills/bpf-tutorial-writing-style/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: bpf-tutorial-writing-style
+description: Repository-local writing-style and bilingual review checklist for advanced bpf-developer-tutorial lessons. Use when drafting, rewriting, translating, or reviewing tutorial README.md and README.zh.md files, especially when matching the voice and code-first structure of lessons 47-cuda-events and 49-hid without losing technical facts, code, commands, evidence, caveats, or references.
+---
+
+# BPF Tutorial Writing Style
+
+Apply this Skill as the single source of truth for tutorial prose and presentation. It contains style rules only. Use `$write-bpf-production-tutorial` for implementation, evidence, model review, KVM, PR, and CI workflow.
+
+## Read the rulebooks
+
+Read all three references before drafting or reviewing an advanced lesson:
+
+1. [Advanced tutorial guidelines](references/advanced-tutorial-guidelines.md) preserves the complete project-provided requirements.
+2. [Repository house style](references/repository-house-style.md) defines how new lessons should match `47-cuda-events` and `49-hid` while avoiding their legacy defects.
+3. [Prose and bilingual checklist](references/prose-and-bilingual-checklist.md) carries the applicable eunomia.dev prose discipline into this repository.
+
+Treat verified implementation facts, real runtime evidence, and the user's current requirements as authoritative. Never change code, commands, output, versions, claims, qualifiers, failure behavior, or limitations to make prose smoother. When an older precedent conflicts with verified facts or the current rulebooks, preserve the facts and use only the precedent's useful teaching style.
+
+## Apply the final gate
+
+Reject a draft until it satisfies every non-diagnostic rule in the three references. Report each failure with the file, heading, smallest useful excerpt, reason, and a targeted correction. Never rewrite a whole section during review when a paragraph-level fix is enough.
+
+Paragraph length ranges are diagnostics, not quotas. A rule marked **Must fix** blocks acceptance. Preserve English and Chinese macro structure, facts, code, commands, output, examples, limitations, and references, but compose each language naturally rather than translating line by line.

.agents/skills/bpf-tutorial-writing-style/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "BPF Tutorial Writing Style"
+  short_description: "Check advanced eBPF tutorial prose and structure"
+  default_prompt: "Use $bpf-tutorial-writing-style to draft or review this advanced eBPF tutorial in the repository house style."

.agents/skills/bpf-tutorial-writing-style/references/advanced-tutorial-guidelines.md

@@ -0,0 +1,81 @@
+# Blog Guidelines for Advanced eBPF Tutorials
+
+This document outlines the key patterns and requirements for writing advanced eBPF tutorials. Advanced tutorials focus on complex eBPF programs, tools, or features that extend beyond basic concepts. They require a deeper understanding of eBPF and kernel interactions.
+
+The audience for advanced tutorials includes developers, system administrators, and security professionals with intermediate to advanced eBPF knowledge. The goal is to provide in-depth explanations of advanced eBPF topics and practical examples that readers can apply in real-world scenarios.
+
+The key point in tone: Using oral English, clear and simple words and short sentence, make it attractive and easy to read, do not make it like a paper. Not too much fancy words, try to be attracive.
+
+You should also include all the details and information I provide to you. do not simplify or change any of them, you just need to regorganize them in a more attractive way as a tutorial blog.
+
+## starting with a clear and descriptive title
+
+Begin with a clear and descriptive title:
+
+```
+# eBPF Tutorial by Example: [Advanced Topic]
+```
+
+Kick off with a brief intro to the advanced eBPF topic you're covering, and the example or tool you'll discuss. Highlight its significance and how it extends beyond basic concepts. Let readers know what they'll learn and why it's important.
+
+## Incroduction to the concept, tool and Background
+
+(Come up with a better session title)
+
+Provide an overview of the specific eBPF programs, tools, or features you'll discuss. Explain their purpose, use cases, and the key eBPF features or kernel events involved. Focus on aspects that are crucial for advanced understanding.
+
+## High-Level Code Analysis
+
+Dive into the kernel-mode eBPF code and user-space code, focusing on high-level concepts rather than basic syntax.
+
+Always include the full code as it is first. then break down the key parts.
+
+Try to avoid using too much list, make it more like a story.
+
+Follow the steps:
+
+1. First, introduce The overall processing logic in both kernel and user space.
+2. Then break down the kernel-mode eBPF code, include
+
+- How the eBPF program is structured.
+- Key eBPF functionalities utilized.
+- How the code interacts with kernel events.
+
+Do not make them a list, make them some paragraphs, you can also quote some code snippets to explain the key parts of the code if needed, focus on the logic and features used in advanced eBPF development. Don't make it too long, but make sure it is informative enough and you explain everything a advanced eBPF developer wants to know.
+
+3. Then briefly explain the user-space code
+
+Aim to help readers grasp how the code works without getting bogged down in basic details.
+
+## Any more detailed concepts or features explanation
+
+If there are other information or features that are important to understand the code, you can add them here.
+
+## 5. Compilation and Execution
+
+Provide instructions on compiling and running the eBPF programs, noting any advanced configurations or dependencies. Include commands and what readers should expect as output. Typically, you can run `make` in the relevant directory in the tutorial repository to build the code.
+
+Include links to complete source code and resources:
+
+- **Repository:** <https://github.com/eunomia-bpf/bpf-developer-tutorial>
+- **Website:** <https://eunomia.dev/tutorials/>
+
+## 6. Summary and Call to Action
+
+Wrap up by summarizing the key points. Emphasize the advanced concepts covered and encourage readers to apply this knowledge. Invite them to explore more examples and tutorials, as one paragraph:
+
+> If you'd like to dive deeper into eBPF, check out our tutorial repository at <https://github.com/eunomia-bpf/bpf-developer-tutorial> or visit our website at <https://eunomia.dev/tutorials/>.
+
+## reference
+
+You should include the important references and resources that used in the tutorial. If this is from other sources like kernel sample or tools, make sure to include them here and clearly mention them in the tutorial.
+
+## Additional Guidelines
+
+- **Clarity:** Use simple language and short sentences to explain complex ideas. But the information should be complete and detailed.
+- **Focus on Advanced Concepts:** Assume readers have basic eBPF knowledge; skip elementary explanations.
+- **Engagement:** Encourage readers to think critically and engage with the material.
+- **Consistency:** Keep a consistent style and formatting throughout.
+- **Code Formatting:** Ensure code snippets are well-formatted and highlight key parts. Do not change or simplify any of the code and commands, keep them as they are.
+- **Proofreading:** Double-check for errors and ensure technical accuracy.
+- **Accessibility:** Make the content valuable for readers with advanced expertise, avoiding unnecessary simplifications.

.agents/skills/bpf-tutorial-writing-style/references/prose-and-bilingual-checklist.md

@@ -0,0 +1,64 @@
+# Prose and bilingual checklist
+
+This checklist carries the relevant eunomia.dev writing discipline into advanced eBPF tutorials. It is self-contained and does not depend on a global or external Skill.
+
+## Fidelity is the first gate
+
+- **Must fix:** Any code, command, captured output, number, version, requirement, limitation, negative result, cleanup behavior, reference, or scope-bearing qualifier from the supplied material is missing or changed.
+- Preserve technical names and project names. Do not replace them with vague pronouns across paragraphs.
+- Treat numbers as claims. State what was measured, under which conditions, and what the result does or does not prove.
+- Avoid absolute words such as “always,” “never,” “cannot,” and “impossible” unless the implementation or a primary source proves the boundary.
+- Do not invent output, benchmark numbers, PIDs, paths, errors, production uses, or performance conclusions.
+- Reorganize for teaching, but do not simplify away technical information. During a rewrite, compare the final text against the entry version from the end backwards and account for every removed paragraph.
+
+## Voice and argument
+
+- Use oral, direct English with familiar words and short connected sentences. Write as an experienced developer explaining a working tool, not as a paper, merge report, release note, or test log.
+- Open with the real problem or a concrete scenario. Avoid “In this tutorial, we will explore,” generic eBPF history, product promotion, and an abstract-style contribution list.
+- Let each section answer the question raised by the previous one. A useful progression is problem, background, whole-system flow, complete code, focused walkthrough, deeper concept, compilation and execution, limits, summary, and references.
+- Give each paragraph one primary job. If a paragraph establishes context, explains a mechanism, reports evidence, and states a limitation at once, split it.
+- Prefer active voice and concrete actors. Name the hook, BPF program, map, callback, loader, fixture, command, or kernel rather than using “it,” “this,” “the approach,” or “the result.”
+- Replace spec-sheet prose with causal explanation. If three neighboring sentences can be reordered without changing the paragraph, connect each fact to what it enables or why it matters.
+- Avoid fancy or promotional words, clickbait, exclamation marks, vague superlatives, hollow calls to action, and self-praise. Attraction should come from a concrete problem and a mechanism the reader can reuse.
+- Do not overuse lists. Use prose for the implementation story and lists only when parallel items become easier to scan.
+
+## Paragraph and sentence checks
+
+- English paragraphs usually work best at 40–90 words. Inspect every paragraph above 110 words. Three consecutive paragraphs above 90 words are **Must fix**.
+- Chinese paragraphs usually work best at 120–260 Chinese characters. Inspect every paragraph above 320 characters. Three consecutive paragraphs above 260 characters are **Must fix**.
+- The ranges are diagnostic tripwires, not quotas. Short transitions and longer indivisible mechanism explanations are allowed.
+- Keep a sentence's subject near its verb. Split long modifiers, dangling introductions, and sentences that make the reader hold several clauses before reaching the action.
+- Avoid weak openings such as “It is,” “There is,” and “This is” when a concrete subject is available.
+- Do not stack three or more short note-like sentences. Connect cause, mechanism, and consequence.
+- Cut filler such as “in order to,” “utilize,” “it is important to note that,” “due to the fact that,” “in terms of,” and “with respect to.” Prefer direct verbs.
+- Do not use spaced English em dashes (` — `) or Chinese em dashes (`——`) in prose.
+- Do not join independent clauses with semicolons. Use two sentences or a conjunction.
+- Use colons only to introduce a list, code block, or table. Rewrite claim-colon-evidence and Chinese noun-phrase-colon openings as sentences.
+
+## Code and evidence presentation
+
+- Present full core source exactly as it exists before excerpting it again for explanation. Never silently shorten functions, replace blocks with ellipses, translate comments, or “clean up” commands.
+- Introduce each complete file with its role in the kernel/user-space flow. After the file, select only the parts that need deeper explanation.
+- Explain what advanced developers need to know: program type, attach point, context restrictions, helper or kfunc semantics, map ownership, state lifetime, concurrency, verifier constraints, event/control path, error handling, and cleanup.
+- Keep build and run commands copyable. Explain prerequisites before the command and interpret real output after it.
+- Label volatile fields and distinguish demonstrations, functional tests, and benchmarks.
+
+## Natural Chinese
+
+- Compose Chinese from the facts and paragraph role, not from English sentence order. The two languages may use different sentence and paragraph boundaries.
+- Translate ordinary concept nouns consistently. Keep proper nouns, product names, code, commands, file names, function names, and genuine terms of art in English.
+- Do not begin a Chinese prose sentence with an English common noun. Avoid English clause splicing and glossary-style prose where every other concept stays in English.
+- Use full-width Chinese punctuation. Put a half-width space between CJK text and Latin letters or digits, such as “64 个事件” and “eBPF 程序.”
+- Write table headings in Chinese. Translate ordinary prose inside comments only when the code block is illustrative; when the block claims to be complete source, preserve it byte-for-byte in both languages.
+- Read every Chinese paragraph aloud. Rewrite literal translations, English word order, and stiff phrases that a developer would not use in conversation.
+
+## Bilingual consistency
+
+- Keep the same macro structure, examples, complete code payload, commands, output, claims, numbers, caveats, limitations, summary, and references in both files.
+- Corresponding headings should promise the same content, but they do not need literal translations.
+- A near-perfect line-for-line prose translation is a review smell. Confirm that each language reads naturally even when that changes sentence or paragraph boundaries.
+- When one version changes a fact, example, figure, command, code block, output, or limitation, update the other in the same pass.
+
+## Final reader check
+
+After reading in order, an intermediate or advanced eBPF developer should be able to explain the real problem, the kernel/user-space flow, why the advanced capability is needed, how the core code works, how to build and run it, what the captured output proves, and where the example stops. If the reader remembers only a feature name or a validation transcript, revise the narrative.

.agents/skills/bpf-tutorial-writing-style/references/repository-house-style.md

@@ -0,0 +1,33 @@
+# Repository house style
+
+New advanced lessons must feel like they belong beside `src/47-cuda-events/` and `src/49-hid/`. Read both English/Chinese README pairs in full before drafting. Use `47-cuda-events` as the depth baseline for an end-to-end tool and `49-hid` as the voice and code-first teaching baseline.
+
+## Match the useful patterns
+
+- Start with a concrete situation the reader can picture. Address the reader directly when it sounds natural, then name the tool and what the reader will learn.
+- Give enough subsystem background to make the advanced mechanism understandable. Assume basic eBPF knowledge, so skip generic definitions of maps, CO-RE, or the verifier unless the lesson depends on a non-obvious property.
+- Introduce the whole kernel/user-space path before walking through individual functions. Keep returning to the same example so the lesson reads as one story.
+- Present the complete kernel-mode eBPF source and complete user-space source exactly as implemented before the detailed walkthrough. Include a shared header when understanding the event or control contract depends on it. Link test fixtures and build files instead of reproducing them unless they are part of the teaching mechanism.
+- After the complete source, explain the important BPF structure, helpers, maps, callbacks or hooks, kernel event interaction, user-space load/attach path, output processing, error handling, and cleanup. Explain basic C syntax only when it hides an eBPF-specific constraint.
+- Put compilation and execution after the concept and implementation walkthrough. Show exact commands, real output, prerequisites, and what the output means.
+- End with a compact summary and one invitation to the repository and tutorial website. Keep primary references in a dedicated final section.
+
+## Preserve modern correctness
+
+Use the precedents for voice and teaching order, not as permission to copy their weaknesses. New lessons must:
+
+- use only captured output and identify fields that vary across runs;
+- source version, performance, deployment, adoption, and upstream-history claims;
+- state minimum kernel, config, privilege, architecture, and hardware requirements;
+- explain at least one meaningful failure or boundary path and all relevant cleanup behavior;
+- distinguish a functional KVM run from a benchmark;
+- avoid unsupported claims such as “production-ready,” “safe,” “negligible,” or “complete visibility”;
+- use consistent Markdown, full-width Chinese punctuation, and spaces between CJK text and Latin letters or digits.
+
+## Keep the teaching narrative
+
+Prefer paragraphs over inventories. Use lists for CLI options, requirements, byte layouts, or genuinely parallel items. Do not turn the mechanism into an acceptance report with headings such as “Verified output,” “Test evidence,” or “Statistics” unless the result itself is the topic. Runtime proof should appear naturally in the compilation and execution section, followed by an explanation of what it proves.
+
+Keep exact operational details, but move low-level provenance such as commit and image hashes into the runtime-requirements or reproducibility discussion. Lead with what the tool does, not how its PR was validated.
+
+The English and Chinese versions must share the same title promise, section progression, complete code, commands, output, facts, caveats, summary, and references. Natural Chinese takes priority over sentence-for-sentence symmetry.

.agents/skills/write-bpf-production-tutorial/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: write-bpf-production-tutorial
-description: Create or revise bilingual bpf-developer-tutorial lessons as small, production-realistic eBPF tools with host builds, benchmark-kernel KVM tests, reproducible evidence, and mandatory independent cross-model prose review. Use when proposing, implementing, documenting, reviewing, or preparing a PR for a new eBPF tutorial, especially when deciding between numbered lessons, features, networking, security, or xpu/gpu placement.
+description: Run the repository-local workflow for proposing, implementing, verifying, documenting, reviewing, and preparing PRs for bilingual bpf-developer-tutorial lessons. Use for scope selection, host builds, benchmark-kernel KVM tests, reproducible evidence, author/reviewer provenance, and CI closure. Pair it with bpf-tutorial-writing-style for prose and bilingual style decisions.
 ---
 
 # Write BPF Production Tutorials
 
 Build a useful tool around a kernel capability. Do not publish a wrapper around an upstream selftest or a feature-only API tour.
 
+This Skill owns the writing process, not writing style. Invoke `$bpf-tutorial-writing-style` before drafting, rewriting, translating, or reviewing README prose. Never substitute a global Skill for the repository-local style Skill.
+
 ## Separate authorship from acceptance
 
 - Let Codex, a human, or another capable model author and revise the lesson. Treat model identity as provenance, not proof of quality.
@@ -29,7 +31,7 @@ Before coding, write one sentence naming:
 
 Reject proposals whose only result is “the program loaded,” “the helper returned success,” or “the upstream selftest passed.”
 
-Read [references/tutorial-acceptance.md](references/tutorial-acceptance.md) before selecting scope or placement. Read [references/repository-precedents.md](references/repository-precedents.md) and the selected precedent lessons in full before drafting. Read [references/writing-guide.md](references/writing-guide.md) before drafting. Read [references/review-checklist.md](references/review-checklist.md) before external review.
+Read [references/tutorial-acceptance.md](references/tutorial-acceptance.md) before selecting scope or placement. Read [references/repository-precedents.md](references/repository-precedents.md) and the required precedent lessons in full before drafting. Read [references/drafting-process.md](references/drafting-process.md) before creating the task file. Read [references/review-checklist.md](references/review-checklist.md) before external review. Read every reference required by `$bpf-tutorial-writing-style` before drafting and again before final review.
 
 ## Implement and verify
 
@@ -43,7 +45,7 @@ Read [references/tutorial-acceptance.md](references/tutorial-acceptance.md) befo
 
 ## Draft from evidence
 
-First write a precedent brief that names two or three existing bilingual lessons read in full, including one with the same operational shape. Use `src/47-cuda-events/README.md` and `README.zh.md` as a default precedent for a production tracer or accelerator tool. State which structural patterns to reuse, which legacy weaknesses to avoid, and why the new lesson has a distinct operational job. Do not draft until this brief exists.
+First write a precedent brief that confirms the required `47-cuda-events` and `49-hid` bilingual pairs were read in full, then names one additional lesson with the closest subsystem or operational shape when useful. State which teaching patterns to reuse, which legacy weaknesses to avoid, and why the new lesson has a distinct operational job. Do not draft until this brief exists.
 
 Create a task file outside the lesson with:
 
@@ -55,9 +57,10 @@ Create a task file outside the lesson with:
 - minimum kernel, libbpf, config, privilege, and hardware requirements;
 - primary upstream references;
 - the precedent brief and exact sibling README paths;
+- a source-fidelity ledger covering every fact, command, code file, captured-output block, requirement, failure path, cleanup behavior, limitation, and reference that must survive a rewrite;
 - facts or claims the author must not add.
 
-Draft or revise both README files from that evidence. The optional exact-Claude authoring path is:
+Draft or revise both README files from that evidence and the repository-local style Skill. Present the complete core BPF and user-space source before the detailed walkthrough as required by the advanced tutorial guidelines. The optional exact-Claude authoring path is:
 
 ```bash
 TUTORIAL_ROOT="$(git rev-parse --show-toplevel)"
@@ -72,7 +75,7 @@ The wrapper must finish with a verified exact-model trace. When another author w
 
 ## Run independent prose review
 
-Run a different model family read-only over the final files, implementation evidence, and the precedent READMEs named in the brief. Pass repository-relative paths with repeated `--file` arguments:
+Run a different model family read-only over the final files, implementation evidence, the two required style precedents, and any additional precedent named in the brief. The wrapper embeds both repository-local Skills and their rulebooks. Pass repository-relative paths with repeated `--file` arguments:
 
 ```bash
 TUTORIAL_ROOT="$(git rev-parse --show-toplevel)"
@@ -86,7 +89,9 @@ TUTORIAL_ROOT="$(git rev-parse --show-toplevel)"
   --file src/<lesson>/<tool>.c \
   --file src/<lesson>/tests/<test>.py \
   --file src/47-cuda-events/README.md \
-  --file src/47-cuda-events/README.zh.md
+  --file src/47-cuda-events/README.zh.md \
+  --file src/49-hid/README.md \
+  --file src/49-hid/README.zh.md
 ```
 
 Use `--reviewer glm` for the fixed OpenCode model `zai-coding-plan/glm-5.2`. Apply valid findings with targeted edits, diff-check both languages, rerun documented commands, and invoke an external reviewer again. The gate passes only when the final trace reports no valid Must-fix item.
@@ -96,4 +101,5 @@ Use `--reviewer glm` for the fixed OpenCode model `zai-coding-plan/glm-5.2`. App
 - Include only one lesson and the minimal generated index/compatibility changes.
 - Explain the production problem before the kernel feature in the PR body.
 - Report the host build, KVM positive test, negative/cleanup test, guest kernel provenance, documentation tests, author identity, review manifests, and finding dispositions.
+- Account for every item in the source-fidelity ledger and state that complete core source appears unchanged in both languages.
 - Follow the repository's review, Copilot, and monitored CI gates. Do not merge unless the user asks.

.agents/skills/write-bpf-production-tutorial/references/drafting-process.md

@@ -0,0 +1,25 @@
+# Tutorial drafting process
+
+Use this process after the tool and its runtime evidence are complete. `$bpf-tutorial-writing-style` owns all prose, structure, and bilingual rules.
+
+## Prepare immutable inputs
+
+Create a task file outside the lesson. Record the exact README paths the author may edit, intended reader, operational scenario, non-goals, code paths, CLI, verified host and guest commands, captured output, kernel provenance, requirements, primary sources, and forbidden claims.
+
+Add a source-fidelity ledger. Inventory every supplied fact, number, command, code file, output block, volatile field, version, config, privilege, failure path, cleanup behavior, limitation, and reference. A rewrite may move these items, but it may not remove or alter them.
+
+Add a code inventory that identifies the complete core files to reproduce in the tutorial. Include the kernel-mode eBPF source, user-space source, and any shared header needed to understand their contract. Keep tests, generated skeletons, vendored code, and build boilerplate as links unless the teaching mechanism depends on them.
+
+## Establish the teaching path
+
+Write one sentence for the tutorial's promise and one sentence for its reader. Map each planned section to a distinct reader question. Confirm that the path covers the problem, relevant background, whole-system flow, complete code, focused kernel explanation, brief user-space explanation, deeper concepts, compilation and execution, real output, requirements, failure and cleanup behavior, limitations, summary, and references.
+
+Do not draft until the precedent brief confirms that both `47-cuda-events` and `49-hid` English/Chinese pairs were read in full. Add the nearest subsystem lesson when it contributes a pattern that those two do not cover.
+
+## Draft and compare
+
+Draft English and Chinese from the same evidence ledger. Keep code, commands, and captured output identical. Compose prose independently in each language under `$bpf-tutorial-writing-style`.
+
+After the rewrite, compare each README with its entry version from the end backwards. Mark every removed paragraph as moved, rephrased with all facts intact, or intentionally excluded for a reason already authorized by the task. Restore any unaccounted technical content.
+
+Verify that every complete-source code block matches its repository file exactly. Then run the repository documentation generators, link checks, tests, and external review workflow.

.agents/skills/write-bpf-production-tutorial/references/repository-precedents.md

@@ -1,17 +1,30 @@
 # Repository tutorial precedents
 
-Read two or three existing English/Chinese README pairs in full before drafting. Select one lesson with the same operational shape and one with the same eBPF attachment or subsystem. Record the exact paths in a precedent brief.
+Read both required English/Chinese README pairs in full before drafting:
 
-## Default production-tool precedent
+- `src/47-cuda-events/README.md` and `src/47-cuda-events/README.zh.md`
+- `src/49-hid/README.md` and `src/49-hid/README.zh.md`
 
-Use `src/47-cuda-events/README.md` and `src/47-cuda-events/README.zh.md` as a default precedent for tracers and accelerator-facing tools. Reuse its useful scope:
+Select one additional lesson with the same operational shape or eBPF attachment when it adds a useful domain pattern. Record every exact path in a precedent brief.
+
+## Required advanced-tool precedents
+
+Use `47-cuda-events` as the end-to-end depth baseline. Reuse its useful scope:
 
 - identify a real workload and the operator-visible events;
 - connect the BPF hooks, shared event structure, ring buffer, user-space formatter, CLI, and fixture end to end;
 - include build and run commands, representative output, limitations, extension points, and primary references;
 - keep the complete source easy to find while explaining only the important excerpts.
 
-Do not inherit its legacy weaknesses. New lessons must show commands and verified evidence early, avoid generic eBPF or subsystem introductions, use only captured output, qualify volatile IDs and addresses, source every benchmark claim, keep English and Chinese macro structure aligned, and state requirements, negative behavior, and cleanup explicitly.
+Use `49-hid` as the approachable, code-first teaching baseline. Reuse its useful scope:
+
+- open with a concrete problem that gives the advanced feature a reason to exist;
+- explain enough subsystem background before implementation;
+- present complete source before walking through the important mechanisms;
+- explain kernel-mode code in depth and user-space orchestration more briefly;
+- put compilation, execution, expected output, experiments, summary, and references after the implementation story.
+
+Do not inherit either lesson's legacy weaknesses. New lessons must avoid generic eBPF history, excessive marketing language, stale or unsupported counts, invented output, unqualified volatile IDs and addresses, unsourced benchmark claims, inconsistent Chinese punctuation, exhaustive feature inventories, and missing requirements or cleanup. The repository-local style Skill defines the current house style when the precedents differ.
 
 ## Domain selection
 
@@ -25,10 +38,11 @@ Do not inherit its legacy weaknesses. New lessons must show commands and verifie
 
 Before prose, record:
 
-1. the exact README pairs read in full;
+1. confirmation that both required README pairs and any additional pair were read in full;
 2. two to four structural patterns to reuse;
 3. old weaknesses or irrelevant sections to avoid;
 4. the new lesson's distinct operational question;
-5. why the chosen depth fits this tool rather than copying a fixed template.
+5. the complete core source files that will appear before the walkthrough;
+6. why the chosen depth fits this tool rather than copying a fixed template.
 
 Give this brief to both the author and external reviewer. Repository continuity is a requirement, but an older lesson never overrides verified code, runtime evidence, or the current writing rules.

.agents/skills/write-bpf-production-tutorial/references/review-checklist.md

@@ -1,6 +1,6 @@
 # Independent tutorial review checklist
 
-Review the supplied snapshot without editing files or running commands. The author and reviewer must belong to different model families. The snapshot must include the precedent lessons named by the author; fail the process as incomplete if they are absent.
+Review the supplied snapshot without editing files or running commands. The author and reviewer must belong to different model families. The snapshot must include both required precedent pairs, any additional precedent named by the author, the process rulebooks, and the complete `$bpf-tutorial-writing-style` rulebooks. Fail the process as incomplete if any are absent.
 
 Classify every finding as **Must fix**, **Should fix**, or **Consider**. For each finding, name the file and line or heading, quote the smallest useful fragment, explain the problem, and propose a concrete correction. Do not rewrite entire sections.
 
@@ -10,12 +10,13 @@ Give explicit verdicts for:
 2. factual faithfulness to the implementation, KVM evidence, minimum versions, configs, privileges, limitations, and cleanup behavior;
 3. architecture, including the thesis, running scenario, section progression, and ending;
 4. reproducibility of every build, run, failure, and cleanup command;
-5. paragraph density, note-like prose, vague claims, invented output, and unsupported production claims;
-6. overlap with nearby lessons and whether the new lesson has a distinct operational job;
-7. English and Chinese agreement on headings, commands, examples, numbers, claims, and caveats;
-8. natural Chinese composition, terminology consistency, punctuation, and avoidance of line-locked translation.
+5. source-fidelity ledger coverage, including whether any fact, code, command, output, requirement, limitation, failure path, cleanup behavior, qualifier, or reference disappeared during rewriting;
+6. exact inclusion of the complete core kernel-mode, user-space, and required shared-header source before the detailed walkthrough;
+7. compliance with every repository-local writing-style checklist item, including oral English, repository voice, narrative flow, paragraph density, natural Chinese, punctuation, and avoidance of line-locked translation;
+8. overlap with nearby lessons and whether the new lesson has a distinct operational job;
+9. English and Chinese agreement on headings, code, commands, examples, output, numbers, claims, caveats, summary, and references.
 
-For the precedent verdict, distinguish legitimate repository continuity from copying. Confirm that the new lesson matches the selected examples' useful depth and end-to-end explanation while rejecting legacy weaknesses such as generic introductions, late commands, invented volatile output, unsupported benchmark claims, exhaustive feature inventories, or bilingual structure drift.
+For the precedent verdict, distinguish legitimate repository continuity from copying. Confirm that the new lesson matches `47-cuda-events` in useful depth and `49-hid` in approachable code-first teaching order while rejecting their legacy weaknesses. A validation-report structure that leads with CI, KVM provenance, or test statistics instead of the reader's problem is a style failure even when every fact is correct.
 
 Finish with a count by severity and exactly one final gate result:
 

.agents/skills/write-bpf-production-tutorial/references/writing-guide.md

@@ -1,49 +0,0 @@
-# BPF tutorial writing guide
-
-Write for developers who want to reproduce a small, useful eBPF tool. Use direct English and natural Chinese. Prefer short, connected sentences over academic prose, release-note inventories, or marketing claims.
-
-Before prose, write a private architecture brief with one thesis, the reader's operational goal, the unique angle relative to nearby lessons, non-goals, a running scenario, and the role of each section. Also write the precedent brief required by `repository-precedents.md`. Build a progression from the operational problem through the mechanism and measured evidence to a practical boundary. Do not mirror an upstream selftest or kernel merge note.
-
-## Required narrative
-
-1. Open with a production incident or operational task the reader recognizes. Explain the consequence and the signal the tool will expose or control.
-2. Show the command and verified result early. Do not begin with a generic definition of eBPF.
-3. Explain the end-to-end flow from workload to hook, maps or kfuncs, user-space processing, and final output.
-4. Present complete source when it stays readable. Otherwise use copyable 15–40 line excerpts and link to the complete lesson.
-5. Explain only the kernel mechanisms needed to understand the tool. State minimum kernel/libbpf versions, configs, privileges, limitations, and cleanup.
-6. Provide exact build and run commands. Use only output captured from a real run. Never invent benchmark numbers, events, PIDs, paths, or errors.
-7. Include the positive path and one meaningful miss, failure, or unsupported path.
-8. Close with what the operator can now learn or control, plus the repository and tutorial-site links.
-
-## Style rules
-
-- Use a specific title such as `# eBPF Tutorial by Example: Quarantine an Established TCP Connection`.
-- Build a progressive explanation around one running example instead of listing features.
-- Match the repository's established depth: explain the workload, BPF hook and state, event/control path, user-space behavior, CLI, verified run, failure path, cleanup, limits, and primary references. Omit any section the actual tool does not need.
-- Borrow organization and voice from the selected precedents, never their scenario-specific facts, output, claims, or defects. The current rulebook overrides a weaker pattern in an older lesson.
-- Use active voice and define technical terms through the example.
-- Give each paragraph one job. Inspect English paragraphs above 110 words, Chinese paragraphs above 320 characters, and any run of three dense paragraphs.
-- Avoid throat clearing, repeated summaries, vague claims, paper-like language, em dashes, semicolons joining independent clauses, and stacked one-line paragraphs.
-- Use a colon only for a real list, code block, or table. Rewrite claim-colon-evidence and noun-phrase-colon openings as sentences.
-- Keep subjects near their verbs, use concrete actors, and replace spec-sheet paragraphs with an argument that explains why each mechanism or number matters.
-- Do not describe a demo as production-ready. State scope and missing hardening plainly.
-- Preserve exact code, command, version, and output facts supplied in the task file.
-- Link kernel claims to primary sources such as kernel commits, documentation, or selftests.
-
-## Bilingual rules
-
-- Keep English and Chinese headings, examples, commands, limitations, and claims aligned.
-- Compose Chinese from the source facts and paragraph role rather than translating English sentence by sentence. Sentence and paragraph boundaries should differ when natural Chinese requires it.
-- Keep product names, code, commands, file names, functions, and genuine terms of art in English. Translate ordinary concept nouns consistently, with a first-use English gloss only when useful.
-- Do not start Chinese prose sentences with an English common noun. Use full-width Chinese punctuation and spaces between CJK text and Latin letters or digits.
-- Keep code and verified console output identical.
-- Do not use Chinese em dashes (`——`) or spaced English em dashes (` — `).
-
-## Required ending links
-
-Include direct links to:
-
-- <https://github.com/eunomia-bpf/bpf-developer-tutorial>
-- <https://eunomia.dev/tutorials/>
-
-Do not add frontmatter unless nearby lessons use it.

.agents/skills/write-bpf-production-tutorial/scripts/run-claude-writer.sh

@@ -4,8 +4,12 @@ set -euo pipefail
 readonly MODEL='claude-opus-4-6[1m]'
 readonly SKILL_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
 readonly VERIFY="$SKILL_DIR/scripts/verify_claude_trace.py"
-readonly GUIDE="$SKILL_DIR/references/writing-guide.md"
+readonly GUIDE="$SKILL_DIR/references/drafting-process.md"
 readonly PRECEDENTS="$SKILL_DIR/references/repository-precedents.md"
+readonly STYLE_DIR="$SKILL_DIR/../bpf-tutorial-writing-style"
+readonly STYLE_GUIDELINES="$STYLE_DIR/references/advanced-tutorial-guidelines.md"
+readonly STYLE_REPOSITORY="$STYLE_DIR/references/repository-house-style.md"
+readonly STYLE_PROSE="$STYLE_DIR/references/prose-and-bilingual-checklist.md"
 
 usage() {
   echo "usage: $0 --repo ABSOLUTE_REPO_PATH --task ABSOLUTE_TASK_FILE --readme ABSOLUTE_README_PATH --readme ABSOLUTE_README_PATH" >&2
@@ -95,11 +99,14 @@ status_before=$(git -C "$repo" status --porcelain=v1)
 task_sha=$(sha256sum "$task" | awk '{print $1}')
 printf -v allowed_paths 'Allowed README path: %s\n' "${allowed_readmes[@]}"
 
-prompt=$(printf '%s\n\n%s\n%s\n%s\n%s\n' \
+prompt=$(printf '%s\n\n%s\n%s\n%s\n%s\n%s\n%s\n%s\n' \
   'You are the prose author for this eBPF production tutorial pass. Read the repository code and evidence named in the task. Edit only the README.md and README.zh.md paths explicitly allowed by the task. Do not edit code, build files, generated indexes, or tests. Do not invent output or claims. Finish by stating which README files you edited.' \
   "$allowed_paths" \
   "$(<"$GUIDE")" \
   "$(<"$PRECEDENTS")" \
+  "$(<"$STYLE_GUIDELINES")" \
+  "$(<"$STYLE_REPOSITORY")" \
+  "$(<"$STYLE_PROSE")" \
   "$(<"$task")")
 
 set +e

.agents/skills/write-bpf-production-tutorial/scripts/run-external-review.sh

@@ -2,9 +2,13 @@
 set -euo pipefail
 
 readonly SKILL_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
-readonly WRITING_GUIDE="$SKILL_DIR/references/writing-guide.md"
+readonly WRITING_GUIDE="$SKILL_DIR/references/drafting-process.md"
 readonly REVIEW_GUIDE="$SKILL_DIR/references/review-checklist.md"
 readonly PRECEDENT_GUIDE="$SKILL_DIR/references/repository-precedents.md"
+readonly STYLE_DIR="$SKILL_DIR/../bpf-tutorial-writing-style"
+readonly STYLE_GUIDELINES="$STYLE_DIR/references/advanced-tutorial-guidelines.md"
+readonly STYLE_REPOSITORY="$STYLE_DIR/references/repository-house-style.md"
+readonly STYLE_PROSE="$STYLE_DIR/references/prose-and-bilingual-checklist.md"
 
 usage() {
   echo "usage: $0 --reviewer grok|glm --repo ABSOLUTE_REPO_PATH --task ABSOLUTE_TASK_FILE --file REPO_RELATIVE_PATH [--file ...]" >&2
@@ -92,6 +96,12 @@ manifest="$run_dir/manifest.json"
   sed -n '1,$p' "$REVIEW_GUIDE"
   printf '\n## Repository precedent rulebook\n\n'
   sed -n '1,$p' "$PRECEDENT_GUIDE"
+  printf '\n## Project-provided advanced tutorial guidelines\n\n'
+  sed -n '1,$p' "$STYLE_GUIDELINES"
+  printf '\n## Repository house style\n\n'
+  sed -n '1,$p' "$STYLE_REPOSITORY"
+  printf '\n## Prose and bilingual checklist\n\n'
+  sed -n '1,$p' "$STYLE_PROSE"
   printf '\n## Review task and evidence\n\n'
   sed -n '1,$p' "$task"
   for file in "${files[@]}"; do