diff --git a/.agents/skills/bpf-tutorial-writing-style/SKILL.md b/.agents/skills/bpf-tutorial-writing-style/SKILL.md index 61c15c1..fb7966c 100644 --- a/.agents/skills/bpf-tutorial-writing-style/SKILL.md +++ b/.agents/skills/bpf-tutorial-writing-style/SKILL.md @@ -5,6 +5,8 @@ description: Style checklist for English and Chinese bpf-developer-tutorial READ # BPF Tutorial Writing Style +This checklist is reference material, not a mandatory second pass after `$write-bpf-production-tutorial`. When Claude is the delegated writer, do not use this skill to review or rewrite Claude's result, do not send it to Claude as an additional checklist, and do not ask Claude for another revision. Codex may make local word-choice and punctuation edits after the delegated writing pass while preserving sentence meaning and paragraph structure. + Read the complete guidelines first: - [Advanced tutorial guideline](https://github.com/eunomia-bpf/bpf-developer-tutorial/blob/main/scripts/guideline_advance.md) for tutorials 40+ - [Basic tutorial guideline](https://github.com/eunomia-bpf/bpf-developer-tutorial/blob/main/scripts/guideline_basic.md) for tutorials 0-39 @@ -41,12 +43,14 @@ Use this Chinese paragraph only as a voice reference for connected rhythm, restr > libbpf 是一个 C/C++ 的 eBPF 用户态加载和控制库,随着内核一起分发,几乎已经成为 eBPF 用户态事实上的 API 标准,libbpf 也支持 CO-RE(Compile Once – Run Everywhere) 的解决方案,即预编译的 bpf 代码可以在不同内核版本上正常工作,而无需为每个特定内核重新编译。 -## Teach from complete source +## Teach from the code that matters -- Introduce one component, show its complete source in an ordinary Markdown fence, then explain the important logic before moving to the next component. -- Keep every core source file byte-exact and complete, including the user-space loader. Preserve comments and commands; use focused excerpts only after the complete block when they help explain a specific mechanism. +- Introduce one component, show the code needed to understand it in an ordinary Markdown fence, then explain the important logic before moving to the next component. +- Show the core kernel-side eBPF program in full when its complete control flow is the lesson. Large or secondary kernel files may use focused excerpts when the omitted parts do not carry the mechanism being taught. +- Keep the user-space discussion compact. Show the loader, configuration, event loop, and cleanup functions only when they help explain the interaction with BPF. A complete user-space loader is optional, and omitting boilerplate is not a tutorial failure. +- Keep every included code excerpt faithful to the repository source. Link to the tutorial directory once so readers can inspect the complete implementation. - Use neither `
` nor HTML synchronization markers. -- Link to the complete lesson once through its GitHub directory. Avoid an opening catalog of individual files. +- Avoid an opening catalog of individual files. - 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. @@ -57,4 +61,4 @@ Use this Chinese paragraph only as a voice reference for connected rhythm, restr - 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. +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. It does not need to reproduce every line of user-space implementation. diff --git a/.agents/skills/write-bpf-production-tutorial/SKILL.md b/.agents/skills/write-bpf-production-tutorial/SKILL.md index 43cdda8..5caf258 100644 --- a/.agents/skills/write-bpf-production-tutorial/SKILL.md +++ b/.agents/skills/write-bpf-production-tutorial/SKILL.md @@ -1,97 +1,32 @@ --- name: write-bpf-production-tutorial -description: Design, write, or rewrite one or more practical bilingual bpf-developer-tutorial lessons with pinned Claude Opus 4.5, then verify the public workflow, complete source, and prose against the implementation. Use when creating README.md and README.zh.md, checking whether a tutorial tool has a realistic CLI and lifecycle, testing the example, or preparing tutorial changes for review. +description: Write or rewrite bilingual bpf-developer-tutorial lessons by assigning each tutorial's English and Chinese README pair to its own pinned Claude Opus 4.5 process. Use when creating or revising README.md and README.zh.md while requiring Claude to edit one tutorial paragraph by paragraph from the reader's perspective, allowing Codex to make local word and punctuation edits only and forbidding an additional prose review or rewrite request. --- # Write a BPF Tutorial -Use `$bpf-tutorial-writing-style` for the finished prose. Keep this workflow small: prepare reliable source material, let one pinned writer complete both languages, then check what it actually wrote. +Keep one writer for the complete reader-facing text. One Claude Opus process performs one free, paragraph-by-paragraph pass over one tutorial's English and Chinese README pair. Codex coordinates the invocation and performs mechanical checks without becoming a second writer or reviewer. -## 1. Prepare the lesson +## 1. Give Opus the complete task once -Read these inputs before writing: +Use the exact model ID `claude-opus-4-5-20251101`. Stop when that model is unavailable instead of substituting another model. -- `scripts/guideline_advance.md` for tutorials 40+, `scripts/guideline_basic.md` for tutorials 0-39; -- both README files from `src/47-cuda-events`, `src/48-energy`, and `src/49-hid` as style references; -- the lesson's implementation, headers, Makefile, fixtures, and tests; -- the current README pair when revising an existing lesson; -- primary upstream sources for versions and feature semantics. +Run one non-interactive invocation from the repository root for one tutorial directory. Name that tutorial's English and Chinese README pair, the applicable `scripts/guideline_advance.md` or `scripts/guideline_basic.md`, and existing tutorials as general references. Ask Claude to revise every paragraph freely from the reader's perspective, improve readability, adjust content or structure wherever useful, finish both files before returning, and ask no questions. -Collect the facts the reader needs: the problem, useful alternatives, the kernel/user-space flow, feature versions, requirements, intended public commands, real output, concurrency or admission behavior, 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. +Start a separate Claude process for every additional tutorial. Never batch README pairs from different tutorial directories into one process. -Write down the narrowest useful description supported by the normal execution path before drafting. Use it to align the title, opening, CLI, output, and test. For stateful security examples, include the correlation key, admission checks, state lifetime, enforcement point, and the negative cases exercised by the test. +Keep the prompt to that request. Do not add a paragraph plan, fact inventory, style checklist, defect list, review rubric, acceptance criteria, or instructions for a later revision. Give Claude permission to read the repository and write only the target README files. Claude does not commit or push. -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. +## 2. Preserve single-writer ownership -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. +Treat Claude as the sole author of sentences, headings, paragraph order, explanations, and translations. After Claude returns, Codex may make local word-choice and punctuation edits. Keep those edits within the existing sentence meaning and paragraph structure. Codex must not add or remove information, rewrite sentences, reorder paragraphs, change headings, shorten or expand explanations, or alter translations substantively. -## 2. Pass the practical-design gate +Use exactly one Claude writing pass per tutorial. Do not ask Claude to review its result, respond to a defect list, polish selected paragraphs, or rewrite the tutorial again. Do not invoke another model, subagent, or independent reviewer for the prose. When the result needs another writing pass, report that fact to the user and wait for an explicit request. -Validate the tool as an operator before writing prose. Keep its public workflow separate from the deterministic fixture: +## 3. Perform mechanical checks only -- State the operational question, the exact command a reader would run, the independent workload or target, the useful output, and how the tool stops. -- Classify the lifecycle. A scan or atomic control action may be one-shot; a tracer or monitor must attach before the workload and remain active until a signal, duration, or real completion condition. -- Do not turn a blocked toy child or `/bin/true` fixture into the public CLI merely because it removes a test race. Launch-scoped tracing is valid only when it is the intended real workflow. -- Emit and test an explicit readiness signal before starting an independent workload. Do not use a fixed sleep as proof that setup or attachment completed. -- Check target scope and filters, concurrent state, admission bounds, drop and failure counters, exit status, normal cleanup, signal cleanup, and destructive-action safety in proportion to the lesson. -- For asynchronous work, stop admission first, wait for completed work rather than merely entered callbacks, drain output, report stable health, and only then destroy resources. -- Execute the documented command as written. The test must prove the real lifecycle plus one relevant failure or cleanup path, not only that the BPF program loaded. -- Describe the current public workflow directly. Do not narrate removed flags, old child-command modes, or other migration history unless backward compatibility is itself the lesson. -- Keep repository tests out of the reader-facing tutorial path. Use them as private validation evidence, but teach the normal command, independent workload, useful tool output, and shutdown sequence. -- Show only output emitted by the documented tool in public examples. Never include harness lines such as `TEST-*` or `PASS`, fixture setup, test assertions, or local test-infrastructure provenance. +Check only that the intended files exist, remain nonempty, stay within the requested file scope, contain no merge markers, and expose no local paths, usernames, secrets, prompts, or private infrastructure. Do not count lines or code fences as a quality proxy. Never run `sync-source-blocks.py` or compare README code fences against a complete repository source inventory as writing acceptance. Do not require the README to contain a byte-exact copy of every source file, and do not treat an omitted complete user-space loader as a failure. These checks establish basic file integrity; they are not a prose, style, structure, factual, or technical review. -If the implementation only demonstrates a helper but is awkward or misleading as a tool, revise the implementation and test before asking the writer to explain it. Do not let polished prose overclaim an impractical design. +Run repository formatting or documentation validation only when it does not rewrite the text. Report mechanical failures without repairing words or asking Claude to revise them. Preserve prompts, responses, drafts, and failed runs; never delete real conversation or agent history. -## 3. Shape the lesson - -Follow `scripts/guideline_advance.md`, then organize the article around the example rather than a fixed heading template. A complete lesson normally has: - -- 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; -- the normal public command, target, lifecycle, useful output, and shutdown path; -- copyable build and run commands, real output, requirements, a compact ending, and primary references. - -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. - -## 4. 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 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: - -- 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, 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 only the target README files. Opus does not commit or push. - -## 5. Check the result - -Inspect both files and the diff instead of trusting the model's final message. Confirm that: - -- both languages are complete and tell the same technical story; -- the documented command, target, lifecycle, signals, concurrency bounds, cleanup, and health output match the practical design gate; -- the opening reads like a tutorial rather than an abstract or feature list; -- every mechanism promised by the title and introduction appears in the executable path, and a feature-driven lesson both uses and explains the named API; -- the title and opening describe the narrowest useful behavior proven by the normal mode and test, without expanding a focused allowlist, profiler, index, capture tool, or monitor into a broader product category; -- 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, including the user-space loader, appears once in a complete ordinary Markdown fence; -- code, commands, output, versions, requirements, cleanup, and limits agree with the repository; -- sample output comes from the normal public workflow and contains no test-harness or migration/deprecation narration; -- the opening source link points only to the lesson directory; -- 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 every core header, kernel/BPF source, and user-space loader with the bundled `sync-source-blocks.py`. Then run `git diff --check`, the lesson build, its tests, the exact documented public command, 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. 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. +Stop with the local result unless the user explicitly asks to commit, push, or update a PR. diff --git a/.agents/skills/write-bpf-production-tutorial/agents/openai.yaml b/.agents/skills/write-bpf-production-tutorial/agents/openai.yaml index ad3f247..1888061 100644 --- a/.agents/skills/write-bpf-production-tutorial/agents/openai.yaml +++ b/.agents/skills/write-bpf-production-tutorial/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "BPF Tutorial Writer" - short_description: "Design and test practical bilingual eBPF lessons" - default_prompt: "Use $write-bpf-production-tutorial to turn this eBPF example into a practical, tested bilingual tutorial." + short_description: "Let one Opus process revise one bilingual lesson" + default_prompt: "Use $write-bpf-production-tutorial to let one pinned Claude Opus process revise this tutorial's English and Chinese README pair paragraph by paragraph from the reader's perspective." diff --git a/scripts/guideline_advance.md b/scripts/guideline_advance.md index 02ad761..edc0a2e 100644 --- a/scripts/guideline_advance.md +++ b/scripts/guideline_advance.md @@ -28,7 +28,7 @@ Provide an overview of the specific eBPF programs, tools, or features you'll dis 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. +Show the core kernel-mode eBPF program in full when it is central to the lesson, then break down the key parts. For user-space code, include only the functions and excerpts needed to understand loading, configuration, event handling, and cleanup. Link to the tutorial directory for the complete implementation. Try to avoid using too much list, make it more like a story. @@ -43,7 +43,7 @@ Follow the steps: 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 +3. Then briefly explain the user-space code, using focused excerpts when they make the control flow easier to follow Aim to help readers grasp how the code works without getting bogged down in basic details. @@ -76,6 +76,6 @@ You should include the important references and resources that used in the tutor - **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. +- **Code Formatting:** Ensure code snippets are well-formatted and highlight key parts. Keep every included excerpt and command faithful to the implementation. The tutorial does not need to embed the complete user-space loader. - **Proofreading:** Double-check for errors and ensure technical accuracy. - **Accessibility:** Make the content valuable for readers with advanced expertise, avoiding unnecessary simplifications.