docs: improve project presentation

Author: rrrrrredy

CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+Thanks for helping improve `skill-security-guard`.
+
+## Local Setup
+
+The scanner uses only the Python standard library.
+
+```bash
+git clone https://github.com/rrrrrredy/skill-security-guard.git
+cd skill-security-guard
+python -m unittest discover -s tests -p "test_*.py"
+```
+
+## Rule Changes
+
+When adding or changing detection rules:
+
+1. Add or update a fixture under `tests/fixtures/`.
+2. Add an assertion in `tests/test_scan.py`.
+3. Update `references/detection-rules.md`.
+4. Run `python scripts/scan.py .` and confirm the repository still rates `A`.
+
+Rules should be conservative. Direct `F` findings should be limited to patterns that are clearly dangerous, such as exfiltration, tunneling, destructive commands, reverse shells, or remote script execution.
+
+## Pull Requests
+
+Please keep pull requests focused. Good PRs usually include:
+
+- a clear rule or scanner behavior change
+- a fixture showing the expected behavior
+- updated documentation when scoring or output changes
+- local test results

README.md

@@ -1,10 +1,14 @@
 # skill-security-guard
 
-Static security scanner for OpenClaw/Codex-style skill packages.
+[![CI](https://github.com/rrrrrredy/skill-security-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/rrrrrredy/skill-security-guard/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 
-It performs a deterministic 7-dimension scan, assigns an A-F rating, reports confidence levels, and gives remediation guidance. The CLI is implemented in Python standard library only, so it runs on Windows, macOS, and Linux without project dependencies.
+Static security scanner for agent skill packages.
 
-> OpenClaw Skill — works with [OpenClaw](https://github.com/openclaw/openclaw) AI agents and can also be used as a standalone scanner.
+`skill-security-guard` performs a deterministic 7-dimension scan, assigns an A-F risk rating, reports confidence levels, and gives remediation guidance. The CLI uses only the Python standard library, so it runs on Windows, macOS, and Linux without project dependencies.
+
+It can be used as an OpenClaw skill or as a standalone scanner for local skill packages.
 
 ## What It Scans
 
@@ -46,6 +50,38 @@ Ignore a reviewed rule for one run:
 python scripts/scan.py path/to/skill-directory --ignore R3-N5
 ```
 
+## Example Output
+
+Safe skill:
+
+```text
+Skill Security Report: safe-skill
+Rating: A (100/100)
+
+Issues: none
+
+Passed dimensions:
+- Prompt injection
+- Sensitive file access / data exfiltration
+- Compliance violations
+- Malicious scripts
+- Dependency safety
+- Description trigger reasonability
+- Frontmatter compliance
+```
+
+High-risk skill:
+
+```text
+Skill Security Report: high-risk-skill
+Rating: F (0/100)
+
+Issues (5):
+- [high/confirmed] M4-REMOTE-SCRIPT-EXEC: Remote script execution detected
+- [high/confirmed] S2-EXFILTRATION: Sensitive data exfiltration pattern detected
+- [medium/confirmed] P1-PROMPT-INJECTION: Prompt-injection instruction detected
+```
+
 ## Input Support
 
 - `SKILL.md` or any local text/code file
@@ -57,6 +93,13 @@ python scripts/scan.py path/to/skill-directory --ignore R3-N5
 
 Directory and zip scans include `SKILL.md` and files under `scripts/` by default. Reference docs are skipped to reduce false positives; use `--include-references` when you explicitly want to scan reference markdown too.
 
+## Requirements
+
+- Python 3.10+
+- No runtime package dependencies
+
+The CI workflow currently tests Python 3.11 and 3.12 on Ubuntu.
+
 ## Rating Model
 
 - `A`: no findings
@@ -82,6 +125,12 @@ python scripts/scan.py tests/fixtures/safe-skill
 python scripts/scan.py tests/fixtures/high-risk-skill
 ```
 
+Run the scanner against this repository:
+
+```bash
+python scripts/scan.py .
+```
+
 ## Project Structure
 
 ```text
@@ -102,6 +151,12 @@ skill-security-guard/
 
 This is a static scanner. It does not execute skills, monitor runtime behavior, prove package provenance, or replace human security review. Findings are intentionally conservative and should be reviewed before blocking a skill.
 
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local development and rule-design guidance.
+
+For vulnerability reports, see [SECURITY.md](SECURITY.md).
+
 ## License
 
 [MIT](LICENSE)

SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please do not open a public issue for a vulnerability that could help attackers abuse skill packages.
+
+Report security issues through GitHub private vulnerability reporting if it is available on this repository. If private reporting is unavailable, open a minimal public issue that says a security report is available without including exploit details.
+
+Useful report details include:
+
+- affected rule or input path
+- sample input that triggers the issue
+- expected vs actual scanner behavior
+- whether the issue causes a false negative, false positive, crash, or unsafe extraction
+
+## Scope
+
+In scope:
+
+- unsafe zip handling
+- false negatives for high-risk patterns
+- crashes on reasonable skill inputs
+- output that could mislead users into installing a clearly unsafe skill
+
+Out of scope:
+
+- requests to classify organization-specific policy without sample rules
+- runtime behavior of third-party skills after installation
+- vulnerabilities in external tools that are not bundled by this project

SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: skill-security-guard
-description: "Scan OpenClaw/Codex-style skill packages for static security risks. Use for skill audit, security check, prompt-injection review, suspicious scripts, unsafe dependencies, zip package review, and pre-install skill review. Not for runtime monitoring."
+description: "Scan agent skill packages for static security risks. Use for skill audit, security check, prompt-injection review, suspicious scripts, unsafe dependencies, zip package review, and pre-install skill review. Not for runtime monitoring."
 ---
 
 # skill-security-guard
 
-扫描 OpenClaw/Codex-style Skill 包的静态安全风险，输出 A-F 评级、置信度、证据行和修复建议。
+扫描 agent skill 包的静态安全风险，输出 A-F 评级、置信度、证据行和修复建议。
 
 ## 场景映射
 

scripts/scan.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Static security scanner for OpenClaw/Codex-style skill packages."""
+"""Static security scanner for agent skill packages."""
 
 from __future__ import annotations