protocol-doc
Skill1 starsChanged 3 days agoMITView on GitHub
Document a network / application protocol in Tsukini's way (from the 2ETP protocol doc of his myteams project) - name + version + acronym, what it provides, the framing of a transmission (control bytes ENQ / ETB / EOT...), the payload types table (byte, hex, link), one section per message type (grammar + field bullets), the code tables (errors, events, commands, with the data sent), a summary of every frame, the handshake / key exchange step by step with the exact frames and a sequence diagram, the commands of the client and of the server (purpose, answer, usage), the storage format (separators, layout, parsed type) - always asking first the output (Markdown, PDF, HTML section inside the existing docs/ site). Use whenever the user wants to document, specify, describe or review a protocol, a wire format, a message format, a handshake, the commands of a client / server, or the files format of a networking project.
In this repository70 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ask-at-endSkill
- clarifySkill
- continue-workSkill
- exportSkill
- full-permissionSkill
- ideationSkill
- interactive-questionsSkill
- onboardSkill
- pauseSkill
- presentationSkill
- rtkSkill
- setup-contextSkill
- write-like-meSkill
- audit-bugsSkill
- audit-depsSkill
- audit-qualitySkill
- audit-securitySkill
- benchmarkSkill
- cmake-styleSkill
- cpp-classSkill
- cpp-commentsSkill
- cpp-projectSkill
- cpp-styleSkill
- better-explain-docSkill
- better-html-docSkill
- better-html-styleSkill
- better-protocol-docSkill
- docs-updateSkill
- explain-docSkill
- html-docSkill
- html-styleSkill
- readme-styleSkill
- reportSkill
- wiki-styleSkill
- ci-cdSkill
- git-commitSkill
- git-conventionsSkill
- pre-commitSkill
- legal-checkSkill
- legal-setupSkill
- licenseSkill
- libutils-exceptionSkill
- libutils-installSkill
- libutils-setupSkill
- libutilsSkill
- python-classSkill
- python-commentsSkill
- python-projectSkill
- python-styleSkill
- auditSkill
- cppSkill
- devSkill
- docSkill
- gitSkill
- legalSkill
- pythonSkill
- setup-projectSkill
- styleSkill
- setup-studioSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 73
Every frame, byte and command checked against the code.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Protocol documentation
<name> (a skill) = the folder of that skill: ~/.claude/skills/<name> (setup.sh) or ${CLAUDE_SKILL_DIR}/../../*/<name> (plugin of the marketplace).
SKILL_DIR = the directory of this file. The reference is the 2ETP doc of the user (the README.md of
~/delivery/year_2/nwp/G-NWP-400-BDX-4-1-myteams-1): its order, its tables and its notation are the model, improved by
the checks below. Every byte, code, field and command is read from the code (the parser, the enums of the control
bytes, the command table, the handshake functions): never invented, planned parts marked as such.
1. Ask first, always (one AskUserQuestion call, French)
Even when the request seems to say it, confirm (the answers decide the files):
- Format (multiSelect):
Markdown (Recommandé)(PROTOCOL.md, or a section of the README when the project has no other doc) ·PDF(from the Markdown, style ofreport) ·HTML dans la doc existante(sections of the technical page ofdocs/,html-docstyle; nodocs/yet: the technical page is created withhtml-doc). - Contenu (multiSelect, the ones found in the code pre-selected in the descriptions):
Trame + types de messages·Codes (erreurs, événements, commandes)·Handshake / échange de clés·Commandes client / serveur·Format de stockage. - Langue:
Anglais (Recommandé)·Français·Les deux(HTML: EN / FR switch ofhtml-doc, always both). - Emplacement (only when not obvious):
PROTOCOL.md à la racine·docs/PROTOCOL.md·Section du README. The answers are kept for the rest of the conversation (a later update of the same doc never asks again).
2. Read the protocol in the code
- Framing: the send / recv functions, the parser (
parseTransmission...), the control characters used (utils::write::Char::*,#define, enums), the encoding (Base64, hex, length prefix), the encryption (tag size). - Message types: the switch on the first byte of the payload, one per type; the code ranges (
code % 128 + 128). - Codes: the error / event / command enums or tables, and for each event / answer the data it carries, in order.
- Handshake: the first exchanges of a connection (client and server sides), the keys generated (sizes), what makes the server disconnect.
- Commands: the command table of the client (name, arguments, code sent) and its answer on the server; the server console commands.
- Storage: the files written, their separators, the order of the fields, the type of the parsed data.
- Anything unclear (a byte whose meaning the code doesn't show): ask in the same AskUserQuestion call or mark it TBD in the doc, never guess.
3. Structure (templates/PROTOCOL.md)
# Documentation(or# <Project> protocol),### Table of Contentslinking every##.## <NAME> Protocol (vX.Y.Z), the acronym expanded in a quote with the bold letters (> **E**ncrypted & **E**ncoded, **T**yped **T**ransfer **P**rotocol), one sentence (layer, transport), thenIt provides:and its bullets (encryption, encoding, typed messages, framing).### Payload: the grammar of a transmission in a code block (ENQ <tag> ETB <payload> EOT), one bullet per element (name, hex(`0x05`), role), the RFC 2119 words in upper case (MUST, MUST NOT, SHOULD, MAY), then the types table| Byte (hexa) | Type |:SYN (`0x16`)and a link to the section of the type.- One
###per message type: its grammar in a code block (repetition*(ETB <data>), optional[...], alternativesa | b), one bullet per field (encoding, size, meaning), its code table when it has codes (| Code (0-127) | Error |,| Code (0-127) | Event | Data sent |,| Code (0-127) | Command |with links to the command sections), the reserved / internal codes (127) said. ### Different Payload Type Resume: every frame of the protocol in one code block, aligned, one comment per line (/* Connection */ ENQ <tag> ETB SYN EOT).## Handshake: one###per step (### First step (basic, tag = 0 byte)), who sends what with the exact frame in backticks, the server behaviour asIf valid → ... / If invalid → ...bullets, the side code excerpt (short, the real code) when it helps, and a sequence diagram of the whole exchange (templates/PROTOCOL.md: ASCII in a code block, it renders in every format).## Commands (Client)/## Commands (Server): one###per command:> [!NOTE]purpose,> Server answers with \<frame>`(each context on its own line, the events it triggers& event(N)), the usage in a code block (login "user_name", optional[ip:port], alternatives(user_uuid|thread_uuid));> [!IMPORTANT]` for an internal command.## <Storage>:> [!WARNING]when not encrypted, the tree of the files (bashblock), the separators table (| Byte (hexa) | Usage |), the layers (file -> record GS record GS ...), each file layout in its own code block (one field per line when it is long: never a single line wider than the page), the parsed C++ type with its comments.
- Notation, everywhere: control bytes by their ASCII name + hex, placeholders
<snake_case>, literal strings in quotes, repetitions*( ... ), a field encoded in Base64 said so once in its bullet.
4. Writing
- English by default (the answer of question 3), present tense, short sentences; a typo of the reference (
steap,awnser,dosen't,reciever) is never copied. - Every frame, byte and command checked against the code; a difference between the code and an existing doc is reported to the user before choosing which one wins.
- Improvements over the reference, applied by default: the RFC 2119 words, the error answer of each command (
NAK <code>cases), a hex example of one full frame (templates/PROTOCOL.md, Example), the version of the protocol and what a peer does with an unknown type / code, the limits (max size of a frame, timeouts) when the code has them.
5. Outputs
- Markdown:
templates/PROTOCOL.mdfilled (GitHub callouts> [!NOTE], tables, code blocks;readme-stylerules for the rest; an empty line before every table: the PDF shows raw pipes without it); the README links to it (## Documentationline) when it is a separate file. - PDF: from that Markdown,
python3 <report>/scripts/md2pdf.py PROTOCOL.md --format both -o PROTOCOL.pdf --footer "<Project> — <NAME> protocol"(style ofreport, GitHub callouts rendered: note / tip blue, warning orange);pdftoppm -r 60 -png -f 1 -l 2to look at it (no line wider than the page, tables whole). - HTML in the existing doc (
html-doc+html-style): the sections oftemplates/protocol.htmlpasted intodocs/technical.html(or the technicalindex.html) as numbered cards after the existing ones (one<section>per##of the Markdown: Protocol, Handshake, Commands, Storage), their links added to the sidebar, every text in both languages; the frames in<pre data-title="...">, the types / codes intable-wraptables, the notes incallout/callout warn, the handshake as the SVG sequence diagram of the template (activation boxes on the lifelines, arrows computed withdata-from/data-to, never typed; drawn at its size on every screen, in a box that scrolls on a phone, each frame starting next to the client: read without scrolling. A longer frame: widen itsviewBoxand its width together). Every bracket of a frame is written<tag>(a raw<tag>is hidden by the browser); a text of a drawing per language is one<text data-lang>, never a<span>(the browser leaves the drawing there). A table too wide for a phone scrolls in its box:style="min-width:14em"on thethof a column of sentences,style="min-width:18ch"on one of long names, never a word per line. Thenpython3 <html-style>/scripts/check_style.py docs/*.html(0 error),python3 <html-style>/scripts/check_render.py docs/technical.html(0 error, both languages and themes, on a phone too) andpython3 <html-style>/scripts/sync_nav.py docs. Nodocs/yet: create the technical page withhtml-docfirst (ask its questions: logo...).
6. Check
python3 SKILL_DIR/scripts/check_protocol.py PROTOCOL.md [docs/technical.html] [--fr]It checks the anchors of the contents and of the tables (every link reaches a heading / an id), that every row of
the types table and of the command table has its section, the codes unique in each table, the frames of the summary
matching the grammar of their section (same type byte), no {{...}} placeholder and no typo of the reference left
(--fr: a document in French, informations and transfert are right there; the French of a bilingual page is skipped). What would not
show as written too: a table without an empty line before it, a code line over 110 characters (wider than a page of the PDF: one
field per line), a raw <tag> of a frame in the HTML, an HTML element inside a drawing.
Then report: the files written, the sections, what was marked TBD or differs from the code.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

