docs: streamline BPF tutorial authoring skills

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

@@ -11,71 +11,24 @@ Read the complete guidelines first:
 
 Then read the English and Chinese versions of `47-cuda-events`, `48-energy`, and `49-hid` as style references. Learn their teaching rhythm and level of detail without copying their topic or wording.
 
-## Document Structure (strictly follow guideline)
+## Let the topic choose the structure
 
-For advanced tutorials (40+), follow this exact section order:
+Follow `scripts/guideline_advance.md` without turning its suggestions into ten mandatory headings. Use a direct title, a short opening, the background the example actually needs, a high-level flow, complete source with explanation, compilation and execution, a compact ending, and primary references. Choose section names that sound natural for the topic.
 
-1. **Title**: `# eBPF 教程：[Topic Description]` or `# eBPF Tutorial by Example: [Topic Description]`
-
-2. **Introduction**: Brief intro with a concrete problem scenario. Highlight significance and what readers will learn. Link to complete source once here.
-
-3. **Background / Why This Approach**: 
-   - Explain WHY this approach is needed
-   - List traditional/alternative approaches and their limitations (e.g., killing process, firewall rules, user-space tools)
-   - Explain what eBPF/the new kernel feature enables that traditional approaches cannot
-   - State when the feature entered Linux (kernel version + commit if relevant)
-
-4. **High-Level Mechanism**:
-   - Explain HOW the eBPF feature/tool works at a high level BEFORE showing code
-   - Describe the overall flow: what happens in kernel, what happens in user space, how they interact
-   - Use diagrams for complex flows with branches, waits, ownership transfers, or 3+ dependent states
-
-5. **Code Implementation**:
-   - First introduce the overall processing logic
-   - Show complete source code for each component (header, BPF program, user-space loader)
-   - After each complete code block, explain the key parts with paragraph style (not bullet lists)
-   - Focus on logic and advanced features, not basic syntax
-
-6. **Additional Concepts** (if needed): Deeper explanation of specific features, edge cases, or semantics
-
-7. **Compilation and Execution** (AFTER code, not before):
-   - Build commands
-   - Run commands with examples
-   - Expected output with explanation
-   - Environment requirements table (kernel version, config, privileges, architecture)
-
-8. **Summary**: Key points, scope boundaries, future extensions
-
-9. **Call to Action**: Repository and website invitation (as blockquote)
-
-10. **References**: Links to kernel commits, upstream selftests, documentation
+Introduce information at the point where the reader needs it. Compilation follows the code discussion. Extra concept sections, alternative approaches, requirements tables, and diagrams are useful when they clarify a real decision or a flow with several dependent states.
 
 ## Tell one useful story
 
-- Open with a concrete situation that the example can reproduce and the question it answers.
-- Near the first mention of eBPF, use one natural sentence to say what eBPF is and why it fits this problem.
+- Open with the concrete question the tool answers. A short factual setup is often enough; avoid invented stories.
+- Near the first mention of eBPF, use one natural sentence to say that it runs verified programs at kernel hooks and can send selected state to user space.
 - Introduce the relevant kernel subsystem and new feature when the running example needs them. State when the feature entered Linux and what it enabled.
 - Follow one packet, event, task, or device interaction through kernel space and user space. Explain what happens, why it happens, and what the next step enables.
-- Present the whole flow before detailed code. A small diagram helps when the reader must track a branch, wait, retry, ownership transfer, or at least three dependent states.
-
-## Explain the "Why" thoroughly
-
-This is critical. The Background section must explain:
-- What problem you're solving
-- What traditional approaches exist (killing process, firewall rules, user-space tools like `ss --kill`, sampling, etc.)
-- Why each traditional approach doesn't work well (race conditions, incomplete coverage, performance overhead, etc.)
-- What the eBPF approach enables that wasn't possible before
-
-Example pattern for the "Why" section:
-> **杀掉进程**是最直接的想法，但一个进程往往维护着多条连接，杀进程会中断所有业务流量。
-> **防火墙规则**可以阻止新连接，但对已建立的连接无能为力。
-> **用户态工具**如 `ss --kill` 依赖 `/proc/net/tcp` 遍历和注入 RST 报文，但这种方式有竞态问题。
-> **内核态方案**才能真正解决这个问题。BPF 迭代器可以在持有适当锁的情况下遍历内核的套接字表...
+- Present the whole flow before detailed code. Add a diagram only when it makes a branch, wait, retry, ownership transfer, or multi-stage path materially easier to follow.
 
 ## Sound like a tutorial
 
 - Use familiar words, direct verbs, and connected paragraphs. Attraction comes from the problem and mechanism rather than promotional language.
