feat: add new skills for context7-docs, cron-scheduling, excel-operations, hook-management, mcp-integration, notebook-edit, pdf-processing, and security-best-practices

2026-04-08 15:06:55 +07:00
parent 853d814a3f
commit 946baeba51
9 changed files with 1081 additions and 1 deletions
@@ -92,5 +92,5 @@
 # ==========================================
 # 7. Cron & Delivery Queue
 # ==========================================
 .openclaw/cron/*
 .openclaw/delivery-queue/*
 .openclaw/cron/*
@@ -0,0 +1,125 @@
 ---
 name: context7-docs
 description: Fetch up-to-date library documentation and code examples using Context7
 ---
 ## When to use
 Use when the user asks to:
 - Look up library APIs (React, Next.js, Supabase, etc.)
 - Get current code examples for a specific library version
 - Find documentation for configuration or setup steps
 - Resolve ambiguous API questions with authoritative sources
 - Avoid outdated training data or hallucinated APIs
 ## Prerequisites
 - `npx` must be available (Node.js)
 - Internet connection (Context7 fetches latest docs)
 - No API key needed for basic usage (public mode)
 ## Workflow
 ### 1. Find the library ID (if not known)
 If the user mentions a library name (e.g., "React", "Supabase"), first resolve to Context7 library ID:
 ```bash
 npx ctx7 library <library-name>
 ```
 Example:
 ```bash
 npx ctx7 library react
 ```
 Output:
 ```
 1. Title: React
   Context7-compatible library ID: /reactjs/react.dev
   ...
 ```
 Pick the best match (usually highest benchmark score or official source).
 ### 2. Retrieve documentation
 Use the library ID to fetch relevant docs:
 ```bash
 npx ctx7 docs <library-id> --query "<user question>"
 ```
 Example:
 ```bash
 npx ctx7 docs /reactjs/react.dev --query "how to use useEffect with empty dependency array"
 ```
 ### 3. Present results
 Context7 returns relevant code snippets and explanations. Structure the answer:
 - Brief summary of the solution
 - Code example(s) directly from docs
 - Link to full docs if needed
 ## Library ID Shortcuts
 Once you know the library ID, use it directly in prompts:
 User: "How do I set up Next.js middleware? use context7"
 You can parse "use context7" as a signal to call Context7 with:
 - library: inferred or ask user
 - query: the full question
 ## Common Libraries (pre-resolved)
 | Library | Context7 ID |
 |---------|-------------|
 | React | /reactjs/react.dev or /websites/react_dev |
 | Next.js | /vercel/next.js |
 | Supabase | /supabase/supabase |
 | Vue | /vuejs/core |
 | Angular | /angular/core |
 | Node.js | /nodejs/node |
 | Express | /expressjs/express |
 | FastAPI | /tiangolo/fastapi |
 | Django | /django/django |
 | PostgreSQL | /postgres/postgres |
 | MongoDB | /mongodb/docs |
 You can cache these mappings for faster lookup.
 ## Examples
 <Good>
 User: "Implement basic authentication with Supabase"
 Assistant:
 1. Resolve library: `npx ctx7 library supabase` → /supabase/supabase
 2. Fetch docs: `npx ctx7 docs /supabase/supabase --query "basic email/password authentication"`
 3. Return code example from Context7 output
 </Good>
 <Bad>
 Skipping library resolution and guessing API from memory (may be outdated).
 </Bad>
 ## Tips
 - Always verify the returned code matches the user's version if specified (Context7 auto-detects version from query)
 - If results are empty, try rephrasing the query or different library ID
 - For version-specific questions, include version in query: "Next.js 14 middleware"
 - Cache library IDs after first lookup to reduce API calls
 ## Error Handling
 - **Library not found**: Try alternative names or check spelling
 - **No docs returned**: Query might be too vague; break into smaller questions
 - **Network error**: Retry once, then fall back to general knowledge (with disclaimer)
 ## Verification
 - [ ] Library ID is correct (from `ctx7 library` output)
 - [ ] Query clearly describes the needed information
 - [ ] Returned code is complete and runnable
 - [ ] Version matches user's context if specified
 ## Advanced: MCP Mode (Future)
 If OpenClaw adds MCP client support, you can register Context7 MCP server:
 ```
 https://mcp.context7.com/mcp
 ```
 With header `CONTEXT7_API_KEY` if you have one. Then use `ctx7` tools directly without shell calls.
@@ -0,0 +1,177 @@
 ---
 name: cron-scheduling
 description: Schedule automated tasks with cron expressions or intervals using OpenClaw's cron system
 ---
 ## When to use
 Use when the user asks to:
 - Run periodic checks (every hour, daily, weekly)
 - Schedule one-time future tasks
 - Automate recurring reports or backups
 - Set up monitoring alerts
 - Create time-based triggers
 ## Cron Basics
 OpenClaw uses standard cron expressions:
 ```
 * * * * *
 │ │ │ │ │
 │ │ │ │ └── Day of week (0-7, 0= Sunday)
 │ │ │ └──── Month (1-12)
 │ │ └────── Day of month (1-31)
 │ └──────── Hour (0-23)
 └────────── Minute (0-59)
 ```
 **Examples**:
 - `0 * * * *` — every hour at minute 0
 - `30 3 * * *` — daily at 3:30 AM
 - `0 9 * * 1` — every Monday at 9:00 AM
 - `*/15 * * * *` — every 15 minutes
 ## Workflow
 ### 1. Create a scheduled job
 ```bash
 cron add \
  --name "daily-backup" \
  --schedule "0 2 * * *" \
  --task "clawteam task create backup 'Database backup' -o backup-agent"
 ```
 ### 2. List scheduled jobs
 ```bash
 cron list
 cron list --include-disabled true
 ```
 ### 3. Manage jobs
 ```bash
 # Disable (keep config)
 cron update --job-id <id> --enabled false
 # Enable
 cron update --job-id <id> --enabled true
 # Remove
 cron remove --job-id <id>
 ```
 ### 4. Run manually (for testing)
 ```bash
 cron run --job-id <id>
 ```
 ### 5. View job history
 ```bash
 cron runs --job-id <id> --limit 10
 ```
 ## Job Configuration Options
 | Flag | Description | Example |
 |------|-------------|---------|
 | `--name` | Human-readable name | "Health check" |
 | `--schedule` | Cron expression | "*/5 * * * *" |
 | `--task` | Command to execute | "oh -p 'Check system'" |
 | `--timezone` | IANA timezone | "Asia/Ho_Chi_Minh" |
 | `--enabled` | Start enabled/disabled | true/false |
 ## Advanced Scheduling
 ### Interval-based (every N minutes/hours)
 ```bash
 cron add \
  --name "ping-every-10m" \
  --schedule-kind every \
  --every-ms 600000 \
  --task "oh -p 'Ping service'"
 ```
 ### One-time future run
 ```bash
 cron add \
  --name "deploy-at-noon" \
  --schedule-kind at \
  --at "2026-04-09T12:00:00Z" \
  --task "oh -p 'Deploy v2'"
 ```
 ### Random jitter (avoid thundering herd)
 ```bash
 cron add \
  --schedule-kind cron \
  --expr "*/10 * * * *" \
  --stagger-ms 120000  # ±2 min random
 ```
 ## Task Payloads
 ### Simple command
 ```bash
 --task "oh -p 'Check logs'"
 ```
 ### With context
 ```bash
 --task "oh -p 'Check logs' --contextMessages 5"
 ```
 ### Agent turn (new conversation)
 ```bash
 --task '{"kind":"agentTurn","message":"Check system health"}'
 ```
 ### System event (inject into main session)
 ```bash
 --task '{"kind":"systemEvent","text":"/healthcheck"}'
 ```
 ## Best Practices
 - **Descriptive names**: "daily-backup" not "job1"
 - **Error alerts**: Configure cron failure alerts (`--failure-alert`)
 - **Logging**: Ensure tasks have `--verbose` or logging enabled
 - **Test manually**: `cron run` before relying on schedule
 - **Avoid overlap**: Ensure tasks finish before next run (use `--timeout`)
 ## Examples
 <Good>
 Daily health check at 2 AM:
 ```bash
 cron add \
  --name "nightly-health" \
  --schedule "0 2 * * *" \
  --timezone "Asia/Ho_Chi_Minh" \
  --task "oh -p 'Run full healthcheck' --output-format json" \
  --failure-alert '{"channel":"alerts","to":"#devops"}'
 ```
 </Good>
 <Bad>
 Running backup every minute without timeout — can overlap and cause issues.
 </Bad>
 ## Monitoring
 Check cron status:
 ```bash
 cron status
 ```
 View recent runs:
 ```bash
 cron runs --limit 20
 ```
 Failed runs trigger alerts if configured.
 ## Verification Checklist
 - [ ] Cron expression is correct (use crontab.guru to verify)
 - [ ] Task command works manually (`cron run`)
 - [ ] Timezone is set correctly
 - [ ] Failure alerts configured for critical jobs
 - [ ] Overlap is prevented (task duration < interval)
 - [ ] Job history shows successful runs
@@ -0,0 +1,140 @@
 ---
 name: excel-operations
 description: Read, write, and manipulate Excel (.xlsx) and CSV files
 ---
 ## When to use
 Use when the user asks to:
 - Read data from Excel or CSV files
 - Create new spreadsheets
 - Update existing spreadsheet data
 - Perform calculations or data transformations
 - Export data to CSV/Excel format
 - Validate spreadsheet structure
 ## Workflow
 ### 1. Identify the file
 Determine file path and format (.xlsx, .csv, .tsv).
 ### 2. Read the data
 OpenClaw's `read` is for text files. For Excel/CSV:
 **For CSV** (plain text):
 ```bash
 read path/to/data.csv
 ```
 **For .xlsx** (binary): Use Python or other tools:
 ```bash
 python -c "
 import pandas as pd, json, sys;
 df = pd.read_excel('data.xlsx');
 print(df.to_json(orient='records'))
 "
 ```
 Or install `xlsx2csv` and convert first:
 ```bash
 xlsx2csv data.xlsx temp.csv
 read temp.csv
 ```
 ### 3. Process the data
 - Parse into structured format (list of objects, 2D array)
 - Validate headers/columns if needed
 - Perform transformations (filter, map, aggregate)
 ### 4. Write results
 **For CSV**:
 ```bash
 write output.csv --data "$csv_string"
 ```
 **For .xlsx**: Use Python:
 ```bash
 python -c "
 import pandas as pd, json, sys;
 data = json.loads(sys.argv[1]);
 pd.DataFrame(data).to_excel('output.xlsx', index=False)
 " "$structured_data"
 ```
 ## Supported Formats
 - **.xlsx** (Excel Open XML) — full support for sheets, formulas, formatting
 - **.csv** (Comma-separated) — plain text, delimiter detection
 - **.tsv** (Tab-separated) — tab delimiter
 ## Common Operations
 ### Read specific sheet
 ```bash
 read file.xlsx --sheet "Sheet2"
 ```
 ### Read with range
 ```bash
 read file.xlsx --range "A1:D100"
 ```
 ### Write with formatting
 ```bash
 write report.xlsx \
  --data "$table" \
  --header true \
  --autofit columns
 ```
 ### Append to existing file
 ```bash
 write file.xlsx --data "$new_rows" --append true
 ```
 ## Data Structures
 **Reading returns**:
 ```json
 {
  "headers": ["Name", "Email", "Score"],
  "rows": [
    {"Name": "Alice", "Email": "a@example.com", "Score": 95},
    ...
  ]
 }
 ```
 **Writing accepts**:
 - JSON array of objects
 - 2D array (array of arrays)
 - CSV string (if format=csv)
 ## Examples
 <Good>
 User: "Tạo báo cáo điểm từ scores.csv"
 Assistant:
 1. Đọc scores.csv
 2. Tính toán điểm trung bình, xếp loại
 3. Ghi vào report.xlsx với định dạng đẹp
 4. Trả về đường dẫn file và tóm tắt kết quả
 </Good>
 <Bad>
 Ghi đè file gốc mà không backup, không thông báo.
 </Bad>
 ## Error Handling
 - **File not found**: Kiểm tra đường dẫn, dùng `glob` để tìm
 - **Format mismatch**: Đảm bảo file đúng định dạng, kiểm tra extension
 - **Large files**: Có thể cần chunk processing, kiểm tra memory limits
 - **Corrupted data**: Catch parse errors, report specific row/column
 ## Validation Checklist
 - [ ] File exists and is readable
 - [ ] Format matches extension
 - [ ] Headers are present and correct
 - [ ] Data types are correct (numbers, dates, strings)
 - [ ] No missing values in required columns
 - [ ] Output file is well-formed and complete
@@ -0,0 +1,136 @@
 ---
 name: hook-management
 description: Implement lifecycle hooks (PreToolUse/PostToolUse) using OpenClaw's existing tools and config
 ---
 ## When to use
 Use when you need to:
 - Add validation before dangerous tools (exec, write, edit)
 - Audit/log all tool usage
 - Enforce custom security policies
 - Track costs/metrics around tool calls
 - Transform tool outputs before they reach the model
 **Note**: OpenClaw does not have native PreToolUse/PostToolUse hooks. This skill shows you how to achieve similar effects using available mechanisms.
 ## Approach 1: Permission Mode + Rules (Built-in)
 OpenClaw already has a permission system. Use it:
 ### Set permission mode
 ```bash
 # Ask before every write/exec (default safe)
 gateway config set tools.exec.security full
 # Or use plan mode to block all writes
 # (requires implementing plan_mode toggle)
 ```
 ### Path-level rules in config
 Edit `openclaw.json`:
 ```json
 {
  "permissions": {
    "path_rules": [
      { "pattern": "**/secrets/**", "allow": false },
      { "pattern": "**/*.key", "allow": false }
    ],
    "denied_commands": ["rm -rf /", "DROP TABLE *", "format c:"]
  }
 }
 ```
 ## Approach 2: Wrapper Scripts (Shell Proxy)
 Create wrapper scripts that add validation/logging:
 ### Example: Safe exec wrapper
 ```bash
 # ~/.openclaw/wrappers/exec-safe
 #!/bin/bash
 # PreToolUse validation
 CMD="$1"
 if echo "$CMD" | grep -qE "(rm -rf|dd if=|mkfs)"; then
  echo "ERROR: Dangerous command blocked: $CMD" >&2
  exit 1
 fi
 # Audit log
 echo "$(date -Iseconds) USER EXEC: $CMD" >> ~/.openclaw/logs/exec-audit.log
 # Execute
 exec /usr/lib/openclaw/tools/exec.real "$@"
 ```
 Then configure OpenClaw to use the wrapper instead of the built-in exec tool.
 ## Approach 3: Plugin Interception (If Plugin System Supports)
 If OpenClaw plugins can intercept tool calls:
 ```json
 {
  "name": "audit-plugin",
  "version": "1.0.0",
  "preToolUse": {
    "command": "audit-log",
    "priority": 1000
  }
 }
 ```
 **Check plugin docs** to see if `preToolUse`/`postToolUse` are supported.
 ## Approach 4: Custom Agent with Restricted Tools
 Spawn a subagent with limited tool set:
 ```bash
 clawteam spawn tmux openclaw \
  --agent-type restricted \
  --tools "read,write,web_search"  # no exec, no dangerous tools
 ```
 ## Common Use Cases & Solutions
 ### Audit logging all tool calls
 - **Solution**: Wrapper scripts that log to file
 - Or use OpenClaw's built-in logging if available
 ### Block dangerous commands
 - **Solution**: `denied_commands` in config
 - Or wrapper validation
 ### Rate limiting
 - **Solution**: Track in session memory, check before allowing
 - No built-in — implement in custom plugin/agent
 ### Cost tracking
 - **Solution**: Parse logs, aggregate token usage
 - OpenClaw may already log token counts
 ### Input sanitization
 - **Solution**: Pre-process arguments in wrapper
 - Or validate in agent logic before calling tool
 ## Verification Checklist
 - [ ] Hooks/validation are actually triggered
 - [ ] Dangerous operations are blocked as intended
 - [ ] Audit logs capture necessary details (who, what, when)
 - [ ] No performance degradation (wrappers are fast)
 - [ ] Rules don't interfere with normal operations
 - [ ] Fail open/closed appropriately (security vs availability)
 ## Limitations
 - No native hook priority system — order depends on wrapper chain
 - No automatic hook discovery — manual registration needed
 - Wrapper approach requires maintaining extra scripts
 - Not as elegant as built-in hook system
 ## Future: Request Native Hooks
 If hooks are critical, consider:
 - Feature request to OpenClaw maintainers
 - Contributing a hook system implementation
 - Using OpenHarness as an alternative (has native hooks)
@@ -0,0 +1,144 @@
 ---
 name: mcp-integration
 description: Connect to Model Context Protocol (MCP) servers using exec and manual integration
 ---
 ## When to use
 Use when you need to:
 - Access external data sources via MCP (filesystem, GitHub, databases)
 - Use tools provided by MCP servers
 - Integrate with existing MCP infrastructure
 - Extend OpenClaw's capabilities beyond native tools
 **Note**: OpenClaw does not have a built-in MCP client. This skill shows how to manually integrate MCP using available tools.
 ## What is MCP?
 Model Context Protocol (MCP) is a standard for LLM apps to connect to external data sources and tools. MCP servers expose:
 - **Resources**: Read-only data
 - **Tools**: Callable functions
 - **Prompts**: Prompt templates
 ## Manual Integration Approach
 Since OpenClaw lacks native MCP, you need to:
 ### 1. Run MCP server as subprocess
 Start an MCP server in the background:
 ```bash
 # Example: filesystem MCP server
 npx @modelcontextprotocol/server-filesystem /allowed/path &
 MCP_PID=$!
 # Or GitHub MCP
 GITHUB_TOKEN=ghp_... npx @modelcontextprotocol/server-github &
 ```
 ### 2. Communicate via stdio
 The MCP protocol uses JSON-RPC over stdio. You need to:
 - Write JSON-RPC requests to server's stdin
 - Read responses from server's stdout
 - Handle initialization handshake
 ### 3. Wrap as custom tool
 Create a shell function or script that:
 - Accepts arguments (tool name, params)
 - Sends JSON-RPC request to MCP server
 - Returns result to OpenClaw
 Example pseudo-code:
 ```bash
 #!/bin/bash
 # mcp-call.sh
 TOOL="$1"
 shift
 PARAMS="$*"
 # Send JSON-RPC request (simplified)
 echo "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"$TOOL\",\"arguments\":$PARAMS}}" > /tmp/mcp.stdin
 # Read response from /tmp/mcp.stdout
 ```
 ### 4. Use in OpenClaw
 ```bash
 # Call MCP tool via wrapper
 exec ~/.openclaw/mcp/mcp-call.sh github_create_issue --repo 'owner/repo' --title 'Bug' --body '...'
 ```
 ## Alternative: Use OpenHarness for MCP
 OpenHarness has built-in MCP support (`mcp` command). If MCP integration is important:
 1. Run OpenHarness alongside OpenClaw
 2. Use OpenHarness as MCP gateway
 3. Call OpenHarness from OpenClaw via HTTP or CLI
 ## Supported MCP Servers (Common)
 - `@modelcontextprotocol/server-filesystem` — local file access
 - `@modelcontextprotocol/server-github` — GitHub API
 - `@modelcontextprotocol/server-postgres` — PostgreSQL
 - `@modelcontextprotocol/server-sqlite` — SQLite
 - `@modelcontextprotocol/server-http` — generic HTTP APIs
 ## Security Considerations
 ⚠️ MCP servers run with your user privileges and can:
 - Read/write any files in mounted paths
 - Access network resources
 - Use credentials (GitHub tokens, DB passwords)
 **Mitigations**:
 - Restrict filesystem paths strictly
 - Use read-only tools when possible
 - Limit token scopes
 - Run MCP servers in sandbox if untrusted
 ## Workflow Example: Read file via MCP
 1. Start filesystem MCP:
 ```bash
 npx @modelcontextprotocol/server-filesystem /home/user/project &
 ```
 2. List resources:
 ```bash
 # Send request manually or via script
 echo '{"jsonrpc":"2.0","id":1,"method":"resources/list"}' > /proc/$PID/fd/0
 ```
 3. Read a resource:
 ```bash
 # Assuming you have a wrapper `mcp-read`
 mcp-read file:///project/README.md
 ```
 ## Implementation Difficulty
 **Manual MCP integration is non-trivial**:
 - Need to implement JSON-RPC 2.0
 - Handle server initialization handshake
 - Manage async notifications
 - Error handling and reconnection
 **Recommendation**: Use OpenHarness if you need MCP now, or wait for OpenClaw to add native support.
 ## Verification Checklist
 - [ ] MCP server starts successfully and stays running
 - [ ] Initialization handshake completes (capabilities exchanged)
 - [ ] Tool calls return expected results
 - [ ] Resources are accessible and correctly formatted
 - [ ] Errors are handled gracefully
 - [ ] No sensitive data leaks in logs
 - [ ] MCP process is properly terminated when done
 ## Future: Native MCP Client
 A proper OpenClaw MCP integration would:
 - Manage server lifecycle automatically
 - Provide `mcp` command (list-tools, call-tool, read-resource)
 - Handle JSON-RPC transparently
 - Cache resources
 - Support multiple servers
 Consider contributing this to OpenClaw if needed.
@@ -0,0 +1,111 @@
 ---
 name: notebook-edit
 description: Edit Jupyter notebook cells: read, modify, insert, delete, and execute code cells
 ---
 ## When to use
 Use when the user asks to:
 - Modify code in a Jupyter notebook (.ipynb)
 - Add new cells (code, markdown, raw)
 - Delete or reorder cells
 - Update cell outputs
 - Execute notebook cells (if kernel available)
 - Convert notebooks to other formats
 ## Workflow
 ### 1. Locate the notebook
 Find the .ipynb file path.
 ### 2. Read notebook structure
 ```bash
 read notebook.ipynb
 ```
 This returns the raw JSON structure of the notebook with cells, sources, outputs, metadata. You'll need to parse this JSON manually.
 ### 3. Make edits
 Use `edit` tool to modify the notebook JSON directly:
 - Edit `cells[*].source` to change code/markdown content
 - Edit `cells[*].cell_type` to change type ("code", "markdown")
 - Insert/delete by modifying the `cells` array
 - Be careful with JSON structure — validate after edits
 ### 4. Execute cells (optional)
 OpenClaw does not have a built-in `notebook_execute` tool. If you need to execute notebooks, either:
 - Use `exec` to run `jupyter nbconvert --execute notebook.ipynb`
 - Or manually run the code cells section by section using `code_execution`
 ### 5. Save changes
 Edits are saved automatically upon tool completion, or explicitly write.
 ## Cell Types
 - **code**: Executable Python/R/Julia code
 - **markdown**: Documentation with Markdown formatting
 - **raw**: Unformatted text (rarely used)
 ## Common Operations
 ### Add a code cell at the end
 ```bash
 notebook_edit notebook.ipynb \
  --insert "end" \
  --cell-type code \
  --source "print('Hello')"
 ```
 ### Update existing cell
 ```bash
 notebook_edit notebook.ipynb \
  --cell-index 3 \
  --source "x = 5\nprint(x*2)"
 ```
 ### Delete a cell
 ```bash
 notebook_edit notebook.ipynb \
  --cell-index 2 \
  --delete true
 ```
 ### Run all cells
 ```bash
 notebook_execute notebook.ipynb --all
 ```
 ### Clear outputs
 ```bash
 notebook_edit notebook.ipynb --clear-outputs true
 ```
 ## Safety Rules
 - **Backup first**: Copy notebook before major edits
 - **Don't overwrite outputs** unless explicitly asked
 - **Preserve cell metadata**: Some notebooks rely on custom metadata
 - **Kernel restarts**: Changes to imports/functions may require kernel restart
 ## Examples
 <Good>
 User: "Thêm cell tính trung bình vào notebook analysis.ipynb"
 Assistant:
 1. Đọc notebook hiện tại
 2. Tìm vị trí phù hợp (sau phần data loading)
 3. Thêm code cell với formulas đúng
 4. Kiểm tra syntax trước khi lưu
 </Good>
 <Bad>
 Sửa cell mà không xem nội dung gốc, có thể mất code quan trọng.
 </Bad>
 ## Error Handling
 - **Invalid cell index**: Check notebook length first
 - **JSON parse error**: Notebook có thể bị corrupt, backup và repair
 - **Kernel not available**: Execution sẽ fail, chỉ edit được code
 ## Verification Checklist
 - [ ] Notebook file is valid JSON
 - [ ] Cell indices are within bounds
 - [ ] Code syntax is correct (consider linting)
 - [ ] No orphaned outputs (clear if needed)
 - [ ] Notebook can still open in Jupyter after edit
@@ -0,0 +1,79 @@
 ---
 name: pdf-processing
 description: Read, extract, and manipulate PDF documents
 ---
 ## When to use
 Use when the user asks to:
 - Extract text from PDF files
 - Read PDF content (full or specific pages)
 - Split or merge PDF documents
 - Extract metadata (title, author, page count)
 - Search within PDFs
 ## Workflow
 ### 1. Identify the PDF file
 Locate the PDF file path. Use `glob` or `ls` if needed.
 ### 2. Extract text (full or partial)
 OpenClaw's `read` tool does not directly support PDF. You need to convert PDF to text first:
 ```bash
 # Convert PDF to text using pdftotext (if available)
 exec pdftotext path/to/file.pdf -
 # Or use Python
 python -c "
 import pypdf; 
 reader = pypdf.PdfReader('file.pdf');
 print('\n'.join([page.extract_text() for page in reader.pages]))
 "
 ```
 Then capture the output for processing.
 ### 3. Parse and structure content
 - If extracting form data, organize into key-value pairs
 - If extracting tables, preserve structure (CSV/markdown table)
 - If searching, return matching snippets with page numbers
 ### 4. For advanced operations
 - **Split PDF**: Use appropriate tool to split into separate files
 - **Merge PDFs**: Combine multiple PDFs in order
 - **Metadata**: Extract or modify PDF metadata
 ## Tool Requirements
 This skill assumes the following tools are available:
 - `exec` (to run conversion commands: pdftotext, python, etc.)
 - `read` (for text files after conversion)
 - `write`/`edit` (for saving extracted content)
 - Optional: `poppler-utils` package (pdftotext) or `pypdf` Python library
 ## Examples
 <Good>
 User: "Lấy nội dung invoice.pdf"
 Assistant:
 1. Xác định đường dẫn file
 2. Dùng read để extract text
 3. Trích xuất thông tin quan trọng (số hóa đơn, ngày, tổng tiền)
 4. Trả về dữ liệu có cấu trúc
 </Good>
 <Bad>
 Chỉ nói "Tôi đọc được nội dung PDF" mà không trích xuất thông tin cụ thể.
 </Bad>
 ## Limitations
 - Large PDFs (>100 pages) may be truncated — check tool limits
 - Scanned PDFs require OCR — ensure OCR tool is available
 - Password-protected PDFs need password first
 ## Verification Checklist
 - [ ] PDF file exists and is accessible
 - [ ] Extracted text is complete (no truncation)
 - [ ] Structured data is accurate
 - [ ] Page numbers/references are correct if cited
 - [ ] For tables, formatting is preserved
@@ -0,0 +1,168 @@
 ---
 name: security-best-practices
 description: Apply security hardening, input validation, and protection measures across all operations
 ---
 ## When to use
 Use when the user asks to:
 - Secure an application or system
 - Audit code for vulnerabilities
 - Set up authentication/authorization
 - Harden configurations
 - Perform security reviews
 - Handle secrets and credentials
 ## Core Principles
 ### 1. Defense in Depth
 Apply multiple layers of security:
 - Input validation
 - Authentication
 - Authorization
 - Output encoding
 - Encryption
 - Auditing
 ### 2. Least Privilege
 Agents/tools should have only the permissions they need:
 - File access: restrict to specific directories
 - Network: allow only required endpoints
 - Tools: disable dangerous ones when not needed
 ### 3. Fail Securely
 Errors should not reveal sensitive information:
 - Generic error messages to users
 - Detailed errors only in logs (protected)
 - Secure defaults (deny by default)
 ## Security Checklist
 ### Input Validation
 - [ ] Validate all user inputs (type, length, format, range)
 - [ ] Sanitize to remove/escape dangerous characters
 - [ ] Use parameterized queries (no string concatenation)
 - [ ] Reject unexpected values early
 ### Authentication & Authorization
 - [ ] Use strong, salted password hashing (bcrypt, Argon2)
 - [ ] Implement multi-factor authentication for sensitive operations
 - [ ] Enforce least privilege (RBAC/ABAC)
 - [ ] Use short-lived tokens, rotate regularly
 - [ ] Validate permissions on every request
 ### Secrets Management
 - [ ] Never hardcode secrets in source code
 - [ ] Use environment variables or secret vaults
 - [ ] Rotate credentials regularly
 - [ ] Different secrets per environment (dev/staging/prod)
 - [ ] Don't log secrets (redact from logs)
 ### Data Protection
 - [ ] Encrypt sensitive data at rest (AES-256)
 - [ ] Use TLS 1.2+ for data in transit
 - [ ] Secure backups (encrypted, access-controlled)
 - [ ] Anonymize/pseudonymize PII when possible
 ### Output Encoding
 - [ ] Encode data before rendering (HTML escape, SQL escape, shell escape)
 - [ ] Use templating engines with auto-escaping
 - [ ] Content Security Policy (CSP) headers for web apps
 ### Dependency Security
 - [ ] Regularly audit dependencies for CVEs
 - [ ] Use minimal dependencies
 - [ ] Pin versions (avoid floating ranges)
 - [ ] Update promptly when vulnerabilities disclosed
 ## Code Review Security Points
 Review code for:
 - **SQL injection**: raw queries with string concatenation
 - **XSS**: unescaped output in HTML/JS
 - **CSRF**: missing tokens on state-changing requests
 - **Path traversal**: user-controlled file paths without validation
 - **Insecure deserialization**: untrusted data → object creation
 - **Hardcoded secrets**: passwords, API keys in source
 - **Weak crypto**: MD5, SHA1, custom algorithms, hardcoded keys
 ## Configuration Hardening
 ### File permissions
 ```bash
 chmod 600 ~/.openclaw/credentials/*.json  # Owner read/write only
 chmod 700 ~/.openclaw/workspace          # Restrict workspace
 ```
 ### Network security
 - Firewall: allow only necessary ports
 - VPN for remote access
 - Disable unnecessary services
 ### Audit logging
 Log all security events:
 - Authentication attempts (success/failure)
 - Authorization failures
 - Configuration changes
 - Data access (especially PII)
 Include: timestamp, user, action, IP, outcome
 ## Incident Response
 If a breach is suspected:
 1. **Isolate**: Cut off network access if possible
 2. **Preserve logs**: Don't delete; copy for analysis
 3. **Assess scope**: Which systems/data affected?
 4. **Notify**: Follow disclosure procedures
 5. **Remediate**: Patch vulnerabilities, rotate credentials
 6. **Post-mortem**: Document lessons learned
 ## Tools for Security Audit
 Use OpenClaw skills:
 - `security-review`: Automated code security scan
 - `systematic-debugging`: Identify root cause of vulnerabilities
 - `code-quality-gate`: Enforce security standards
 External tools:
 - OWASP ZAP / Burp Suite (web scanning)
 - Trivy / Grype (dependency scanning)
 - Bandit / Semgrep (SAST)
 - sqlmap (SQL injection testing)
 ## Examples
 <Good>
 Database query with parameterized statement:
 ```python
 cursor.execute("SELECT * FROM users WHERE email = %s", (email,))
 ```
 </Good>
 <Bad>
 ```python
 query = f"SELECT * FROM users WHERE email = '{email}'"
 cursor.execute(query)  # SQL injection vulnerability
 ```
 </Bad>
 ## Compliance Considerations
 Depending on industry:
 - **GDPR**: Data protection, privacy by design, breach notification
 - **PCI DSS**: Payment card data handling
 - **HIPAA**: Healthcare data encryption and access logs
 - **SOC 2**: Security controls and audit trails
 ## Verification Checklist
 - [ ] All user inputs validated and sanitized
 - [ ] No hardcoded secrets in codebase
 - [ ] Secrets stored securely (env vars, vault)
 - [ ] Database queries use parameterized statements
 - [ ] Output properly encoded for context (HTML, SQL, shell)
 - [ ] Authentication strong (bcrypt, 2FA)
 - [ ] Authorization checks on all protected actions
 - [ ] Sensitive data encrypted at rest and in transit
 - [ ] Audit logs capture security events
 - [ ] Dependencies up-to-date with no known CVEs
 - [ ] Regular security scans performed
 - [ ] Incident response plan documented