fraud-skills
Coding skills for Fraud Blocker workspace repos (cms, api, tracker)
Open source Open in the app JSON README (API)
About
Coding skills for Fraud Blocker workspace repos (cms, api, tracker)
Details
- Kind
- Plugins
- Topic
- Social & content
- Publisher
- thanhhai0311
- Origin
- gemini
- Category
- ferramentas
- Version
- 1.0.0
- Last push
- 2026-08-06T10:25:00Z
- Repository state
- ativo
- Language
- JavaScript
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
thanhhai0311/fraud-md
README
# Fraud Blocker Skills
Coding skills + workflow automation for all Fraud Blocker workspace repos. Covers architecture patterns, naming
conventions, and strict rules for 3 repos (`cms`, `api`, `tracker`), plus hooks, slash commands, and a bug-hunter
skill built on top of them.
---
## Installation
### Claude Code
**Bước 1 — Add marketplace (1 lần duy nhất):**
```sh
claude plugin marketplace add thanhhai0311/fraud-md
```
**Bước 2 — Install plugin:**
```sh
claude plugin install fraud-skills
```
**Bước 3 — Enable trong project** (`.claude/settings.json`):
```json
{
"enabledPlugins": {
"fraud-skills@fraud-skills-marketplace": true
}
}
```
Sau khi install, các thành phần xuất hiện dưới namespace `fraud-skills:`:
- Skills: `fraud-skills:cms`, `fraud-skills:api`, `fraud-skills:tracker`, `fraud-skills:critical-bug-hunter`
- Commands: `/fraud-skills:self-heal-tests`, `/fraud-skills:review-skill-gaps`
- Agent: `test-writer`
- Hooks: `inject-skill-by-path`, `review-enforcer`, `detect-workflow-mode` (đăng ký sẵn qua plugin manifest)
**Update plugin khi có skill mới:**
```sh
claude plugin update fraud-skills
```
**Local dev (không cần marketplace):**
```sh
claude plugin install /path/to/fraud-md
```
---
### Codex (OpenAI)
**Option 1 — Copy to project `.codex/skills/`:**
```sh
cp -r skills/* .codex/skills/
```
**Option 2 — Symlink:**
```sh
mkdir -p .codex/skills
for skill in skills/*/; do
ln -sf "$(pwd)/$skill" ".codex/skills/$(basename $skill)"
done
```
**Option 3 — Use `.codex-plugin/`** (if Codex supports plugin install):
```sh
codex plugin install /path/to/fraud-md
```
---
### Gemini CLI
```sh
# Copy gemini-extension.json and GEMINI.md to project root
cp gemini-extension.json ./
cp GEMINI.md ./
```
Or if Gemini CLI supports plugin install, point it at this directory.
---
### Cursor / Other AI editors
Copy the relevant `skills/<repo>/SKILL.md` content into the editor's custom instructions or rules file for that
project.
---
## Skills Index
| Skill | Repo | Stack | Use when |
|---|---|---|---|
| `cms` | `cms/` | Remix 2 / React 18 / Polaris / Redux Saga / React Query | Admin UI: routes, pages, components, Redux, service layer, Shopify extensions |
| `api` | `api/` | NestJS 11 / Mongoose / RabbitMQ / Redis | Backend: modules, controllers, services, repositories, consumers, outbox |
| `tracker` | `tracker/` | NestJS 11 / Mongoose / RabbitMQ / Redis | Tracking: storefront intake, rule/bot/IP evaluation, outbox events, contracts |
| `critical-bug-hunter` | all 3 | — | Deep-scan recent commits/PRs for high-severity correctness bugs |
---
## Plugin Structure
```
fraud-md/
├── .claude-plugin/
│ ├── plugin.json # Claude Code manifest
│ └── marketplace.json # Claude marketplace listing
├── .codex-plugin/
│ └── plugin.json # Codex manifest
├── gemini-extension.json # Gemini CLI extension
├── CLAUDE.md # Claude Code context (workflow, routing, MCP-by-phase)
├── GEMINI.md # Gemini CLI context
├── README.md # This file
├── skills/
│ ├── cms/SKILL.md
│ ├── api/SKILL.md
│ ├── tracker/SKILL.md
│ └── critical-bug-hunter/SKILL.md
├── commands/ # Slash commands (/self-heal-tests, /review-skill-gaps)
├── agents/ # Custom subagents (test-writer)
├── hooks/ # PreToolUse / SessionStart automation
│ ├── inject-skill-by-path.sh
│ ├── review-enforcer.sh
│ └── detect-workflow-mode.sh
├── rules/ # Cross-skill facts not tied to one SKILL.md
│ └── db-scale-and-security.md
├── scripts/ # Helper scripts used by hooks/skills
│ ├── search-known-error.sh
│ ├── search-skill-gaps.sh
│ └── check-rabbitmq-contract.mjs
├── agent-memory/ # Persistent memory for self-heal-tests / skill-gap tracking
│ ├── skill-gaps/
│ └── test-writer/
└── workflows/ # Reserved for multi-agent Workflow scripts
```
---
## Quick Reference
### Frameworks
| Repo | Framework | Module system |
|---|---|---|
| `cms` | Remix 2 + React 18 | ESM / TypeScript |
| `api` | NestJS 11 | ESM / TypeScript |
| `tracker` | NestJS 11 | ESM / TypeScript |
### Service roles
| Repo | Role |
|---|---|
| `cms` | Merchant-facing UI. No fraud decisions. No RabbitMQ. |
| `tracker` | Write-side. Owns storefront tracking, rule/IP/bot evaluation, sync publish. |
| `api` | Compatibility layer. Consumes RabbitMQ events from tracker, serves legacy reads. |
### RabbitMQ rules (api + tracker)
- Exchange always `'direct'`
- Never change routing key/queue on one side without updating the other
- Consumer on failure: `Nack(false)` — **never requeue**
- Always idempotency-check before handling (see `rules/db-scale-and-security.md`)
### Logger (api + tracker)
```typescript
private readonly logger = new Logger(ClassName.name);
this.logger.error('message', error);
this.logger.log('message');
```
### tracker storefront fast path
- `void asyncFn()` for slow work (proxy check, outbox write, GeoIP)
- Return `{ action }` immediately — never await enrichment on request path
- Rule evaluation order: WHITELIST → BLACKLIST → REDIRECT (first-match-wins)
---
## Recommended additional plugins
Plugin này chỉ cung cấp skills/hooks/rules riêng cho Fraud Blocker. Để làm việc thuận tiện hơn, nên cài thêm:
| Plugin | Marketplace | Vì sao cần | Cài đặt |
|---|---|---|---|
| `security-guidance` | `claude-plugins-official` | Bổ sung `security-review` skill + `claude-security` agent để scan diff/PR trước khi merge (workflow yêu cầu ở Phase 3 khi đụng `api/`/`tracker`) | `claude plugin marketplace add claude-plugins-official && claude plugin install security-guidance` |
| `shopify-plugin` | `shopify-ai-toolkit` | Cả 3 repo đều tích hợp Shopify (AppBridge, webhooks, Functions/extensions ở `cms`) — bổ sung skill cho Admin/Storefront GraphQL, Functions, CLI | `claude plugin marketplace add shopify/ai-toolkit && claude plugin install shopify-plugin` |
> Kiểm tra tên marketplace/plugin chính xác bằng `claude plugin marketplace list` sau khi add — tên package của
> bên thứ ba có thể đổi theo phiên bản.
---
## Recommended MCP servers
Các MCP server dưới đây không đi kèm plugin (vì cần chạy process/credentials riêng cho từng máy), nhưng
`CLAUDE.md` và các skill trong plugin này giả định chúng đã sẵn sàng ("MCP Tools by Phase"). Thiếu MCP nào thì
bước tương ứng trong workflow (Discovery/Implementation/Verification) sẽ phải làm tay.
### Code intelligence — bắt buộc để dùng đúng workflow Discovery
- **CodeGraph** (`codegraph_*` tools) — tree-sitter knowledge graph cho toàn bộ symbol/edge/file trong repo,
dùng thay grep khi cần trace caller/callee/impact. Plugin này được viết với giả định CodeGraph đã init
(`codegraph init -i`) cho mỗi repo (`api`, `cms`, `tracker`) và mount riêng từng MCP server instance
(`codegraph-api`, `codegraph-cms`, `codegraph-tracker`). Nếu team chưa có setup này, hỏi người quản lý hạ tầng
nội bộ trước khi thêm — đây thường là self-hosted server, không phải package public trên npm/PyPI.
### Database & cache — cần cho Implementation/Verification khi đụng schema/query
- **MongoDB MCP** — đọc schema/index thật, chạy `find`/`aggregate`/`count` để verify query mới thay vì đoán từ
code. Dùng connection string từ `api/.env` (`MONGODB_URI`) / `tracker/.env`, **không hardcode** khi add server.
```sh
claude mcp add mongodb -- npx -y mongodb-mcp-server --connectionString "$MONGODB_URI"
```
- **Redis MCP** — kiểm tra key pattern/TTL thật trước khi thêm cache key mới (theo `rules/db-scale-and-security.md`).
Chưa có server chính thức thống nhất; nếu team dùng community package, gắn theo tài liệu của package đó và
trỏ về Redis instance dev, không phải prod.
### Issue/ticket tracking — cho Discovery khi cần spec/ticket thật
- **Atlassian (Jira/Confluence) MCP** — pull ticket/spec thật thay vì suy diễn từ tên branch. Atlassian có Remote
MCP Server chính thức (OAuth, không cần self-host) — xem tài liệu Atlassian Developer để lấy URL + auth flow,
hoặc dùng community server (`mcp-atlassian`) nếu team tự host.
- **GitLab MCP** — check branch/MR/CI status thật trong Phase 3 (Verification) và Discovery.
```sh
claude mcp add gitlab -- npx -y @modelcontextprotocol/server-gitlab
```
(cần set `GITLAB_PERSONAL_ACCESS_TOKEN` qua env, không truyền trực tiếp trong command)
### Browser automation — cho Verification (E2E thật, không chỉ unit test)
- **Playwright MCP** — primary E2E runner theo `CLAUDE.md`.
```sh
claude mcp add playwright -- npx -y @playwright/mcp@latest
```
- **Puppeteer MCP** — supplementary, dùng khi cần điều khiển browser mức thấp hơn Playwright.
```sh
claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer
```
### Filesystem / memory / search — tiện ích chung, ít rủi ro nhất để bắt đầu
- **Filesystem MCP** — duyệt/đọc file ngoài project root khi cần so sánh với repo khác trong workspace.
```sh
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/workspace
```
- **Memory MCP** — lưu context giữa các session dài (đã có agent-memory riêng cho skill-gaps/test-writer trong
plugin này, nhưng Memory MCP hữu ích cho context ngoài phạm vi 2 nhóm đó).
```sh
claude mcp add memory -- npx -y @modelcontextprotocol/server-memory
```
- **DuckDuckGo MCP** — search nhanh không cần API key, dùng khi WebSearch built-in không đủ (ví dụ tra proxy/IP
reputation trong bot-detection).
> Tất cả lệnh `claude mcp add` trên chạy ở scope local theo mặc định. Muốn chia sẻ config MCP cho cả team, thêm
> `--scope project` và commit `.mcp.json` — nhưng **không commit credentials/connection string thật** vào đó;
> dùng biến môi trường (`${MONGODB_URI}` kiểu placeholder) và để mỗi máy set `.env` riêng.
---
## Updating Skills
When repo patterns change, update the corresponding `skills/<name>/SKILL.md`, then bump `version` in
`.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` before publishing:
```sh
vim skills/cms/SKILL.md
claude plugin update fraud-skills # if testing from an installed copy
```
Gap chưa merge vào skill → log vào `agent-memory/skill-gaps/entries/` theo `TEMPLATE.md`, merge qua
`/review-skill-gaps` khi đã xác nhận (không tự sửa `SKILL.md`/`rules/*.md` ngay trong task, xem `CLAUDE.md`).