-- Prefer positive descriptions of what the example does. Put remaining limits and safety boundaries in one short paragraph near the end.
+- Prefer positive descriptions of what the example does. Use negative constructions sparingly. Put the most relevant scope note in one short paragraph near the end.
 - Use prose for the main explanation and lists for genuinely parallel items.
 - Keep each paragraph focused on one job. Connect facts through cause, sequence, or contrast instead of listing them like a specification.
 - Write Chinese naturally from the same facts instead of translating English sentence by sentence. Use restrained punctuation and spaces between Chinese text and Latin letters or numbers.
@@ -91,14 +44,14 @@ Use this Chinese paragraph only as a voice reference for connected rhythm, restr
 - Keep source byte-exact. Preserve comments and commands; use focused excerpts only after the complete block.
 - Use neither `<details>` nor HTML synchronization markers.
 - Link to the complete lesson once through its GitHub directory. Avoid an opening catalog of individual files.
-- Every Markdown link uses an absolute `https://github.com/...` target. Omit a link when no stable GitHub target exists.
+- Every Markdown link uses a stable absolute `https://` target. GitHub, kernel.org, and authoritative documentation sites are all valid; relative links are prohibited.
 - Public prose contains no local path, shared test repository, VM name, copy route, cache, prompt, model, agent, or trace detail.
 
 ## Finish the lesson
 
 - Show copyable build and run commands, representative real output, and what that output proves.
 - State kernel, configuration, privilege, architecture, and hardware requirements that affect the example (use a table).
-- End with a compact scope boundary, summary, repository invitation, and primary references.
+- End with a compact summary, repository invitation, and primary references.
 - Keep the English and Chinese files aligned on structure, facts, source, commands, output, limits, and references while allowing each language to sound natural.
 
 The final read should answer: what problem is solved, how one event moves through the system, which eBPF mechanism makes it possible, which code matters, how to run it, what success looks like, and where the example stops.

.agents/skills/test-bpf-tutorial-kvm/scripts/run-in-kvm.sh

@@ -146,13 +146,15 @@ fi
     die "/dev/kvm is not available with read/write permission; refusing a TCG fallback"
 
 benchmark_root=$(realpath -e -- "$benchmark_root")
-kernel_source=$benchmark_root/vendor/linux-framework
 kernel_build=$benchmark_root/vendor/build/x86/linux
+kernel_source_link=$kernel_build/source
 kernel_image=$kernel_build/arch/x86/boot/bzImage
 kernel_config=$kernel_build/.config
 kernel_release_file=$kernel_build/include/config/kernel.release
 
-[[ -d $kernel_source ]] || die "kernel source directory is missing: $kernel_source"
+[[ -e $kernel_source_link ]] || die "kernel build source link is missing: $kernel_source_link"
+kernel_source=$(realpath -e -- "$kernel_source_link")
+[[ -d $kernel_source ]] || die "kernel build source directory is missing: $kernel_source"
 [[ -s $kernel_image ]] || die "built benchmark kernel is missing: $kernel_image"
 [[ -r $kernel_config ]] || die "kernel config is missing: $kernel_config"
 [[ -r $kernel_release_file ]] || die "kernel release file is missing: $kernel_release_file"
@@ -191,6 +193,7 @@ printf '%s\n' \
     'KVM preflight: OK' \
     "benchmark_root=$benchmark_root" \
     "kernel_image=$kernel_image" \
+    "kernel_source=$kernel_source" \
     "kernel_release=$kernel_release" \
     "kernel_sha256=$kernel_sha256" \
     "kernel_config_sha256=$config_sha256" \

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

@@ -1,6 +1,6 @@
 ---
 name: write-bpf-production-tutorial
-description: Write or rewrite one bilingual bpf-developer-tutorial lesson with pinned Claude Opus 4.5, then verify the result against the implementation. Use when creating README.md and README.zh.md, preserving full source, testing the example, or preparing tutorial changes for review.
+description: Write or rewrite one or more bilingual bpf-developer-tutorial lessons with pinned Claude Opus 4.5, then verify the result against the implementation. Use when creating README.md and README.zh.md, preserving full source, testing the example, or preparing tutorial changes for review.
 ---
 
 # Write a BPF Tutorial
@@ -17,43 +17,39 @@ Read these inputs before writing:
 - the current README pair when revising an existing lesson;
 - primary upstream sources for versions and feature semantics.
 
-Collect the facts the reader needs: the problem, why traditional approaches fail, the kernel/user-space flow, feature versions, requirements, commands, real output, cleanup, limits, and references. Keep every claim grounded in the code, tests, captured output, or a primary source. Preserve an existing draft before a from-scratch rewrite.
+Collect the facts the reader needs: the problem, the kernel/user-space flow, feature versions, requirements, commands, real output, cleanup, scope, and references. Add alternatives when they help the reader choose or understand the mechanism. Keep every claim grounded in the code, tests, captured output, or a primary source. Preserve an existing draft before a from-scratch rewrite.
+
+Make the example a small useful tool. Its normal mode works on a reader-selected process, cgroup, interface, or other real target. A deterministic demo or integration test may create its own workload. Keep the CLI compact and keep infrastructure details out of public text.
 
 Build and run the example when the environment supports it. Use `$test-bpf-tutorial-kvm` for kernel features that need the repository's KVM environment. Runtime details support the tutorial; local workspace paths, VM names, shared repositories, caches, prompts, and agent traces stay private.
 
