compliance-agent-skills

Deterministic USA compliance auditing for AI agents — progressive-disclosure Agent Skills, a Presidio PHI redaction gate, MCP integrations, and IDE plugins for HIPAA, HITECH, PCI-DSS v4.0, SOC 2, ISO 27001, NIST CSF 2.0, CCPA/CPRA, US state privacy laws, GDPR, FedRAMP, SOX, CMMC, and GLBA/FFIEC workflows.

Disclaimer: This repository provides operational audit patterns and automation templates. It is not legal advice and does not replace a Qualified Security Assessor (QSA), HIPAA Privacy Officer, or licensed CPA for SOC 2 attestation.

Coverage: 30 skills across HIPAA, PCI-DSS, SOC 2, FedRAMP, CMMC, GLBA, SOX, privacy, NIST AI RMF, FERPA, COPPA, and cross-cutting agent controls. Reference checklists include provenance footers and CI-enforced SME review metadata — see docs/sme-review.md. Full feature list: docs/project-status.md.

Why this exists

LLM agents can accelerate compliance work, but they must not:

• Invent regulatory steps or cite non-existent requirements
• Send raw ePHI or cardholder data to model providers
• Produce unauditable "compliant" claims without evidence

compliance-agent-skills addresses this with:

1. 30 specialized skills with explicit triggers, anti-patterns, and output artifacts
2. Mandatory PHI redaction (redaction.py) before any user text reaches the model
3. Audit lifecycle commands — /scope, /audit, /evidence, /remediate, /report
4. MCP templates for Playwright DOM audits, Postgres evidence queries, Presidio DLP, Slack notifications, GitHub change tracking, and Terraform drift
5. IDE install surfaces — VS Code extension and JetBrains plugin

Quick start

Prerequisites

• Python 3.11+
• Node.js 18+ (for VS Code extension build; optional)
• JDK 17+ (for JetBrains plugin build; optional)
• spacy model en_core_web_sm (installed automatically via requirements.txt)

Bootstrap (recommended)

macOS / Linux:

git clone https://github.com/vaquarkhan/compliance-agent-skills.git
# or: git clone [email protected]:vaquarkhan/compliance-agent-skills.git
cd compliance-agent-skills
chmod +x bootstrap.sh
./bootstrap.sh

Windows (PowerShell):

git clone https://github.com/vaquarkhan/compliance-agent-skills.git
cd compliance-agent-skills
.\bootstrap.ps1

The installer detects your IDE (Cursor, VS Code, Claude Code, JetBrains) and copies skills, presets, rules, hooks, and MCP templates to the appropriate config directories.

Run the agent locally

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
pip install -r requirements-lock.txt

export OPENAI_API_KEY=sk-...   # or ANTHROPIC_API_KEY
python agent.py "Scope a HIPAA PHI redaction review for our LLM intake pipeline"

Without API keys, the agent falls back to Pydantic AI TestModel for local development.

Deanonymization is opt-in. By default, agent output keeps redacted tokens (<PERSON_1>). To restore original PHI for an authorized downstream channel only:

from agent import run_compliance_agent_sync

# Default — redacted output (safe)
run_compliance_agent_sync("Review Jane Doe SSN 123-45-6789")

# Authorized restore — explicit opt-in
run_compliance_agent_sync("Review Jane Doe SSN 123-45-6789", deanonymize_output=True)
# or: COMPLIANCE_AGENT_DEANONYMIZE=1 python agent.py "..."

Run the no-API-key demo: python scripts/demo_agent.py or make demo.

Validate the repository

make validate   # or run scripts individually
make test       # requires: pip install -r requirements-lock.txt -r requirements-dev.txt
make lint       # ruff check + format
make security   # pip-audit, bandit, detect-secrets

Engineering: CI enforces lint, mypy, security scans (pip-audit, Bandit, detect-secrets, CodeQL), and ≥80% coverage on agent.py + redaction.py. See docs/architecture.md, docs/sme-review.md, and docs/redaction-limitations.md.

Locked dependencies: Reproducible installs use requirements-lock.txt (compile with make lock from requirements.in).

Regulatory reports: Structured /report outputs via docs/regulatory-reports.md and make report INPUT=... OUTPUT=....

SME review: All reference checklists include provenance footers; CI enforces via docs/sme-review.md and make validate-sme.

Plugin installation

Cursor

Run ./bootstrap.sh --target cursor or follow docs/cursor-setup.md. Installs:

• .cursor/rules/ — compliance core, deterministic audit, PHI redaction, framework routing
• Skills symlink/copy to project or global skills directory
• MCP templates from mcp/
• Hooks from hooks/

VS Code / GitHub Copilot

./bootstrap.sh --target vscode

Or install the bundled extension:

cd vscode-extension && npm install && npx vsce package
code --install-extension compliance-agent-skills-*.vsix

See docs/vscode-setup.md and .github/copilot-instructions.md.

Claude Code / Claude Desktop

./bootstrap.sh --target claude

Copies .claude/commands/ lifecycle commands and CLAUDE.md. See docs/claude-setup.md.

JetBrains (IntelliJ, PyCharm, etc.)

Build and install from jetbrains-plugin/:

cd jetbrains-plugin && ./gradlew buildPlugin

See docs/jetbrains-setup.md.

Audit lifecycle commands

Example engagement flow:

/scope  →  /audit (pci-dss-script-audit)  →  /evidence  →  /remediate  →  /report

Skills catalog

