protokol-ai

Distribute company AI rules and skills across all coding tools.

Uses the ecosystem-standard skill format (skills/*/SKILL.md) from agentskills.io — compatible with anthropics/skills, vercel-labs/skills, shadcn-ui/ui, and any repo that follows the convention.

Quick Start

npm install -g protokol-ai

Then in any project:

protokol-ai init     # choose what to install
protokol-ai sync     # apply rules and skills

Commands

| Command | Description | |---------|-------------| | protokol-ai init | Interactive setup — auto-detect with AI or pick manually | | protokol-ai sync | Sync rules and skills into the current project | | protokol-ai status | Show what's installed, stale, or missing | | protokol-ai learn | Auto-generate rules from lint configs + codebase patterns | | protokol-ai learn --skip-ai | Same as above but deterministic only (no AI) |

Maintainer-only (available when running from the protokol-ai repo):

| Command | Description | |---------|-------------| | protokol-ai add <source> | Install a skill pack from a git repo | | protokol-ai remove <pack> | Remove an installed pack | | protokol-ai packs | List installed packs | | protokol-ai update | Update all installed packs to latest |

How It Works

Skill Format

Skills follow the agentskills.io specification. Each skill is a directory with a SKILL.md:

skills/
  my-skill/
    SKILL.md          # YAML frontmatter (name, description) + instructions
    rules/            # optional: rule files injected into AGENTS.md
    hooks/            # optional: hook scripts → .claude/hooks/
    settings.json     # optional: settings fragment → merge into .claude/settings.json
    references/       # optional: additional documentation (loaded on-demand)
    assets/           # optional: templates, data files

Example SKILL.md:

---
name: my-skill
description: What this skill does. Use when working with X.
allowed-tools: Read Glob Grep Bash(git:*)
compatibility: Requires bash and jq. Unix/macOS/Linux only.
metadata:
  version: "1.0.0"
  timestamp: "2026-04-27"
  type: guardrail
  severity: critical
  inclusion: default
  activation: on-demand
---

Instructions for the AI agent...

| Field | Required | Description | |-------|----------|-------------| | name | Yes | Kebab-case, 1-64 chars, must match directory name | | description | Yes | What + when to use, max 1024 chars | | allowed-tools | No | Space-separated pre-approved tools (spec field) | | compatibility | No | Environment requirements, max 500 chars (spec field) | | user-invocable | No | Claude Code-specific. false = only Claude invokes; default true. Passed through verbatim. | | disable-model-invocation | No | Claude Code-specific. true = only user invokes. Passed through verbatim. | | metadata.version | No | Semver version | | metadata.timestamp | No | ISO date (YYYY-MM-DD) for audit trail | | metadata.type | No | One of: guardrail / workflow / reviewer / rule / reference | | metadata.severity | No | Only valid when type: guardrail. One of: critical / high / medium / low | | metadata.inclusion | No | mandatory (always installed) / default (auto-installed, removable) / optional (opt-in) | | metadata.activation | No | always (→ AGENTS.md) / on-demand (→ .agents/skills/) |

What Happens When You Sync

protokol-ai sync reads .protokol-ai.json and auto-detects which tools are present. It distributes skills to every detected target:

                            protokol-ai sync
                                  │
              ┌───────────┬───────┼────────┬───────────┐
              ▼           ▼       ▼        ▼           ▼
        .agents/skills/ .claude/ .cursor/ AGENTS.md  CLAUDE.md
        (on-demand)    skills/   rules/  (always-on  (@import)
                      (on-demand) (all)    rules)
              │           │       │        │
              ▼           ▼       ▼        ▼
          All tools   Claude   Cursor   All tools
         (cross-tool)  Code             (cross-tool)

Auto-detection: Sync checks for .claude/ and .cursor/ directories. .agents/skills/ is always written (cross-tool standard). Only detected tools get output.

Always-on rules → injected into AGENTS.md between managed markers. Read by all AI tools. On-demand skills → copied to .agents/skills/ and .claude/skills/. All skills → written to .cursor/rules/ as .mdc files. Hook scripts → copied to .claude/hooks/<skillId>/. Deterministic enforcement (Claude Code only). Settings → merged into .claude/settings.json. Hook wiring + deny rules.

After sync completes, a color-coded changelog shows what was added, updated, or removed.

| Output | Read by | Contains | |--------|---------|----------| | .agents/skills/ | All spec-compliant tools | On-demand skills (SKILL.md + references) | | .claude/skills/ | Claude Code | On-demand skills (native format) | | .cursor/rules/ | Cursor | All skills as .mdc files with Cursor frontmatter | | AGENTS.md | Claude, Codex, Cursor, Copilot, Gemini, Windsurf | Always-on rules | | CLAUDE.md | Claude Code | @import AGENTS.md | | .claude/hooks/ | Claude Code | Guardrail enforcement scripts | | .claude/settings.json | Claude Code | Hook wiring and configuration |

Configuration

Skills are selected in .protokol-ai.json (generated by init, or edit manually):

{
  "version": 1,
  "skills": {
    "protokol-code-style": { "version": "1.0.0" },
    "security-git-safety": { "version": "1.0.0" },
    "review-code": { "version": "1.1.0" }
  },
  "settings": true
}

Built-in Skills

The full, auto-generated catalog lives in docs/SKILLS.md. Run protokol-ai catalog to view it in the terminal. The highlights below are a curated subset.

On-demand skills (loaded when relevant):

| Skill | Description | |-------|-------------| | review-code | Review local diffs/staged changes with severity-tagged findings; supports parallel "team mode" | | pr-reviewer | Review an open PR (uses gh CLI) with structured feedback on quality, correctness, style | | ship | Branch, commit, push, and open PR in one command |

Always-on rules (injected into AGENTS.md):

| Skill | Description | |-------|-------------| | protokol-code-style | Consistent formatting, early returns, single responsibility | | protokol-no-any-types | No any types in TypeScript | | protokol-workflow | Conventional Commits, squash merge |

Security guardrails (always-on rules + deterministic hook enforcement):

| Guardrail | Blocks | Allows | |-----------|--------|--------| | security-dangerous-commands | rm -rf /, sudo, fork bombs, dd to disk | rm -rf ./node_modules | | security-git-safety | --force push, reset --hard, branch -D | --force-with-lease | | security-secret-protection | Reading .env/.ssh, writing API keys | Normal files | | security-exfiltration-prevention | curl\|bash, scp outbound, netcat | curl -o file | | security-file-protection | Writes to migrations/, terraform/, CI | Reads, explicit user instruction | | security-database | DROP TABLE, TRUNCATE, DELETE without WHERE | SELECT, DELETE...WHERE | | security-package-install | Silent npm install pkg, pip install pkg | npm install (no args), npm ci |

protokol-ai init

Interactive setup wizard:

• Auto-detect — detects claude or codex on your PATH, launches it to analyze the project (package.json, tsconfig.json, directory structure), and writes .protokol-ai.json. You'll see real-time streaming output as the agent works.
• Pick manually — interactive checkbox UI where you select which skills to install. Recommended items are pre-checked.

After either mode, sync runs automatically.

Note: Auto-detect uses your existing CLI subscription (Claude Max/Pro, OpenAI plan). It does not use API credits or require an API key.

protokol-ai learn

Auto-generates rules from your project's existing tooling:

Tier 1 — Deterministic (always runs): Parses JSON lint configs and generates matching AI rules:

• .eslintrc.json — extracts active rules like no-console, eqeqeq, etc.
• biome.json — extracts linter rules + formatter settings
• .prettierrc / .prettierrc.json — extracts formatting options
• tsconfig.json — extracts strict mode flags

Tier 2 — AI-powered (unless --skip-ai): Launches your AI agent to scan the codebase for:

• Naming conventions (files, variables, components)
• Import/export patterns
• Error handling patterns
• File structure conventions

Also passes any JavaScript-based lint configs (e.g., eslint.config.js) to the AI for extraction.

Generated rules are stored in .protokol-ai/learned/ as standard SKILL.md format and automatically picked up by sync.

Packs

Install skills from any git repo that has a skills/*/SKILL.md structure:

# Install from GitHub
protokol-ai add github:anthropics/skills
protokol-ai add github:shadcn-ui/ui

# Install from any git URL
protokol-ai add https://github.com/some-org/custom-skills.git

# Manage installed packs
protokol-ai packs      # list
protokol-ai update     # git pull all
protokol-ai remove skills

Packs are cloned to .protokol-ai/packs/<name>/ in the project directory. Their skills appear alongside built-in skills in init and sync.

Company whitelist: To restrict which repos your team can install, create allowed-sources.json in the protokol-ai repo:

{
  "sources": [
    {
      "source": "github:anthropics/skills",
      "name": "Anthropic Skills",
      "description": "Official Anthropic example skills",
      "tags": ["official"]
    },
    {
      "source": "github:protokol/*",
      "name": "Protokol Internal",
      "description": "Any repo from the protokol org"
    }
  ]
}

If allowed-sources.json doesn't exist, all sources are allowed.

Project Structure

protokol-ai/
├── skills/                    # built-in skills (shipped with the tool)
│   ├── protokol-code-style/
│   │   ├── SKILL.md
│   │   └── rules/
│   │       └── code-style.md
│   ├── security-git-safety/
│   │   ├── SKILL.md
│   │   ├── hooks/
│   │   │   └── block-git-destructive.sh
│   │   └── settings.json
│   ├── review-code/
│   │   └── SKILL.md
│   └── ...
├── settings/
│   └── settings.json          # default Claude Code hooks
├── prompts/
│   ├── init.md                # AI prompt for project analysis
│   └── learn.md               # AI prompt for convention detection
├── src/                       # CLI source code (TypeScript)
│   ├── cli.tsx
│   ├── commands/
│   └── lib/
├── tests/                     # vitest unit tests + integration tests
│   ├── adapters.test.ts
│   ├── catalog.test.ts
│   ├── detect-agent.test.ts
│   ├── inject.test.ts
│   └── integration.sh
├── package.json
└── README.md

In each project after sync:

your-project/
├── AGENTS.md                  # always-on rules for all AI tools (auto-managed)
├── CLAUDE.md                  # @import AGENTS.md
├── .agents/
│   └── skills/                # on-demand skills (cross-tool standard)
│       ├── review-code/
│       │   └── SKILL.md
│       └── ship/
│           └── SKILL.md
├── .claude/
│   ├── skills/                # on-demand skills (Claude Code native)
│   │   ├── review-code.md
│   │   └── ship.md
│   ├── hooks/                 # guardrail enforcement scripts
│   │   ├── security-dangerous-commands/
│   │   └── security-git-safety/
│   └── settings.json          # hook wiring + config
├── .cursor/
│   └── rules/                 # all skills as Cursor .mdc rules
│       ├── protokol-review-code.mdc
│       └── protokol-security-git-safety.mdc
├── .protokol-ai.json          # config: what's selected
└── .protokol-ai/
    ├── packs/                 # installed external packs
    └── learned/               # auto-generated from lint configs / AI

Development

npm install
npm run dev -- sync           # run CLI in dev mode
npm test                      # run vitest unit tests
npm run build                 # compile to dist/
bash tests/integration.sh     # run full integration tests (requires build)

Updating

cd /path/to/protokol-ai
git pull
protokol-ai sync     # re-sync with latest rules

Uninstall

npm uninstall -g protokol-ai