-## 2. Structure requirements
+## 2. Shape the lesson
 
-For advanced tutorials (40+), follow this exact section order as defined in `$bpf-tutorial-writing-style`:
+Follow `scripts/guideline_advance.md`, then organize the article around the example rather than a fixed heading template. A complete lesson normally has:
 
-1. **Title + Introduction**: Concrete problem scenario, link to source
-2. **Background / Why This Approach**: Explain traditional approaches and their limitations, then what eBPF enables
-3. **High-Level Mechanism**: How the feature works before showing code
-4. **Code Implementation**: Complete source blocks, then paragraph explanations
-5. **Additional Concepts** (if needed)
-6. **Compilation and Execution**: AFTER code analysis, not before
-7. **Summary + Call to Action**
-8. **References**
+- a direct title and a short introduction that says what the tool answers;
+- enough eBPF, kernel-subsystem, and feature background to make the mechanism understandable, including the feature's kernel version when relevant;
+- the complete kernel and user-space flow before detailed code;
+- every core source file in a normal Markdown fence, followed by focused explanation;
+- copyable build and run commands, real output, requirements, a compact ending, and primary references.
 
-The "Background / Why" section is critical. It must explain:
-- What traditional approaches exist
-- Why each doesn't work well
-- What the eBPF approach enables
+Use headings that fit the topic. Keep compilation after the code discussion. Explain alternatives, limits, diagrams, and extra concepts only when they materially improve the lesson.
 
 ## 3. Let Opus write
 
 Claude Opus writes all reader-facing tutorial prose. Use the exact model ID `claude-opus-4-5-20251101`. Stop if that model is unavailable instead of substituting another model.
 
-Use one non-interactive invocation for the complete English and Chinese pair. The prompt stays short and names only:
+Use one non-interactive invocation for the complete requested set. A single lesson means one English and Chinese pair; a batch means every requested pair is finished in the same invocation before Opus returns. The prompt stays short and names only:
 
-- the two target README files;
+- every target README pair;
 - `scripts/guideline_advance.md` or `scripts/guideline_basic.md`;
 - `$bpf-tutorial-writing-style`;
 - `src/47-cuda-events`, `src/48-energy`, and `src/49-hid` as style references;
-- the request to read the implementation and write both files completely before returning.
+- the request to read the implementation, rewrite each paragraph in place, and finish both files before returning without questions.
 
 Do not paste a second checklist, paragraph plan, fact inventory, or review rubric into the prompt. Add a technical fact only when it is unavailable in the repository.
 
-Run Claude from the repository root with the pinned model and permission to read the repository and write the two README files. Opus does not commit or push.
+Run Claude from the repository root with the pinned model and permission to read the repository and write only the target README files. Opus does not commit or push.
 
 ## 4. Check the result
 
@@ -61,17 +57,17 @@ Inspect both files and the diff instead of trusting the model's final message. C
 
 - both languages are complete and tell the same technical story;
 - the opening reads like a tutorial rather than an abstract or feature list;
-- there is a "Why" section explaining traditional approaches and their limitations;
-- the high-level mechanism is explained BEFORE code sections;
+- the relevant eBPF and kernel background appears before details that depend on it;
+- the high-level mechanism is explained before code sections;
 - compilation/execution is AFTER code analysis;
 - every core source file appears once in a complete ordinary Markdown fence;
 - code, commands, output, versions, requirements, cleanup, and limits agree with the repository;
 - the opening source link points only to the lesson directory;
-- every published link is an absolute `https://github.com/...` URL;
+- every published link uses a stable absolute `https://` URL; GitHub, kernel.org, and authoritative documentation sites are valid, while relative links are prohibited;
 - no local infrastructure, prompt, model, agent, or trace detail appears in public text.
 
 Check source blocks with the bundled `sync-source-blocks.py`, then run `git diff --check`, the lesson build, its tests, and the relevant runtime test. Treat a functional run as a functional run rather than a benchmark.
 
-Read the finished pair once as an intermediate eBPF developer. If a concrete problem remains, give Opus a short defect list in the same session and let it revise the whole pair before returning. Keep prompts, responses, partial drafts, and failed runs; never delete real conversation or agent history.
+Read the finished pair once as an intermediate eBPF developer. Remove template-like detours, repeated setup, unexplained jargon, and details that belong only to the test harness. If a concrete problem remains, give Opus a short defect list in the same session and let it revise the affected paragraphs before returning. Keep prompts, responses, partial drafts, and failed runs; never delete real conversation or agent history.
 
 Stop after the reviewed local result unless the user asks to commit, push, or update a PR.