marketing-shibata50/claude-code-ultimate-guide
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(security): add threat intelligence DB, security commands, and cheatsheet audit fixes (v3.26.0)

Browse source 
- Add threat-db.yaml v2.0.0 with 63 malicious skills, 22 CVEs, 4 campaigns
- Add /security-check, /security-audit, /update-threat-db slash commands
- Add Snyk ToxicSkills evaluation (58th resource evaluation)
- Fix cheatsheet: add Alt+T to keyboard shortcuts table, add /fast and /debug commands
- Update Features Meconnues table with Agent Teams and Auto-Memories
- Clean up cheatsheet.md.bak
- Bump version to 3.26.0

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX 2026-02-11 16:12:36 +01:00
parent 1b04bdbcf5
commit 971a297db3
14 changed files with 1209 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

62
CHANGELOG.md
View file

@ -8,41 +8,55 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
<!-- New entries go here -->
## [3.26.0] - 2026-02-11
### Added
- **Security Threat Intelligence Database** (`examples/commands/resources/threat-db.yaml` v2.0.0)
- Comprehensive threat DB compiled from Perplexity Deep Research across 15 sources
- **63 malicious skills** catalogued (ClawHavoc 341 skills, Snyk ToxicSkills, PyPI supply chain)
- **22 CVEs** tracked with component, severity, fixed_in version, and mitigation
- **4 campaigns** documented: ClawHavoc (AMOS), ToxicSkills, PyPI MCP reverse shell, Postmark npm squatter
- **IOCs**: 6 C2 IPs, exfiltration endpoints, malicious GitHub repos, malware hashes
- **17 malicious skill patterns** for wildcard matching (prefix-based scanning)
- **10 minimum safe versions** quick reference for MCP servers
- **8 attack techniques** taxonomy (T001-T008) mapped to campaigns
- **6 scanning tools** documented (mcp-scan, skills-ref, Garak, MCP Fortress, SafeDep vet, Koi Clawdex)
- **5 defensive resources** (SAFE-MCP framework, VirusTotal integration, Docker MCP Gateway, Snyk AI-BOM, Bitsight TRACE)
- Sources: Koi Security, Snyk, JFrog, Flatt Security, SentinelOne, Cymulate, Checkpoint, Bitsight, SafeDep, SAFE-MCP
- **New Slash Command**: `/security-check` (`examples/commands/security-check.md`)
- Quick (~30s) configuration security check against known threats database
- 7 phases: Load threat DB → MCP audit → Skills/agents audit → Hook security → Memory poisoning → Permissions → Exposed secrets
- Outputs CRITICAL/HIGH/MEDIUM/LOW findings with exact fix commands
- **New Slash Command**: `/security-audit` (`examples/commands/security-audit.md`)
- Full 6-phase security audit with scored posture assessment (/100, grades A-F)
- Phases: Config (via /security-check) → Secrets scan → Injection surface → Dependencies → Hook security → Posture score
- Includes benchmark against security-hardening.md recommendations
- **New Slash Command**: `/update-threat-db` (`examples/commands/update-threat-db.md`)
- Research & update the threat intelligence database via Perplexity searches
- 6 phases: Assess current state → 4 targeted searches → Deduplicate → Update YAML → Cascade to guides → Summary report
- Designed for monthly maintenance or post-advisory updates
- **Threat DB Badge** in README: red badge linking to security-hardening.md showing CVE and malicious skill counts
- **Resource Evaluation**: "AI Fatigue is Real" by Siddhant Khare (`docs/resource-evaluations/siddhant-khare-ai-fatigue.md`)
- Evaluated blog post on AI-induced exhaustion and productivity paradoxes
- Score: 3/5 (Pertinent — complément utile)
- 90% content overlap with existing `learning-with-ai.md`, but identified session time-boxing gap
- Technical-writer challenge downgraded from initial 4/5 to 3/5
- Fact-check confirmed: 0 research citations (anecdotal only) vs guide's peer-reviewed RCTs
- Extracted: Time-boxing tactics (30 min limit, 3 attempts max), nondeterminism stress recognition
- Score: 3/5 — Time-boxing tactics, nondeterminism stress recognition
### Changed
- **README**: Commands count updated 18→22, 3 new security commands listed in examples library
- **CLAUDE.md**: Slash commands table updated with `/security-check`, `/security-audit`, `/update-threat-db`
- **reference.yaml**: 4 new entries (security_check_command, security_audit_command, security_threat_db, security_update_threat_db)
- **Learning Guide Enhancement**: AI fatigue symptom recognition integrated into `guide/learning-with-ai.md`
- **Red Flags Checklist** (line 869): Added "Prolonged sessions without breaks" with time-boxing mitigation (30 min limit, max 3 attempts before manual implementation)
- **Productivity Reality** (line 115): Added paragraph on nondeterminism stress (identical prompts → varying outputs causes "AI fatigue")
- **UVAL Protocol** (line 247): Added "Step 2.5: Recognize Fatigue Signals" checkpoint (session duration, retry count, frustration assessment)
- **Total footprint**: ~200 words across 3 locations (minimal integration)
- **Rationale**: Addresses session-level time-boxing gap (distinct from existing weekly 70/30 split)
- Red Flags Checklist, Productivity Reality, UVAL Protocol sections updated
### Fixed
- **Extended Thinking Documentation**: Corrected `effort` parameter documentation based on [official Anthropic docs](https://platform.claude.com/docs/en/build-with-claude/effort)
- **API Syntax** (line 10408-10416): `thinking={"type": "adaptive", "effort": "high"}` → `output_config={"effort": "medium"}` (correct parameter name)
- **Scope Clarification** (line 10398-10400): `effort` controls **entire response** (text, tool calls, thinking), not just thinking tokens
- **Official Descriptions** (line 10402-10406): Replaced generic descriptions with official Anthropic definitions
- `max`: Maximum capability, no constraints (Opus 4.6 only — errors on other models)
- `high`: Complex reasoning, coding, agentic tasks (default)
- `medium`: Balance speed/cost/performance
- `low`: Most efficient for classification, lookups, sub-agents
- **Control Table** (line 10441): Opus 4.5 supports `low|medium|high`, Opus 4.6 adds `max`
- **New Subsection**: "Effort and Tool Use" (line 10418-10425) — explains impact on tool call behavior
- **Relationship Clarification** (line 10427-10431):
- Opus 4.6: `effort` recommended, `budget_tokens` deprecated
- Opus 4.5: both `effort` and `budget_tokens` work in parallel
- Without thinking: `effort` still controls text + tools
- API syntax, scope clarification, official descriptions, control table, effort and tool use subsection
## [3.25.0] - 2026-02-10

6
CLAUDE.md
View file

@ -83,6 +83,9 @@ Custom slash commands available in this project:
| `/changelog [count]` | View recent CHANGELOG entries (default: 5) |
| `/sync` | Check guide/landing synchronization status |
| `/audit-agents-skills [path]` | Audit quality of agents, skills, and commands in .claude/ config |
| `/security-check` | Quick config check against known threats database (~30s) |
| `/security-audit` | Full 6-phase security audit with score /100 (2-5min) |
| `/update-threat-db` | Research & update threat intelligence database |
**Examples:**
```
@ -97,6 +100,9 @@ Custom slash commands available in this project:
/audit-agents-skills # Audit current project
/audit-agents-skills --fix # Audit + fix suggestions
/audit-agents-skills ~/other # Audit another project
/security-check # Quick scan config vs known threats
/security-audit # Full audit with posture score /100
/update-threat-db # Research + update threat-db.yaml
```
These commands are defined in `.claude/commands/` and automate:

11
README.md
View file

@ -6,9 +6,10 @@
<p align="center">
<a href="https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers"><img src="https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=for-the-badge" alt="Stars"/></a>
<a href="./CHANGELOG.md"><img src="https://img.shields.io/badge/Updated-Feb_10,_2026_·_v3.24.0-brightgreen?style=for-the-badge" alt="Last Update"/></a>
<a href="./CHANGELOG.md"><img src="https://img.shields.io/badge/Updated-Feb_11,_2026_·_v3.26.0-brightgreen?style=for-the-badge" alt="Last Update"/></a>
<a href="./quiz/"><img src="https://img.shields.io/badge/Quiz-257_questions-orange?style=for-the-badge" alt="Quiz"/></a>
<a href="./examples/"><img src="https://img.shields.io/badge/Templates-111-green?style=for-the-badge" alt="Templates"/></a>
<a href="./guide/security-hardening.md"><img src="https://img.shields.io/badge/🛡️_Threat_DB-22_CVEs_·_341_malicious_skills-red?style=for-the-badge" alt="Threat Database"/></a>
</p>
<p align="center">
@ -99,7 +100,7 @@ graph LR
│
├─ 📋 examples/ 111 Production Templates
│ ├─ agents/ 6 custom AI personas
│ ├─ commands/ 18 slash commands
│ ├─ commands/ 22 slash commands
│ ├─ hooks/ 18 security hooks (bash + PowerShell)
│ ├─ skills/ 1 meta-skill (Claudeception)
│ └─ scripts/ Utility scripts (audit, search)
@ -167,7 +168,7 @@ Complete guides with rationale and examples:
### 📚 106 Annotated Templates
Educational templates with explanations:
- Agents (6), Commands (18), Hooks (18), Skills
- Agents (6), Commands (22), Hooks (18), Skills
- Comments explaining **why** each pattern works
- Gradual complexity progression
@ -406,7 +407,7 @@ Claude Code sends your prompts, file contents, and MCP results to Anthropic serv
**Agents** (6): [code-reviewer](./examples/agents/code-reviewer.md), [test-writer](./examples/agents/test-writer.md), [security-auditor](./examples/agents/security-auditor.md), [refactoring-specialist](./examples/agents/refactoring-specialist.md), [output-evaluator](./examples/agents/output-evaluator.md), [devops-sre](./examples/agents/devops-sre.md) ⭐
**Slash Commands** (18): [/pr](./examples/commands/pr.md), [/commit](./examples/commands/commit.md), [/release-notes](./examples/commands/release-notes.md), [/diagnose](./examples/commands/diagnose.md), [/security](./examples/commands/security.md), [/refactor](./examples/commands/refactor.md), [/explain](./examples/commands/explain.md), [/optimize](./examples/commands/optimize.md), [/ship](./examples/commands/ship.md)...
**Slash Commands** (22): [/pr](./examples/commands/pr.md), [/commit](./examples/commands/commit.md), [/release-notes](./examples/commands/release-notes.md), [/diagnose](./examples/commands/diagnose.md), [/security](./examples/commands/security.md), [/security-check](./examples/commands/security-check.md) **, [/security-audit](./examples/commands/security-audit.md) **, [/update-threat-db](./examples/commands/update-threat-db.md) **, [/refactor](./examples/commands/refactor.md), [/explain](./examples/commands/explain.md), [/optimize](./examples/commands/optimize.md), [/ship](./examples/commands/ship.md)...
**Security Hooks** (18): [dangerous-actions-blocker](./examples/hooks/bash/dangerous-actions-blocker.sh), [prompt-injection-detector](./examples/hooks/bash/prompt-injection-detector.sh), [unicode-injection-scanner](./examples/hooks/bash/unicode-injection-scanner.sh), [output-secrets-scanner](./examples/hooks/bash/output-secrets-scanner.sh)...
@ -510,7 +511,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
---
*Version 3.24.0 | Updated daily · Feb 10, 2026 | Crafted with Claude*
*Version 3.26.0 | Updated daily · Feb 11, 2026 | Crafted with Claude*
<!-- SEO Keywords -->
<!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,

2
VERSION
View file

@ -1 +1 @@
3.24.0
3.26.0

BIN
cheatsheet.pdf
View file

Binary file not shown.

3
docs/resource-evaluations/README.md
View file

@ -65,7 +65,8 @@ Les documents de travail bruts (prompts Perplexity, audits clients) restent dans
| **Awesome Claude Skills** (BehiSecc) | 3/5 | **3/5** | ✅ Mention spécialisée | [awesome-claude-skills-github.md](./awesome-claude-skills-github.md) |
| **Wasp Fullstack Essentials** (Vinny @ Wasp) | 3/5 | **3/5** | ✅ Intégrer concepts framework-agnostiques | [wasp-fullstack-essentials-eval.md](./wasp-fullstack-essentials-eval.md) |
| **Master Claude Code Infographic** (Rakesh Gohel / Aakash Gupta) | 2/5 | **2/5** | ❌ Ne pas intégrer (surface-level, erreur Cursor) | [rakesh-gohel-aakash-gupta-master-claude-code.md](./rakesh-gohel-aakash-gupta-master-claude-code.md) |
| **Snyk ToxicSkills** (Supply Chain Audit) | 4/5 | **4/5** | ✅ Intégré (security-hardening.md §1.1, §1.2, §1.5) | [snyk-toxicskills-evaluation.md](./snyk-toxicskills-evaluation.md) |
---
**Dernier update**: 2026-02-10 (57 évaluations)
**Dernier update**: 2026-02-11 (58 évaluations)

73
docs/resource-evaluations/snyk-toxicskills-evaluation.md Normal file
View file

@ -0,0 +1,73 @@
# Resource Evaluation: Snyk ToxicSkills — Malicious AI Agent Skills Audit
| Field | Value |
|-------|-------|
| **Resource** | [Snyk ToxicSkills Blog](https://snyk.io/fr/blog/toxicskills-malicious-ai-agent-skills-clawhub/) |
| **Type** | Security research + open-source tool |
| **Published** | 2026-02-05 |
| **Relayed by** | Victor Langlois (LinkedIn) |
| **Score** | **4/5** (High Value) |
| **Action** | Integrated — enriched security-hardening.md (CVE, stats, new section §1.5) |
---
## Summary
Snyk scanned **3,984 AI agent skills** across ClawHub and skills.sh marketplaces, finding:
1. **36.82%** (1,467 skills) contain security flaws
2. **534 skills** flagged critical (malware, prompt injection, exposed secrets)
3. **76 malicious payloads** identified (credential theft, backdoors, data exfiltration — 8 still active on ClawHub at publication)
4. **10.9%** of ClawHub skills contain hardcoded secrets
5. **2.9%** fetch and execute remote content dynamically
6. **mcp-scan**: open-source tool achieving 90-100% recall on confirmed malicious skills, 0% false positives on top-100 legitimate skills
## Gap Analysis
| Topic | Before (guide) | After |
|-------|----------------|-------|
| Supply chain stats | 8-14% (SafeDep) | 36.82% (Snyk, 3,984 skills corpus) |
| Audit tools | skills-ref validate | + mcp-scan (Snyk) |
| Attack categories | Generic (injection, exfil, privesc) | 8 detailed policies (hardcoded secrets, remote prompt exec, malicious downloads) |
| .claude/ attack vector | 1-line mention (line 199) | Full section §1.5 with checklist |
| Malicious hooks/commands | Not covered | Documented with audit checklist |
| Recent CVEs | 5 CVEs (2025) | + CVE-2026-24052, CVE-2025-66032 |
## Fact-Check
| Claim | Verified | Source |
|-------|----------|--------|
| 3,984 skills scanned | Yes | Snyk blog |
| 36.82% with flaws (1,467/3,984) | Yes | Snyk blog |
| 534 critical | Yes | Snyk blog (13.4% of total) |
| 76 malicious payloads | Yes | Snyk blog (8 still active on ClawHub) |
| mcp-scan 90-100% recall | Yes | Snyk blog (0% FP on top-100 legit) |
| "91% combine injection + code" | Not verified | LinkedIn post stat, not in Snyk blog. Excluded from integration. |
| CVE-2026-24052 (SSRF Claude Code) | Yes | SentinelOne vulnerability database |
| CVE-2025-66032 (8 bypasses) | Yes | Flatt Security research |
## Score Justification
**4/5 (High Value)** — not 5/5 because:
- The guide already covers ~70% of the scope (security-hardening.md §1.1-1.4)
- This is an enrichment (updated stats, new tool, new section), not a gap-from-scratch
- Snyk stats are more recent and larger corpus than existing SafeDep data
- mcp-scan fills a concrete tooling gap
- The .claude/ attack surface section addresses a real blind spot
## Integration Plan
1. **§1.1 CVE Summary**: +2 CVEs (CVE-2026-24052, CVE-2025-66032)
2. **§1.2 Supply Chain**: Replace SafeDep stats with Snyk (larger corpus), add mcp-scan
3. **MCP Safe List**: Add mcp-scan entry
4. **New §1.5**: Malicious Extensions (.claude/ Attack Surface) with audit checklist
5. **reference.yaml**: Add entries for new sections
## References
- **Snyk ToxicSkills**: [snyk.io/blog/toxicskills](https://snyk.io/fr/blog/toxicskills-malicious-ai-agent-skills-clawhub/)
- **mcp-scan**: [github.com/snyk/mcp-scan](https://github.com/snyk/mcp-scan)
- **CVE-2026-24052**: [SentinelOne](https://sentinelone.com/vulnerability-database/)
- **CVE-2025-66032**: [Flatt Security](https://flatt.tech/research/posts/)
- **SafeDep (previous source)**: [safedep.io/agent-skills-threat-model](https://safedep.io/agent-skills-threat-model)

243
examples/commands/security-audit.md Normal file
View file

@ -0,0 +1,243 @@
# Security Audit
Comprehensive security audit of your project AND Claude Code configuration. Analyzes secrets exposure, injection surfaces, dependencies, hook security, and produces a scored security posture assessment.
**Time**: 2-5 minutes | **Scope**: Full project + Claude Code config
> For a quick config-only check, use `/security-check` instead.
## Instructions
You are a senior application security engineer. Perform a 6-phase security audit and produce a scored report with prioritized remediation plan.
---
### Phase 1: Configuration Security (via /security-check)
Execute all checks from `/security-check` (the `examples/commands/security-check.md` command). This covers:
- MCP server audit against CVE database
- Skills & agents against known malicious entries
- Hook exfiltration patterns
- Memory poisoning detection
- Permissions & settings review
- Exposed secrets in Claude Code config
Record findings — they contribute to the final score.
---
### Phase 2: Project Secrets Scan
Scan the entire project for exposed secrets and credentials:
```bash
# API keys and tokens
grep -rn --include="*.{js,ts,py,go,java,rb,php,yaml,yml,json,toml,env,cfg,ini,conf}" \
-E '(?i)(api[_-]?key|apikey|secret|password|passwd|token|bearer|auth)\s*[=:]\s*["'\''"][^"'\'']{8,}["'\''"]\s' \
--exclude-dir={node_modules,vendor,.git,dist,build,target,__pycache__,.venv} . 2>/dev/null | head -30
# Known provider key patterns
grep -rn -E 'sk-[a-zA-Z0-9]{20,}|sk-ant-[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36}|AKIA[A-Z0-9]{16}|xox[bps]-[a-zA-Z0-9\-]{20,}' \
--exclude-dir={node_modules,vendor,.git,dist,build,target} . 2>/dev/null | head -20
# Private keys
grep -rn 'BEGIN.*PRIVATE KEY' --exclude-dir={node_modules,vendor,.git} . 2>/dev/null
# .env files that might be committed
find . -name ".env*" -not -path "*/node_modules/*" -not -path "*/.git/*" -type f 2>/dev/null
# Check .gitignore coverage
[ -f ".gitignore" ] && {
grep -q "\.env" .gitignore && echo "✅ .env in .gitignore" || echo "⚠️ .env NOT in .gitignore"
grep -q "\.pem" .gitignore && echo "✅ .pem in .gitignore" || echo "⚠️ .pem NOT in .gitignore"
grep -q "\.key" .gitignore && echo "✅ .key in .gitignore" || echo "⚠️ .key NOT in .gitignore"
}
```
**Scoring:**
- 0 secrets found → +20 points
- 1-3 secrets → +10 points
- 4+ secrets → 0 points
- Private key committed → -10 points
---
### Phase 3: Prompt Injection Surface
Analyze markdown and config files for injection vectors:
```bash
# Zero-width characters (invisible instructions)
grep -rPn '[\x{200B}-\x{200D}\x{FEFF}]' --include="*.md" --include="*.yaml" --include="*.json" . 2>/dev/null
# Hidden HTML comments with instructions
grep -rn '<!--' --include="*.md" . 2>/dev/null | grep -i 'ignore\|system\|admin\|instruction\|override\|forget'
# Base64 in comments (potential hidden payloads)
grep -rn -E '[#;].*[A-Za-z0-9+/]{20,}={0,2}' --include="*.py" --include="*.js" --include="*.ts" --include="*.md" \
--exclude-dir={node_modules,vendor,.git} . 2>/dev/null | head -10
# ANSI escape sequences
grep -rPn '\x1b\[|\x1b\]|\x1b\(' --exclude-dir={node_modules,vendor,.git} . 2>/dev/null | head -10
# Null bytes
grep -rPn '\x00' --exclude-dir={node_modules,vendor,.git,dist} . 2>/dev/null | head -5
# Nested command execution in markdown/config
grep -rn -E '\$\([^)]+\)|`[^`]+`' --include="*.md" --include="*.yaml" --include="*.json" \
--exclude-dir={node_modules,vendor,.git} . 2>/dev/null | head -10
```
**Scoring:**
- 0 injection vectors → +15 points
- 1-2 vectors (likely false positives) → +10 points
- 3+ vectors → +5 points
- Confirmed injection in CLAUDE.md → 0 points
---
### Phase 4: Dependency Audit
Run the appropriate package audit for the project:
```bash
# Node.js
[ -f "package-lock.json" ] && npm audit --json 2>/dev/null | jq '{total: .metadata.vulnerabilities.total, critical: .metadata.vulnerabilities.critical, high: .metadata.vulnerabilities.high}' 2>/dev/null
# Python
[ -f "requirements.txt" ] && pip-audit -r requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && pip-audit 2>/dev/null
# Rust
[ -f "Cargo.toml" ] && cargo audit 2>/dev/null
# Go
[ -f "go.mod" ] && govulncheck ./... 2>/dev/null
```
If no package manager detected, note it and skip (no penalty).
**Scoring:**
- 0 vulnerabilities → +20 points
- 0 critical + 0 high → +15 points
- 1-3 high → +10 points
- Any critical → +5 points
- 10+ high or 3+ critical → 0 points
---
### Phase 5: Hook Security Assessment
Verify security hooks from `guide/security-hardening.md` are properly installed:
```bash
# Check for recommended security hooks
echo "=== Checking security hooks ==="
# PreToolUse hooks (should block dangerous patterns)
ls .claude/hooks/PreToolUse* 2>/dev/null || echo "⚠️ No PreToolUse hooks found"
# PostToolUse hooks (should monitor output)
ls .claude/hooks/PostToolUse* 2>/dev/null || echo "⚠️ No PostToolUse hooks found"
# Check if prompt injection detector exists
find . -path "*/hooks/*injection*" -o -path "*/hooks/*security*" -o -path "*/hooks/*scanner*" 2>/dev/null
# Check settings for hook configuration
grep -c "hooks" .claude/settings.json 2>/dev/null || echo "No hooks in settings.json"
```
**Scoring:**
- PreToolUse security hooks installed → +10 points
- PostToolUse output scanner installed → +5 points
- Prompt injection detector hook → +5 points
- No hooks at all → 0 points
---
### Phase 6: Posture Score & Report
Calculate total score and generate report.
**Scoring Breakdown:**
| Category | Max Points | Source |
|----------|-----------|--------|
| Config Security (Phase 1) | 30 | /security-check results |
| Secrets Scan (Phase 2) | 20 | Secrets found in project |
| Injection Surface (Phase 3) | 15 | Injection vectors found |
| Dependencies (Phase 4) | 20 | Vulnerability audit |
| Hook Security (Phase 5) | 15 | Security hooks installed |
| **Total** | **100** | |
**Phase 1 scoring detail:**
- 0 CRITICAL findings → +15 points
- 0 HIGH findings → +10 points
- 0 MEDIUM findings → +5 points
- Any CRITICAL → 0 for that sub-score
**Grade Scale:**
| Score | Grade | Meaning |
|-------|-------|---------|
| 90-100 | A | Excellent — production-ready security posture |
| 75-89 | B | Good — minor improvements recommended |
| 60-74 | C | Acceptable — address HIGH issues before production |
| 40-59 | D | Poor — significant security gaps |
| 0-39 | F | Critical — do not deploy, address CRITICAL issues immediately |
## Output Format
```
## 🛡️ Security Audit Report
**Date**: [timestamp]
**Project**: [directory name]
**Scope**: Full project + Claude Code configuration
### Security Posture Score: [XX]/100 (Grade [X])
[1-sentence assessment]
### Phase Results
| Phase | Score | Max | Key Finding |
|-------|-------|-----|-------------|
| 1. Config Security | XX | 30 | [summary] |
| 2. Secrets Scan | XX | 20 | [summary] |
| 3. Injection Surface | XX | 15 | [summary] |
| 4. Dependencies | XX | 20 | [summary] |
| 5. Hook Security | XX | 15 | [summary] |
| **Total** | **XX** | **100** | |
### 🔴 Critical Findings
[Each finding with location, description, and exact fix]
### 🟠 High Findings
[Each finding with location, description, and fix]
### 🟡 Medium Findings
[Each finding with location, description, and fix]
### 🔧 Remediation Plan (Priority Order)
| # | Action | Severity | Effort | Command/Steps |
|---|--------|----------|--------|---------------|
| 1 | [action] | CRITICAL | [time] | [how] |
| 2 | [action] | HIGH | [time] | [how] |
| ... | | | | |
### 📊 Benchmark
Your score vs security-hardening.md recommendations:
- [X] items from the guide are implemented
- [X] items are missing
- Top 3 missing items to implement next: [...]
### 📚 References
- Security hardening guide: guide/security-hardening.md
- Threat database: examples/commands/resources/threat-db.yaml
- Quick check: `/security-check`
- MCP scan tool: `npx mcp-scan` (Snyk)
```
$ARGUMENTS

172
examples/commands/security-check.md Normal file
View file

@ -0,0 +1,172 @@
# Security Check
Quick configuration security check against known threats database. Verifies your Claude Code setup for known malicious skills, vulnerable MCPs, dangerous patterns, and exposed secrets.
**Time**: ~30 seconds | **Scope**: Claude Code configuration only
## Instructions
You are a security analyst. Check the user's Claude Code configuration against the threat intelligence database bundled at `examples/commands/resources/threat-db.yaml`. Produce a concise, actionable report.
### Phase 1: Load Threat Database
Read `examples/commands/resources/threat-db.yaml` from this repository to load:
- Known malicious authors and skills
- CVE database for MCP servers
- Suspicious patterns for hooks, agents, and config
### Phase 2: MCP Server Audit
Read the user's MCP configuration:
```bash
# Global MCP config
cat ~/.claude/mcp.json 2>/dev/null
# Project MCP config
cat .claude/mcp.json 2>/dev/null
```
**Check against threat-db.yaml:**
- [ ] Any MCP server matching a CVE entry? → CRITICAL
- [ ] Version pinning: are all MCP servers pinned to exact versions (not `@latest`)? → HIGH if unpinned
- [ ] Any `--dangerous-*` flags in MCP args? → CRITICAL
- [ ] Any MCP servers not on the Safe List (see `guide/security-hardening.md` §1.1)? → MEDIUM (flag for manual review)
### Phase 3: Skills & Agents Audit
```bash
# List installed skills
ls -la .claude/skills/ 2>/dev/null
ls -la ~/.claude/skills/ 2>/dev/null
# List agents
ls -la .claude/agents/ 2>/dev/null
ls -la ~/.claude/agents/ 2>/dev/null
# Check agent allowed-tools
grep -r "allowed-tools" .claude/agents/ 2>/dev/null
grep -r "allowed-tools" ~/.claude/agents/ 2>/dev/null
```
**Check against threat-db.yaml:**
- [ ] Any skill/agent name matching `malicious_skills` entries? → CRITICAL
- [ ] Any skill/agent author matching `malicious_authors` entries? → CRITICAL
- [ ] Any agent with `allowed-tools: ["Bash"]` only? → HIGH
- [ ] Any agent with overly broad tool access + vague description? → MEDIUM
### Phase 4: Hook Security
```bash
# List all hooks
find .claude/hooks/ -type f 2>/dev/null
find ~/.claude/hooks/ -type f 2>/dev/null
# Scan hooks for suspicious patterns
grep -rn "curl\|wget\|nc \|ncat\|netcat\|base64\|eval\|exec\|/dev/tcp\|/dev/udp" .claude/hooks/ 2>/dev/null
grep -rn "curl\|wget\|nc \|ncat\|netcat\|base64\|eval\|exec\|/dev/tcp\|/dev/udp" ~/.claude/hooks/ 2>/dev/null
# Check for credential access in hooks
grep -rn "ssh\|id_rsa\|id_ed25519\|\.env\|credentials\|secret\|password\|token\|api.key" .claude/hooks/ 2>/dev/null
grep -rn "ssh\|id_rsa\|id_ed25519\|\.env\|credentials\|secret\|password\|token\|api.key" ~/.claude/hooks/ 2>/dev/null
```
**Check against threat-db.yaml `suspicious_patterns.hooks`:**
- [ ] Network calls (`curl`, `wget`) → HIGH
- [ ] Reverse shell indicators (`nc`, `/dev/tcp`) → CRITICAL
- [ ] Credential access (`ssh`, `.env`, `password`) → CRITICAL
- [ ] Base64 encoding → MEDIUM (review context)
### Phase 5: Memory Poisoning Check
```bash
# Check for suspicious instructions in memory/config files
grep -in "ignore\|forget\|override\|disregard\|you are now\|new role\|system prompt" \
CLAUDE.md .claude/CLAUDE.md SOUL.md .claude/SOUL.md MEMORY.md .claude/MEMORY.md \
~/.claude/CLAUDE.md ~/.claude/MEMORY.md 2>/dev/null
```
- [ ] Prompt injection patterns in CLAUDE.md / SOUL.md / MEMORY.md? → HIGH
- [ ] Instructions to disable security, skip reviews, or grant broad permissions? → CRITICAL
### Phase 6: Permissions & Settings
```bash
# Check settings
cat .claude/settings.json 2>/dev/null
cat ~/.claude/settings.json 2>/dev/null
```
- [ ] `permissions.deny` exists and covers `.env*`, `*.pem`, `*.key`, secrets? → MEDIUM if missing
- [ ] No wildcard `permissions.allow` for Bash or Write? → HIGH if present
- [ ] No `dangerouslySkipPermissions` or similar flags? → CRITICAL if present
### Phase 7: Exposed Secrets in Config
```bash
# Check for secrets in .claude/ directory
grep -rn "sk-[a-zA-Z0-9]\{20,\}\|sk-ant-[a-zA-Z0-9]\{20,\}\|ghp_[a-zA-Z0-9]\{36\}\|AKIA[A-Z0-9]\{16\}" \
.claude/ ~/.claude/ 2>/dev/null
# Check for private keys
grep -rn "BEGIN.*PRIVATE KEY" .claude/ ~/.claude/ 2>/dev/null
```
- [ ] API keys or tokens in config files? → CRITICAL
- [ ] Private keys in config? → CRITICAL
## Output Format
```
## 🛡️ Security Check Report
**Date**: [timestamp]
**Scope**: Claude Code configuration
### Results Summary
| Severity | Count | Status |
|----------|-------|--------|
| 🔴 CRITICAL | X | [PASS/FAIL] |
| 🟠 HIGH | X | [PASS/FAIL] |
| 🟡 MEDIUM | X | [PASS/FAIL] |
| 🟢 LOW | X | [PASS/FAIL] |
### 🔴 Critical Issues
[List each critical finding with location and fix]
### 🟠 High Issues
[List each high finding with location and fix]
### 🟡 Medium Issues
[List each medium finding with location and fix]
### ✅ Passed Checks
[List what passed — important for confidence]
### 🔧 Recommended Actions (Priority Order)
1. [Most urgent fix with exact command]
2. [Second priority]
3. [...]
### 📚 References
- Full security guide: guide/security-hardening.md
- Threat database: examples/commands/resources/threat-db.yaml
- MCP scan: `npx mcp-scan` (Snyk)
```
If ALL checks pass, output:
```
## 🛡️ Security Check Report — ALL CLEAR ✅
**Date**: [timestamp]
No known threats detected in your Claude Code configuration.
**Recommendations for continued security:**
- Re-run `/security-check` after installing new skills or MCP servers
- Run `/security-audit` for a comprehensive project + config audit
- Keep Claude Code updated (current security fixes in v2.1.34+)
```
$ARGUMENTS

164
examples/commands/update-threat-db.md Normal file
View file

@ -0,0 +1,164 @@
# Update Threat Database
Research and update the AI agent security threat intelligence database with the latest threats, CVEs, malicious skills, and campaigns.
**Time**: 3-8 minutes | **Scope**: `examples/commands/resources/threat-db.yaml`
> Requires Perplexity MCP (or manual web search). Run monthly or after major security advisories.
## Instructions
You are a threat intelligence analyst specializing in AI coding agent security. Research the latest threats and update the threat database.
---
### Phase 1: Current State Assessment
Read the current threat database:
```
Read examples/commands/resources/threat-db.yaml
```
Note:
- Current `version` and `updated` date
- Number of malicious authors, skills, CVEs, campaigns
- Most recent entries to avoid duplicates
---
### Phase 2: Research New Threats
Run **4 targeted Perplexity searches** (parallel when possible):
**Search 1: New malicious skills & campaigns**
```
Query: "malicious AI agent skills ClawHub OpenClaw skills.sh 2026 new campaigns malware supply chain"
Focus: New malicious skill names, authors, campaigns not already in threat-db.yaml
```
**Search 2: New MCP server CVEs**
```
Query: "MCP server CVE vulnerability 2025 2026 model context protocol security advisory"
Focus: New CVEs for MCP servers, SDK vulnerabilities, transport-level flaws
```
**Search 3: New attack techniques**
```
Query: "AI coding agent attack prompt injection Claude Code Cursor supply chain security research 2026"
Focus: New attack vectors, techniques, research papers
```
**Search 4: New defensive tools & blocklists**
```
Query: "MCP security scanner tool mcp-scan alternative AI agent skills security scanning 2026"
Focus: New scanning tools, blocklists, defensive frameworks
```
If Perplexity MCP is unavailable, use WebSearch for each query.
---
### Phase 3: Analyze & Deduplicate
For each finding from Phase 2:
1. **Check if already in threat-db.yaml** — skip duplicates
2. **Verify source credibility** — prefer: CVE databases, security vendor blogs, peer-reviewed research
3. **Categorize** — which section does it belong to?
- `malicious_authors` — new confirmed malicious publishers
- `malicious_skills` — new confirmed malicious skill/package names
- `malicious_skill_patterns` — new prefix patterns for wildcard matching
- `cve_database` — new CVEs with component, severity, fixed_in
- `minimum_safe_versions` — update if new patches available
- `iocs` — new C2 IPs, exfil URLs, malware hashes
- `campaigns` — new coordinated campaigns
- `attack_techniques` — new documented attack vectors
- `scanning_tools` — new tools or major updates
- `defensive_resources` — new frameworks, blocklists
4. **Assess risk level**:
- `critical` — confirmed malicious, active exploitation
- `high` — confirmed vulnerable, exploit available
- `medium` — theoretical risk, no known exploitation
- `low` — informational
---
### Phase 4: Update threat-db.yaml
Apply changes following these rules:
1. **Bump version** — increment minor (e.g. 2.0.0 → 2.1.0) for new entries, major for schema changes
2. **Update `updated` date** — set to today
3. **Add new sources** — add any new research sources to the `sources` list
4. **Maintain YAML validity** — use single quotes for patterns containing backslashes
5. **Preserve existing entries** — never remove entries unless confirmed false positive
6. **Follow existing format** — match the structure of existing entries exactly
**Important**: After editing, validate YAML:
```bash
python3 -c "import yaml; yaml.safe_load(open('examples/commands/resources/threat-db.yaml')); print('YAML valid')"
```
---
### Phase 5: Update Dependent Files (if needed)
Check if new CVEs should also be added to the security hardening guide:
```bash
# Count current CVEs in threat-db vs security-hardening
grep -c "id:" examples/commands/resources/threat-db.yaml
grep -c "CVE-" guide/security-hardening.md
```
If major new CVEs found (severity critical/high):
- Consider adding to `guide/security-hardening.md` CVE table
- Update `minimum_safe_versions` if new patches released
---
### Phase 6: Summary Report
## Output Format
```
## Threat Database Update Report
**Date**: [timestamp]
**Previous version**: [old version]
**New version**: [new version]
### Changes Summary
| Category | Added | Updated | Total |
|----------|-------|---------|-------|
| Malicious authors | +X | ~X | XX |
| Malicious skills | +X | ~X | XX |
| CVEs | +X | ~X | XX |
| Campaigns | +X | ~X | XX |
| IOCs | +X | ~X | XX |
| Attack techniques | +X | ~X | XX |
| Scanning tools | +X | ~X | XX |
### New Entries
[List each new entry with source and risk level]
### Notable Findings
[Highlight anything particularly important or urgent]
### No Changes Needed
[If nothing new found, explain what was searched and confirmed up-to-date]
### Next Steps
- [ ] Run `/security-check` to test against updated database
- [ ] Update `guide/security-hardening.md` if new critical CVEs
- [ ] Commit: `docs(security): update threat-db vX.Y.Z — [summary]`
```
$ARGUMENTS

13
guide/cheatsheet.md
View file

@ -6,7 +6,7 @@
**Written with**: Claude (Anthropic)
**Version**: 3.24.0 | **Last Updated**: February 2026
**Version**: 3.26.0 | **Last Updated**: February 2026
---
@ -26,6 +26,8 @@
| `/teleport` | Teleport session from web |
| `/tasks` | Monitor background tasks |
| `/remote-env` | Configure cloud environment |
| `/fast` | Toggle fast mode (2.5x speed, 6x cost) |
| `/debug` | Systematic troubleshooting |
| `/exit` | Quit (or Ctrl+D) |
---
@ -42,6 +44,7 @@
| `Tab` | Autocomplete |
| `Shift+Enter` | New line |
| `Ctrl+B` | Background tasks |
| `Alt+T` | Toggle thinking |
| `Ctrl+D` | Exit |
---
@ -67,7 +70,8 @@
|---------|-------|--------------|
| **Tasks API** | v2.1.16 | Persistent task lists with dependencies |
| **Background Agents** | v2.0.60 | Sub-agents work while you code |
| **TeammateTool** | Experimental | Multi-agent coordination (unstable) |
| **Agent Teams** | v2.1.32 | Multi-agent coordination (TeamCreate/SendMessage) |
| **Auto-Memories** | v2.1.32 | Automatic cross-session context capture |
| **Session Forking** | v2.1.19 | Rewind + create parallel timeline |
| **LSP Tool** | v2.0.74 | Code intelligence (go-to-def, refs) |
@ -202,12 +206,13 @@ Model: Sonnet | Ctx: 89.5k | Cost: $2.11 | Ctx(u): 56.0%
| **Plan Mode** | `Shift+Tab × 2` or `/plan` | Explore without modifying |
| **OpusPlan** | `/model opusplan` | Opus for planning, Sonnet for execution |
> **⚠️ Opus 4.5+ Change**: Thinking mode is now **ON by default at max budget**. Keywords like "ultrathink" are cosmetic only.
> **Opus 4.6**: Thinking is **ON by default at max budget**. Keywords like "think hard" or "ultrathink" are cosmetic only — they don't control depth.
| Control | Action | Persistence |
|---------|--------|-------------|
| **Alt+T** | Toggle thinking on/off | Session |
| **/config** | Enable/disable globally | Permanent |
| **`effort` param** | API only: `low\|medium\|high\|max` | Per-request |
**Cost tip**: For simple tasks, Alt+T to disable thinking → faster & cheaper.
@ -520,4 +525,4 @@ where.exe claude; claude doctor; claude mcp list
**Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude
*Last updated: February 2026 | Version 3.24.0*
*Last updated: February 2026 | Version 3.26.0*

6
guide/ultimate-guide.md
View file

@ -10,7 +10,7 @@
**Last updated**: January 2026
**Version**: 3.24.0
**Version**: 3.26.0
---
@ -4283,7 +4283,7 @@ The `.claude/` folder is your project's Claude Code directory for memory, settin
| Personal preferences | `CLAUDE.md` | ❌ Gitignore |
| Personal permissions | `settings.local.json` | ❌ Gitignore |
### 3.24.0 Version Control & Backup
### 3.26.0 Version Control & Backup
**Problem**: Without version control, losing your Claude Code configuration means hours of manual reconfiguration across agents, skills, hooks, and MCP servers.
@ -19354,4 +19354,4 @@ We'll evaluate and add it to this section if it meets quality criteria.
**Contributions**: Issues and PRs welcome.
**Last updated**: January 2026 | **Version**: 3.24.0
**Last updated**: January 2026 | **Version**: 3.26.0

26
machine-readable/reference.yaml
View file

@ -3,7 +3,7 @@
# Source: guide/ultimate-guide.md
# Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
version: "3.24.0"
version: "3.26.0"
updated: "2026-02-09"
# ════════════════════════════════════════════════════════════════
@ -173,7 +173,7 @@ deep_dive:
third_party_toad: "https://github.com/batrachianai/toad"
third_party_conductor: "https://docs.conductor.build"
# Configuration Management & Backup (Added 2026-02-02)
config_management_guide: "guide/ultimate-guide.md:4085" # Section 3.24.0
config_management_guide: "guide/ultimate-guide.md:4085" # Section 3.26.0
config_hierarchy: "guide/ultimate-guide.md:4095" # Global → Project → Local precedence
config_git_strategy_project: "guide/ultimate-guide.md:4110" # What to commit in .claude/
config_git_strategy_global: "guide/ultimate-guide.md:4133" # Version control ~/.claude/
@ -753,6 +753,16 @@ deep_dive:
architecture: 819 # Architecture internals
production_safety: "guide/production-safety.md" # Production safety rules
security_hardening: "guide/security-hardening.md" # Security best practices
security_cve_summary: "guide/security-hardening.md:51" # CVE table (7 CVEs, 2025-2026)
security_supply_chain_stats: "guide/security-hardening.md:127" # Snyk ToxicSkills: 36.82% of 3,984 skills
security_mcp_scan_tool: "guide/security-hardening.md:96" # mcp-scan in Safe List
security_malicious_extensions: "guide/security-hardening.md:242" # .claude/ attack surface (§1.5)
security_claude_folder_audit: "guide/security-hardening.md:270" # 5-minute .claude/ audit checklist
security_toxicskills_evaluation: "docs/resource-evaluations/snyk-toxicskills-evaluation.md"
security_check_command: "examples/commands/security-check.md" # Quick config check vs known threats
security_audit_command: "examples/commands/security-audit.md" # Full 6-phase security audit (score /100)
security_threat_db: "examples/commands/resources/threat-db.yaml" # Threat intelligence database (authors, skills, CVEs, patterns)
security_update_threat_db: "examples/commands/update-threat-db.md" # /update-threat-db — research & update threat database
agent_validation_checklist: 3850 # Agent validation section in ultimate-guide.md
git_mcp_guide: "guide/mcp-servers-ecosystem.md:102" # Git MCP server documentation
@ -1169,7 +1179,7 @@ ecosystem:
- "Cross-links modified → Update all 4 repos"
history:
- date: "2026-01-20"
event: "Code Landing sync v3.24.0, 66 templates, cross-links"
event: "Code Landing sync v3.26.0, 66 templates, cross-links"
commit: "5b5ce62"
- date: "2026-01-20"
event: "Cowork Landing fix (paths, README, UI badges)"
@ -1181,7 +1191,7 @@ ecosystem:
onboarding_matrix_meta:
version: "2.0.0"
last_updated: "2026-02-05"
aligned_with_guide: "3.24.0"
aligned_with_guide: "3.26.0"
changelog:
- version: "2.0.0"
date: "2026-02-05"
@ -1209,7 +1219,7 @@ onboarding_matrix:
core: [rules, sandbox_native_guide, commands]
time_budget: "5 min"
topics_max: 3
note: "SECURITY FIRST - sandbox before commands (v3.24.0 critical fix)"
note: "SECURITY FIRST - sandbox before commands (v3.26.0 critical fix)"
beginner_15min:
core: [rules, sandbox_native_guide, workflow, essential_commands]
@ -1294,7 +1304,7 @@ onboarding_matrix:
- default: agent_validation_checklist
time_budget: "60 min"
topics_max: 6
note: "Dual-instance pattern for quality workflows (v3.24.0)"
note: "Dual-instance pattern for quality workflows (v3.26.0)"
learn_security:
intermediate_30min:
@ -1305,7 +1315,7 @@ onboarding_matrix:
- default: permission_modes
time_budget: "30 min"
topics_max: 4
note: "NEW goal (v3.24.0) - Security-focused learning path"
note: "NEW goal (v3.26.0) - Security-focused learning path"
power_60min:
core: [sandbox_native_guide, mcp_secrets_management, security_hardening]
@ -1330,7 +1340,7 @@ onboarding_matrix:
core: [rules, sandbox_native_guide, workflow, essential_commands, context_management, plan_mode]
time_budget: "60 min"
topics_max: 6
note: "Security foundation + core workflow (v3.24.0 sandbox added)"
note: "Security foundation + core workflow (v3.26.0 sandbox added)"
intermediate_120min:
core: [plan_mode, agents, skills, config_hierarchy, git_mcp_guide, hooks, mcp_servers]

474
tools/audit-cheatsheet-prompt.md Normal file
View file

@ -0,0 +1,474 @@
# Audit Your Landing Cheatsheet
> A self-contained prompt to evaluate if your project needs a cheatsheet and audit existing ones against the gold standard.
**Author**: [Florian BRUNIAUX](https://github.com/FlorianBruniaux) | Founding Engineer [@Methode Aristote](https://methode-aristote.fr)
**Reference**: [Claude Code Ultimate Guide Cheatsheet](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/cheatsheet.md) (gold standard)
---
## 1. What This Does
This prompt instructs Claude to perform a systematic cheatsheet audit in 4 phases:
1. **Discovery** — Explore the project source + landing to understand scope
2. **Evaluation** — Score whether the project needs a cheatsheet (objective criteria)
3. **Audit** — If a cheatsheet exists, grade it against 13 quality checkpoints
4. **Recommendation** — Go/no-go decision with actionable plan
**Covers 3 scenarios**:
- No cheatsheet exists → need assessment + go/no-go
- Partial cheatsheet (HTML only, or MD only) → gap analysis
- Complete cheatsheet (MD + PDF + HTML) → quality audit
**Time**: ~3-5 minutes depending on project size
---
## 2. Who This Is For
| Audience | What You'll Get |
|----------|-----------------|
| **Project maintainer** | Clear go/no-go on creating a cheatsheet |
| **Landing page builder** | Quality checklist for cheatsheet pages |
| **Documentation lead** | Gap analysis and prioritized improvements |
**Prerequisites**:
- Claude Code installed and working
- Access to the project source code (repo with docs/README)
- Access to the landing site (if exists)
- Bash shell (native on macOS/Linux, WSL on Windows)
---
## 3. How to Use It
### Step 1: Copy the Prompt
Copy everything inside the code block in [Section 4](#4-the-prompt) below.
### Step 2: Navigate to your project
```bash
cd your-project-directory
claude
```
### Step 3: Paste and Execute
Paste the prompt and press Enter. Claude will begin the 4-phase audit.
### Step 4: Review Results
Claude will present findings per phase and a final summary with actionable recommendations.
---
## 4. The Prompt
````markdown
# Cheatsheet Audit
## Context
You are a documentation quality auditor. Your job is to evaluate whether this project needs a cheatsheet, and if one exists, audit its quality against a proven gold standard.
**Gold standard reference**: The Claude Code Ultimate Guide cheatsheet — a 527-line Markdown file that condenses a 11K-line guide into 1 printable page, with matching PDF and HTML landing page versions.
## Instructions
Run all 4 phases sequentially. Report findings after each phase before proceeding.
---
### Phase 1: Discovery
**Goal**: Understand the project scope, audience, and existing documentation assets.
#### 1.1 Project Source Scan
```bash
bash -c '
echo "=== PROJECT IDENTITY ==="
[ -f "package.json" ] && echo "Name: $(grep -m1 \"name\" package.json | cut -d\" -f4)"
[ -f "Cargo.toml" ] && echo "Name: $(grep -m1 "name" Cargo.toml | cut -d\" -f2)"
[ -f "VERSION" ] && echo "Version: $(cat VERSION)" || echo "Version: not found"
echo ""
echo "=== DOCUMENTATION ==="
for f in README.md CLAUDE.md CHANGELOG.md; do
[ -f "$f" ] && echo "✅ $f ($(wc -l < "$f") lines)" || echo "❌ $f"
done
echo ""
echo "=== GUIDE/DOCS DIRECTORY ==="
for d in guide docs doc documentation; do
[ -d "$d" ] && echo "✅ $d/ ($(find "$d" -name "*.md" | wc -l | tr -d " ") md files)" || echo "— $d/ not found"
done
echo ""
echo "=== CHEATSHEET FILES ==="
find . -maxdepth 3 -iname "*cheatsheet*" -o -iname "*cheat-sheet*" -o -iname "*quick-ref*" -o -iname "*quickref*" 2>/dev/null | head -20
echo ""
echo "=== EXAMPLES/TEMPLATES ==="
for d in examples templates; do
[ -d "$d" ] && echo "✅ $d/ ($(find "$d" -type f | wc -l | tr -d " ") files)"
done
'
```
#### 1.2 Landing Site Scan
If the project has an associated landing site, scan it:
```bash
bash -c '
echo "=== LANDING SEARCH ==="
# Check common landing locations relative to project
PROJECT_NAME=$(basename "$PWD")
for suffix in "-landing" "-site" "-web" "-docs"; do
LANDING="../${PROJECT_NAME}${suffix}"
[ -d "$LANDING" ] && echo "✅ Found: $LANDING" && ls "$LANDING"/*.html 2>/dev/null | head -5
done
# Check for cheatsheet in landing
echo ""
echo "=== LANDING CHEATSHEET ==="
find .. -maxdepth 3 -path "*landing*" -name "*cheatsheet*" 2>/dev/null | head -10
'
```
#### 1.3 Content Complexity Assessment
```bash
bash -c '
echo "=== COMPLEXITY INDICATORS ==="
# Commands/CLI
echo "--- Commands ---"
grep -rh "^\`[a-z]" README.md guide/*.md docs/*.md 2>/dev/null | sort -u | wc -l | xargs echo "CLI commands found:"
grep -rhi "slash command\|/command\|custom command" README.md guide/*.md docs/*.md 2>/dev/null | wc -l | xargs echo "Slash command refs:"
# Keyboard shortcuts
echo "--- Shortcuts ---"
grep -rhi "ctrl\|alt\|shift\|cmd\|⌘\|shortcut" README.md guide/*.md docs/*.md 2>/dev/null | wc -l | xargs echo "Shortcut references:"
# Config files
echo "--- Configuration ---"
grep -rhi "config\|settings\|\.env\|\.json\|\.yaml\|\.toml" README.md guide/*.md docs/*.md 2>/dev/null | wc -l | xargs echo "Config references:"
# API surface
echo "--- API/Features ---"
grep -rhi "endpoint\|api\|route\|feature\|flag" README.md guide/*.md docs/*.md 2>/dev/null | wc -l | xargs echo "API/feature refs:"
# Total doc volume
echo "--- Volume ---"
find . -name "*.md" -not -path "./.git/*" -not -path "*/node_modules/*" | xargs wc -l 2>/dev/null | tail -1 | xargs echo "Total MD lines:"
'
```
**After running Phase 1, report:**
- Project name, version, type (CLI tool / library / app / framework)
- Target audience (developers / non-devs / mixed)
- Documentation volume (lines, files)
- Existing cheatsheet assets found (MD, PDF, HTML, none)
- Complexity indicators summary
---
### Phase 2: Need Evaluation
**Goal**: Determine objectively whether this project warrants a cheatsheet.
Score each criterion 0-2 (0 = no, 1 = partial, 2 = yes):
| # | Criterion | Score Guide | Score |
|---|-----------|-------------|-------|
| 1 | **Command surface** | 2 = 10+ commands, 1 = 5-9, 0 = <5 | |
| 2 | **Keyboard shortcuts** | 2 = 5+ shortcuts, 1 = 2-4, 0 = 0-1 | |
| 3 | **Configuration complexity** | 2 = multiple config files/levels, 1 = single config, 0 = minimal | |
| 4 | **Multi-step workflows** | 2 = documented workflows, 1 = implicit workflows, 0 = none | |
| 5 | **Decision points** | 2 = multiple modes/options to choose from, 1 = some, 0 = linear | |
| 6 | **Reference frequency** | 2 = users look up daily, 1 = weekly, 0 = once then done | |
| 7 | **Documentation volume** | 2 = >2000 lines docs, 1 = 500-2000, 0 = <500 | |
| 8 | **Audience breadth** | 2 = beginners + advanced, 1 = single level, 0 = niche experts | |
**Scoring**:
- **12-16**: Strong need — cheatsheet is high value
- **8-11**: Moderate need — cheatsheet adds value
- **4-7**: Low need — consider a "Quick Start" section instead
- **0-3**: No need — a good README suffices
**Report**: Table with scores, total, and verdict (Strong/Moderate/Low/None).
---
### Phase 3: Quality Audit (if cheatsheet exists)
**Goal**: Grade the existing cheatsheet against the gold standard's 13 quality checkpoints.
If no cheatsheet was found in Phase 1, skip to Phase 4.
For each checkpoint, grade: Pass / Partial / Fail / N/A.
#### A. Version & Date Sync
Check that version numbers match the project's source of truth:
- Header/footer version matches `VERSION` file or `package.json`
- "Last updated" date is current (within 1 month of latest release)
- HTML: schema.org `dateModified` matches
- HTML: Open Graph metadata matches
#### B. Factual Accuracy
Spot-check 3-5 factual claims against the source documentation:
- Are described features still current? (no deprecated items listed as active)
- Are version requirements accurate?
- Are any "keywords" or "magic strings" documented that don't actually work?
#### C. Commands Completeness
Compare commands listed vs. actual available commands:
- Count commands in cheatsheet vs. source docs
- Flag any missing essential commands
- Flag any deprecated commands still listed
#### D. Keyboard Shortcuts Completeness
Compare shortcuts listed vs. actual shortcuts:
- Cross-reference with source documentation
- Check platform-specific variants (macOS vs Windows/Linux)
- Verify no deprecated shortcuts
#### E. Feature Tables Accuracy
For each feature table in the cheatsheet:
- Verify column values against source docs
- Check for outdated entries
- Verify links still work
#### F. Decision Trees / Quick Reference
If the cheatsheet includes decision trees or flowcharts:
- Verify all paths lead to valid recommendations
- Check that referenced features/commands exist
- Ensure no dead-end paths
#### G. Folder Structure / Config
If folder structure or config layout is documented:
- Compare against actual project structure
- Verify all listed files/dirs exist
- Flag any missing important paths
#### H. Installation Correctness
If installation instructions are included:
- Verify package name is correct
- Check version constraints
- Test install command mentally against current ecosystem
#### I. Section Coverage (cross-format)
Compare coverage across available formats:
| Section | MD | PDF | HTML |
|---------|:--:|:---:|:----:|
| Commands | ? | ? | ? |
| Shortcuts | ? | ? | ? |
| Config | ? | ? | ? |
| Workflows | ? | ? | ? |
| Troubleshooting | ? | ? | ? |
Flag sections present in one format but missing in another.
#### J. Cost / Pricing Accuracy
If pricing or cost information is included:
- Verify against current official pricing
- Check that model names are current
- Verify any "free tier" claims
#### K. CLI Flags Completeness
If CLI flags are documented:
- Compare against `--help` output or source docs
- Flag missing commonly-used flags
- Flag deprecated flags still listed
#### L. SEO / Schema.org (HTML landing only)
For HTML cheatsheet pages:
- Verify `<script type="application/ld+json">` schema exists
- Check `dateModified` is current
- Verify canonical URL
- Check Open Graph tags (title, description, image)
- Check meta description accuracy
- Verify print CSS exists (cheatsheets get printed)
#### M. PDF Rendering Quality
For PDF cheatsheets:
- Tables render correctly (no broken columns)
- Special characters display properly (checkmarks, arrows, emojis)
- Code blocks are readable (monospace font, syntax highlighting)
- Fits intended page count (1 page for quick ref, 2-4 for detailed)
- Print-friendly (no dark backgrounds eating ink)
**Report**: Table with all 13 checkpoints graded, plus notes on critical failures.
---
### Phase 4: Recommendation
**Goal**: Deliver a clear, actionable verdict.
#### If no cheatsheet exists (Phase 2 result)
Based on the need score:
**Score 12-16 (Strong need)**:
```
VERDICT: GO — Create cheatsheet
Priority: HIGH
Estimated effort: [S/M/L based on complexity]
Recommended formats: [MD only / MD+PDF / MD+PDF+HTML]
Suggested sections (based on Phase 1 findings):
1. [section] — [why]
2. [section] — [why]
...
```
**Score 8-11 (Moderate need)**:
```
VERDICT: CONDITIONAL GO — Create if [condition]
Priority: MEDIUM
Condition: [e.g., "if landing site targets beginners"]
Lighter alternative: [e.g., "expanded Quick Start in README"]
```
**Score 4-7 (Low need)**:
```
VERDICT: NO-GO — Quick Start section recommended instead
Reason: [specific reasons]
Alternative: Add a "Quick Start" or "TL;DR" section to README
```
**Score 0-3 (No need)**:
```
VERDICT: NO-GO — README is sufficient
Reason: [specific reasons]
```
#### If cheatsheet exists (Phase 3 result)
```
AUDIT SCORE: [X/13 passing]
Critical failures: [list]
Priority fixes:
1. [fix] — [impact]
2. [fix] — [impact]
...
Missing formats: [list needed: MD / PDF / HTML]
Estimated effort to reach gold standard: [S/M/L]
```
---
## Gold Standard Reference
The Claude Code cheatsheet serves as the benchmark. Here's what makes it the gold standard:
### Structure (527 lines, 17 sections)
```
1. Essential Commands (15 commands, table format)
2. Keyboard Shortcuts (9 shortcuts, table format)
3. File References (syntax + IDE shortcuts)
4. Hidden Features (versioned feature table)
5. Permission Modes (3-mode matrix)
6. Memory & Settings (2-level config with paths)
7. .claude/ Folder Structure (tree diagram)
8. Typical Workflow (numbered step-by-step)
9. Context Management (thresholds + symptoms + recovery)
10. Under the Hood (quick facts table)
11. Plan Mode & Thinking (controls + cost + model switching)
12. MCP Servers (7 servers, table format)
13. Creating Custom Components (agent/command/hook templates)
14. Anti-patterns (do/don't table)
15. Quick Prompting Formula (template + example)
16. CLI Flags Quick Reference (13 flags)
17. Golden Rules (7 rules, numbered)
```
### Quality Characteristics
- **Density**: 527 lines condenses 11,000+ lines (20:1 ratio)
- **Scannability**: Every section uses tables, code blocks, or numbered lists
- **Actionability**: Every entry answers "what do I type?" not "what is this?"
- **Cross-format**: MD (source) + PDF (print) + HTML (landing, with dark theme + print CSS)
- **Version-synced**: Header, footer, schema.org all match VERSION file
- **Platform-aware**: macOS + Windows paths where relevant
- **Anti-pattern section**: Shows what NOT to do (high value for beginners)
- **Decision tree**: "What should I do?" quick routing
### HTML Landing Patterns
When evaluating HTML cheatsheet pages, the gold standard includes:
- Dark theme with syntax highlighting
- Print-optimized CSS (`@media print`)
- Schema.org `TechArticle` markup with `dateModified`
- Open Graph tags for social sharing
- Responsive design (mobile-friendly tables)
- Navigation integration (linked from main landing)
- Download CTA for PDF version
````
---
## 5. Example Output
Here's what the audit looks like when run against a real project:
### Example: Project with no cheatsheet
```
=== PHASE 1: DISCOVERY ===
Project: cc-copilot-bridge v1.5.3 (CLI tool)
Audience: Developers (VS Code users)
Docs: README.md (450 lines), 3 guide files (1200 lines total)
Cheatsheet: None found
Complexity: 12 commands, 6 config options, 3 workflows
=== PHASE 2: NEED EVALUATION ===
| # | Criterion | Score |
|---|------------------------|-------|
| 1 | Command surface | 2 |
| 2 | Keyboard shortcuts | 1 |
| 3 | Config complexity | 1 |
| 4 | Multi-step workflows | 2 |
| 5 | Decision points | 1 |
| 6 | Reference frequency | 2 |
| 7 | Documentation volume | 1 |
| 8 | Audience breadth | 1 |
| | **TOTAL** | **11** |
VERDICT: CONDITIONAL GO
Priority: MEDIUM
Condition: If landing site is created for broader audience
Lighter alternative: "Quick Reference" section in README
=== PHASE 3: SKIPPED (no cheatsheet) ===
=== PHASE 4: RECOMMENDATION ===
If you decide to create a cheatsheet:
- Start with MD format (1-2 hours)
- Sections: Commands, Config, Workflows, Troubleshooting
- Skip PDF/HTML until landing site exists
```
---
**Version**: 1.0.0 | **Last Updated**: February 2026