30 skills organized by framework. Full catalog: skills-index.md.

Load skills progressively — only pull in what matches the task. See AGENTS.md for routing.

Frameworks

HIPAA

Security Rule (45 CFR §164.312), Breach Notification (§164.400–414), BAA review (§164.502(e)). Skills cover technical safeguards, Presidio redaction pipelines, and vendor BAAs.

Preset: presets/healthcare-hipaa/PRESET.md
Starter pack: starter-packs/hipaa-healthcare-starter.yaml

PCI-DSS

v4.0 Requirements 1–2 (network), 6.4.3 / 11.6.1 (payment-page scripts), 7–8 (access), 10 (logging).

Preset: presets/fintech-pci-dss/PRESET.md
Starter pack: starter-packs/pci-dss-ecommerce-starter.yaml

SOC 2

AICPA Trust Services Criteria (2017 + 2022 revisions): Security, Availability, Confidentiality, Processing Integrity, Privacy.

Preset: presets/saas-soc2-type2/PRESET.md
Starter pack: starter-packs/soc2-saas-starter.yaml

ISO 27001

ISO/IEC 27001:2022 Annex A controls, Statement of Applicability, risk treatment.

Related skill: iso27001-annex-a-controls
Template: templates/iso27001-statement-of-applicability.yaml

NIST CSF 2.0

Govern, Identify, Protect, Detect, Respond, Recover gap assessments and organizational profiles.

Related skill: nist-csf-2-assessment
Template: templates/nist-csf-profile.yaml

CCPA / CPRA

California consumer privacy rights, DSAR workflows, service provider contracts.

Related skill: ccpa-cpra-privacy-rights
Template: templates/dsar-request-log.yaml

FedRAMP

FedRAMP Moderate baseline, NIST SP 800-53 Rev 5, SSP/POA&M/ConMon authorization packages.

Related skill: fedramp-moderate-baseline
Template: templates/fedramp-ssp-outline.yaml

SOX

Sarbanes-Oxley IT general controls (SOX 404) — access, change, development, operations.

Related skill: sox-itgc-audit
Template: templates/sox-itgc-control-matrix.yaml

CMMC

CMMC 2.0 Level 2, CUI, NIST SP 800-171, SPRS scoring for defense supply chain.

Related skill: cmmc-nist-800-171
Template: templates/cmmc-poam.yaml

GLBA / FFIEC

GLBA Safeguards and Privacy Rules, FFIEC IT handbook alignment for financial institutions.

Related skill: glba-ffiec-financial-privacy
Preset: presets/financial-services-glba/PRESET.md
Starter pack: starter-packs/multinational-privacy-starter.yaml

NIST AI RMF

Trustworthy AI governance (GOVERN, MAP, MEASURE, MANAGE) for LLM agents and MCP toolchains.

Related skill: nist-ai-rmf-governance
Template: templates/nist-ai-rmf-profile.yaml

FERPA

Student education records, school official DPAs, and legitimate educational interest for EdTech agents.

Related skill: ferpa-education-records
Template: templates/ferpa-school-official.yaml

COPPA

FTC children's privacy — verifiable parental consent and service provider rules for under-13 users.

Related skill: coppa-children-privacy
Template: templates/coppa-parental-consent.yaml
Preset: presets/edtech-youth-privacy/PRESET.md
Starter pack: starter-packs/edtech-youth-privacy-starter.yaml

HITECH

HITECH Act breach notification depth—OCR portal, unsecured PHI, BA liability, penalty tiers. Use after breach-incident-response containment.

Related skill: hitech-breach-notification
Template: templates/hitech-breach-workbook.yaml

US state privacy

Comprehensive state laws: VCDPA, CPA, TDPSA, CTDPA, OCPA, and harmonized multi-state programs.

Related skill: us-state-privacy-laws
Reference: references/us-state-privacy-matrix.md

GDPR (US multinationals)

EU/EEA processing, RoPA, SCCs/DPF, 72-hour breach, DPIA for agent/LLM cross-border transfers.

Related skill: gdpr-us-multinational
Template: templates/gdpr-ropa-template.yaml
Preset: presets/multinational-privacy/PRESET.md
Starter pack: starter-packs/multinational-privacy-starter.yaml

Project structure

compliance-agent-skills/
├── agent.py                 # Pydantic AI entry + SkillsCapability
├── redaction.py             # Presidio PHI redaction gate
├── requirements.txt
├── skills/                  # 30 Agent Skills (SKILL.md each)
├── presets/                 # Framework + cloud presets
├── starter-packs/           # Curated skill + template bundles
├── templates/               # YAML/MD audit artifacts
├── references/              # Checklists and pattern guides
├── registry/assets.json     # Machine-readable asset index
├── mcp/                     # MCP server templates
├── hooks/                   # Session hooks (PHI guard, audit mode)
├── docs/                    # Setup and authoring guides
├── .cursor/rules/           # Cursor agent rules
├── .claude/commands/        # Lifecycle slash commands
├── agents/                  # Persona prompts (architect, QSA, etc.)
├── examples/                # Runnable audit examples
├── scripts/                 # install + validation
├── vscode-extension/
└── jetbrains-plugin/

MCP integrations

Pre-configured templates in mcp/ for compliance audit workflows:

See mcp/README.md and skill mcp-compliance-integration.

Examples

Documentation

License

MIT — see LICENSE.

Acknowledgments

Built on Pydantic AI, Microsoft Presidio, and the Agent Skills progressive-disclosure pattern.