AI Skill Report Card
Designing Communication Protocols
Protocol Design
Quick Start14 / 15
Given a protocol request (e.g., "design a federation handshake between MusGo nodes"), produce four artifacts in order:
- Protocol Design — purpose, actors, transport, message schema
- Message Flow — sequence diagram (text-based) of request/response exchanges
- Validation Rules — what makes a message valid/invalid, error codes
- Compatibility Matrix — version support table across implementations
Example skeleton:
Markdownundefined
Recommendation▾
Add a 'bad output' example (e.g., missing validation rules or unversioned protocol) to contrast good vs poor outcomes
Protocol Design
- Name: MusGo-Fed-Handshake-v1
- Transport: HTTPS + JSON, mTLS optional
- Actors: Node A (initiator), Node B (responder)
- Message types: HELLO, HELLO_ACK, CAPABILITY_EXCHANGE, ERROR
Message Flow
- A -> B: HELLO { node_id, protocol_version, nonce }
- B -> A: HELLO_ACK { node_id, protocol_version, nonce_signed }
- A -> B: CAPABILITY_EXCHANGE { supported_features[] }
- B -> A: CAPABILITY_EXCHANGE { supported_features[] }
Validation Rules
- nonce must be unique per session, expires in 60s
- protocol_version must match semver major
- reject if signature verification fails -> ERROR{code:401}
Compatibility Matrix
| Version | Supports mTLS | Supports Capability Exchange | Deprecated |
|---|---|---|---|
| v1.0 | No | Yes | No |
| v0.9 | No | No | Yes |
Workflow14 / 15
Progress:
- Clarify protocol scope: what problem is being solved (federation, messaging, auth handoff, etc.)
- Identify actors/roles and trust boundaries
- Choose transport & serialization (HTTP/JSON, gRPC/protobuf, WebSocket, etc.)
- Define message types and required/optional fields
- Draft message flow as ordered steps or sequence diagram
- Define validation rules per message type (schema, semantic, security)
- Define error handling and failure modes
- Define versioning scheme and backward-compatibility rules
- Produce compatibility matrix across known/anticipated versions
- Review for security gaps (replay, spoofing, downgrade attacks)
Recommendation▾
Include guidance on handling protocol negotiation/version mismatch failures explicitly in an example
Examples17 / 20
Example 1: Input: "Design a secure messaging protocol for MusGo peer nodes to exchange encrypted user messages." Output:
Protocol Design: MusGo-SecMsg-v1
- Transport: WebSocket over TLS 1.3
- Encryption: End-to-end via X25519 + AES-256-GCM
- Message types: MSG_SEND, MSG_ACK, KEY_EXCHANGE, MSG_ERROR
Message Flow:
1. Sender -> Recipient: KEY_EXCHANGE { ephemeral_pubkey }
2. Recipient -> Sender: KEY_EXCHANGE { ephemeral_pubkey }
3. Sender -> Recipient: MSG_SEND { ciphertext, nonce, sender_sig }
4. Recipient -> Sender: MSG_ACK { message_id, status }
Validation Rules:
- sender_sig must verify against sender's known public key
- nonce must not repeat within session (replay protection)
- ciphertext max size: 256KB, else reject with MSG_ERROR{code:413}
Compatibility Matrix:
| Version | E2E Encryption | Key Rotation | Deprecated |
|---------|---------------|--------------|------------|
| v1.0 | Yes | Manual | No |
Example 2: Input: "Federation protocol for interoperability between MusGo and an external identity provider." Output:
Protocol Design: MusGo-Fed-IDP-Bridge-v1
- Transport: HTTPS REST, OAuth2-compatible token exchange
- Actors: MusGo Node, External IDP
- Message types: TOKEN_REQUEST, TOKEN_RESPONSE, FEDERATION_ERROR
Message Flow:
1. MusGo -> IDP: TOKEN_REQUEST { client_id, grant_type, scope }
2. IDP -> MusGo: TOKEN_RESPONSE { access_token, expires_in, id_token }
3. MusGo validates id_token signature against IDP's published JWKS
Validation Rules:
- id_token must have valid iss, aud, exp claims
- reject tokens signed with unknown/rotated-out keys
- clock skew tolerance: 5 minutes
Compatibility Matrix:
| Version | OAuth2 | OIDC | SAML Fallback |
|---------|--------|------|----------------|
| v1.0 | Yes | Yes | No |
Recommendation▾
Consider trimming the Best Practices and Common Pitfalls sections slightly, as some overlap conceptually (e.g., versioning mentioned in both)
Best Practices
- Always version protocols explicitly (semver); never assume implicit compatibility.
- Design for graceful degradation — unknown fields should be ignorable, not fatal, unless marked required.
- Separate transport-layer security (TLS/mTLS) from application-layer security (signatures, encryption) and specify both.
- Always define nonce/timestamp-based replay protection for any stateful handshake.
- Make error responses structured (code + message + retryable flag), never plain strings.
- Keep compatibility matrix updated whenever a new version is introduced — never leave it implicit.
Common Pitfalls
- Do not skip the Validation Rules section — undefined validation leads to inconsistent implementations across nodes.
- Do not conflate authentication with authorization in message flow; keep them as distinct steps.
- Do not assume synchronous delivery — always account for retries, timeouts, and out-of-order messages in federation contexts.
- Do not version only the payload schema while ignoring the handshake/negotiation protocol itself.
- Do not omit downgrade-attack protection when supporting multiple protocol versions simultaneously.