Awesome-omni-skill privgraph

Privacy and security annotation for Mermaid diagrams. Use this skill when: (1) a user shares or creates a Mermaid flowchart or sequence diagram and asks for privacy, security, or compliance review, (2) a user asks to annotate a diagram with data classifications, controls, trust boundaries, or compliance scope, (3) a user mentions 'privgraph', '@pg:', or 'risk-informed diagram', (4) a user asks about data flow risks, missing controls, or GDPR/HIPAA/PCI compliance gaps in an architecture diagram, (5) a user is writing a design doc with Mermaid diagrams and wants privacy/security feedback embedded in the diagram itself. Do NOT use for general Mermaid syntax help, diagram styling, or non-security topics.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/development/privgraph" ~/.claude/skills/diegosouzapw-awesome-omni-skill-privgraph && rm -rf "$T"

manifest: skills/development/privgraph/SKILL.md

source content

PrivGraph: Mermaid Security & Privacy Annotation

PrivGraph annotates Mermaid diagrams with privacy and security metadata using comment-based directives, then evaluates configurable rules to surface control gaps.

Core Workflow

When a user presents a Mermaid diagram for privacy/security review:

Parse the diagram — identify nodes, edges, subgraphs, and any existing
```
@pg:
```
annotations
Classify — determine what data flows where (direct identifiers, health data, credentials, etc.)
Annotate — add
```
@pg:
```
directives as Mermaid comments for data classes, controls, boundaries, compliance
Evaluate — check the annotated diagram against the rule set (see
```
references/rules.yaml
```
)
Report — surface findings with severity, description, and remediation guidance

When a user asks to create a new annotated diagram from scratch, follow steps 2–5 after helping them build the diagram.

Annotation Syntax

All annotations are Mermaid comments and do not affect rendering:

%% @pg:<directive> <target> <parameters>

Directives

@pg:data-class

— classify data on a flow

%% @pg:data-class A-->B DIRECT_ID, LOCATION

@pg:control

— declare present or missing (

) controls on a node or flow

%% @pg:control UserDB encrypted-at-rest, access-controlled
%% @pg:control UserDB !retention-policy
%% @pg:control A-->B encrypted-in-transit

@pg:boundary

— declare trust boundary crossing on a flow

%% @pg:boundary A-->B third-party

@pg:compliance

— declare applicable compliance frameworks

%% @pg:compliance UserDB GDPR, CCPA

@pg:risk-accept

— suppress a rule finding with justification

%% @pg:risk-accept Cache PG-003 "24hr TTL enforced at Redis level. Approved 2024-01-10"

@pg:meta

— diagram-level metadata

%% @pg:meta owner "platform-team"
%% @pg:meta system "checkout-service"
%% @pg:meta reviewed "2024-01-15"

Data Classifications

Classification	Description	Examples
`DIRECT_ID`	Direct identifiers	Names, emails, SSNs, phone numbers
`INDIRECT_ID`	Indirect/pseudonymous identifiers	Opaque IDs, UUIDs, session tokens, pseudonyms
`PHI`	Protected health information	EHR, Diagnoses, prescriptions, lab results
`PCI`	Payment card data	Card numbers, CVVs
`CREDENTIALS`	Authentication secrets	Passwords, API keys, tokens
`BIOMETRIC`	Biometric data	Fingerprints, face data, voice prints
`LOCATION`	Location data	GPS coordinates, IP-derived location
`FINANCIAL`	Financial data	Bank accounts, transactions
`SENSITIVE`	Other sensitive data	Catch-all for sensitive categories
`PUBLIC`	Non-sensitive data	Public content, marketing copy

Controls

encrypted-at-rest

encrypted-in-transit

access-controlled

audit-logged

retention-policy

anonymized

minimized

consent-managed

dpa-in-place

Prefix with

to mark a control as explicitly missing.

Boundaries

internal

third-party

cross-region

cross-cloud

public-internet

user-device

Compliance Frameworks

GDPR

CCPA

HIPAA

PCI-DSS

SOC2

FERPA

Rule Evaluation

After annotating, evaluate the diagram against the rule set. Load

references/rules.yaml

for the full rule definitions. Here is the summary:

Rule	Sev	Trigger
PG-001	HIGH	DIRECT_ID/INDIRECT_ID/PHI flow missing `encrypted-in-transit`
PG-002	HIGH	DIRECT_ID/INDIRECT_ID/PHI node missing `encrypted-at-rest`
PG-003	MED	Sensitive data node missing `retention-policy`
PG-004	HIGH	CREDENTIALS flow missing encryption
PG-005	CRIT	DIRECT_ID to `third-party` missing `dpa-in-place`
PG-006	HIGH	PHI to `third-party` boundary
PG-007	MED	`cross-region` flow missing compliance annotation
PG-008	HIGH	HIPAA-scoped flow missing `audit-logged`
PG-009	MED	GDPR-scoped node missing `retention-policy`
PG-010	LOW	Flow crosses boundary with no controls documented
PG-011	INFO	Node has zero controls documented

For each violation, check if a

@pg:risk-accept

suppresses it (matching target + rule ID). Suppressed findings should be noted but not reported as active violations.

Reporting Format

Present findings grouped by severity. Use this structure:

## PrivGraph Review: [system name or file]

### Findings

🔴 **CRITICAL — PG-005: Direct Identifiers to Third Party Without DPA**
Flow: UserSvc → Analytics
DIRECT_ID is transferred to a third party without a documented DPA.
→ Add: `%% @pg:control Analytics dpa-in-place`

🟡 **HIGH — PG-001: Unencrypted Identifier Transfer**
Flow: Mobile → API
DIRECT_ID transferred without encryption in transit.
→ Add: `%% @pg:control Mobile-->API encrypted-in-transit`

### Summary
X critical, Y high, Z medium | N findings suppressed by @pg:risk-accept

Always output the complete annotated diagram (original diagram with all

@pg:

annotations added) so the user can copy-paste it directly.

Handling Ambiguity

When data classifications are unclear from the diagram alone:

Ask the user what data flows through ambiguous edges
Default to the more sensitive classification when context suggests it

Flag uncertain classifications with a comment:

%% TODO: Confirm data classification for A-->B

When a diagram has no annotations yet, annotate it fully rather than just listing what's missing. Show the user what a complete annotation looks like.

Supported Diagram Types

Flowcharts:
```
flowchart LR/TB/etc.
```
— nodes, edges, subgraphs all supported
Sequence diagrams:
```
sequenceDiagram
```
— participants map to nodes, messages map to edges, boxes map to subgraphs

For annotation target syntax in sequence diagrams, use participant names:

%% @pg:data-class Client->>Server DIRECT_ID

Examples

See

examples/flowchart-annotated.md

and

examples/sequence-annotated.md

for complete worked examples with annotations and findings.