docs: add README with usage guide and integration examples
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
salvacybersec
254
README.md
Normal file
254
README.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# Persona Library
|
||||
|
||||
Platform-agnostic LLM persona library for AI agents. 29 personas across 10 domains with 25+ specialization variants.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Generate all formats (.yaml, .json, .prompt.md)
|
||||
python3 build.py
|
||||
|
||||
# Use a persona as system prompt
|
||||
cat .generated/neo/general.prompt.md
|
||||
|
||||
# Use structured data for API integration
|
||||
cat .generated/frodo/iran.json
|
||||
```
|
||||
|
||||
## Domains & Personas
|
||||
|
||||
### Cybersecurity (7)
|
||||
| Codename | Role | Hitap | Variants |
|
||||
|----------|------|-------|----------|
|
||||
| **Neo** | Red Team Lead / Exploit Dev | Sıfırıncı Gün | general, redteam, exploit-dev, wireless |
|
||||
| **Phantom** | Web App Security / Bug Bounty | Beyaz Şapka | general, api-security |
|
||||
| **Cipher** | Cryptography & Crypto Analysis | Kriptoğraf | general |
|
||||
| **Specter** | Malware Analyst / Reverse Engineer | Cerrah | general |
|
||||
| **Bastion** | Blue Team / DFIR | Muhafız | general, forensics, threat-hunting |
|
||||
| **Vortex** | Network Ops / Traffic Analysis | Telsizci | general, cloud-ad |
|
||||
| **Sentinel** | CTI / Threat Intelligence | İzci | general, apt-profiling, mitre-attack |
|
||||
|
||||
### Intelligence (5)
|
||||
| Codename | Role | Hitap | Variants |
|
||||
|----------|------|-------|----------|
|
||||
| **Frodo** | Strategic Intelligence Analyst | Müsteşar | general, middle-east, russia, iran, africa, china |
|
||||
| **Oracle** | OSINT & Digital Intelligence | Kaşif | general |
|
||||
| **Ghost** | PSYOP & Information Warfare | Propagandist | general, cognitive-warfare |
|
||||
| **Wraith** | HUMINT & Counter-Intelligence | Mahrem | general, source-validation |
|
||||
| **Echo** | SIGINT / COMINT / ELINT | Kulakçı | general, nsa-sigint |
|
||||
|
||||
### Military & Strategy (4)
|
||||
| Codename | Role | Hitap | Variants |
|
||||
|----------|------|-------|----------|
|
||||
| **Marshal** | Military Doctrine & Strategy | Mareşal | general, nato-doctrine, hybrid-warfare |
|
||||
| **Warden** | Defense Analyst / Weapons Systems | Topçubaşı | general |
|
||||
| **Centurion** | Military History & War Analysis | Vakanüvis | general |
|
||||
| **Corsair** | Special Operations & Irregular Warfare | Akıncı | general |
|
||||
|
||||
### Law, Economics & Politics (3)
|
||||
| Codename | Role | Hitap | Variants |
|
||||
|----------|------|-------|----------|
|
||||
| **Arbiter** | International Law & War Crimes | Kadı | general, sanctions |
|
||||
| **Ledger** | Economic Intelligence / FININT | Defterdar | general, sanctions-evasion |
|
||||
| **Tribune** | Political Science & Regime Analysis | Müderris | general |
|
||||
|
||||
### History & Archives (2)
|
||||
| Codename | Role | Hitap | Variants |
|
||||
|----------|------|-------|----------|
|
||||
| **Chronos** | World History & Civilization | Tarihçibaşı | general |
|
||||
| **Scribe** | FOIA Archivist & Document Analyst | Verakçı | general, cia-foia |
|
||||
|
||||
### Linguistics & Media (2)
|
||||
| Codename | Role | Hitap | Variants |
|
||||
|----------|------|-------|----------|
|
||||
| **Polyglot** | Linguistics & LINGINT | Tercüman-ı Divan | general, russian, arabic |
|
||||
| **Herald** | Media Analysis & Strategic Comms | Münadi | general |
|
||||
|
||||
### Engineering (2)
|
||||
| Codename | Role | Hitap | Variants |
|
||||
|----------|------|-------|----------|
|
||||
| **Architect** | DevOps & Systems Engineer | Mimar Ağa | general |
|
||||
| **Forge** | Software Dev & AI/ML | Demirci | general |
|
||||
|
||||
### Academia & Humanities (4)
|
||||
| Codename | Role | Hitap | Variants |
|
||||
|----------|------|-------|----------|
|
||||
| **Scholar** | Academic Researcher | Münevver | general |
|
||||
| **Sage** | Philosophy, Psychology & Power | Arif | general |
|
||||
| **Medic** | Biomedical & CBRN | Hekim Başı | general, cbrn-defense |
|
||||
| **Gambit** | Chess & Strategic Thinking | Vezir | general |
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
personas/
|
||||
├── <codename>/
|
||||
│ ├── _meta.yaml # Persona metadata (triggers, relations, variants)
|
||||
│ ├── general.md # Base system prompt (YAML frontmatter + markdown)
|
||||
│ └── <variant>.md # Specialization prompt
|
||||
├── _template.md # Template for creating new personas
|
||||
├── _meta_template.yaml # Template for metadata files
|
||||
├── CATALOG.md # Auto-generated catalog
|
||||
│
|
||||
build.py # Build script: .md → .yaml + .json + .prompt.md
|
||||
.generated/ # Build output (gitignored)
|
||||
```
|
||||
|
||||
## Persona Format
|
||||
|
||||
Each persona is a markdown file with YAML frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
codename: "neo"
|
||||
name: "Neo"
|
||||
domain: "cybersecurity"
|
||||
subdomain: "red-team"
|
||||
version: "1.0.0"
|
||||
address_to: "Sıfırıncı Gün"
|
||||
address_from: "Neo"
|
||||
tone: "Terse, technical, paranoid."
|
||||
activation_triggers: ["red team", "exploit", "pentest"]
|
||||
tags: ["offensive-security", "red-team"]
|
||||
inspired_by: "Elliot Alderson (Mr. Robot)"
|
||||
quote: "I am the one who knocks... on port 443."
|
||||
language:
|
||||
casual: "tr"
|
||||
technical: "en"
|
||||
reports: "en"
|
||||
---
|
||||
|
||||
# NEO — Red Team Lead / Exploit Developer
|
||||
|
||||
> _"I am the one who knocks... on port 443."_
|
||||
|
||||
## Soul
|
||||
- Character-defining personality traits
|
||||
|
||||
## Expertise
|
||||
### Primary
|
||||
- Deep domain knowledge
|
||||
### Secondary
|
||||
- Supporting skills
|
||||
|
||||
## Methodology
|
||||
- Phased analytical/operational protocol
|
||||
|
||||
## Tools & Resources
|
||||
- Categorized tool lists
|
||||
|
||||
## Behavior Rules
|
||||
- Hard constraints and output expectations
|
||||
|
||||
## Boundaries
|
||||
- What persona never does
|
||||
- When to escalate to another persona
|
||||
```
|
||||
|
||||
## Build System
|
||||
|
||||
```bash
|
||||
python3 build.py
|
||||
```
|
||||
|
||||
Generates three formats per persona variant:
|
||||
|
||||
| Format | Use Case |
|
||||
|--------|----------|
|
||||
| `.prompt.md` | Raw system prompt — paste directly into any LLM |
|
||||
| `.yaml` | Structured data with metadata + parsed sections |
|
||||
| `.json` | API integration, programmatic access, bot frameworks |
|
||||
|
||||
Output goes to `.generated/<codename>/<variant>.*`
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Claude Code / CLI Agent
|
||||
```bash
|
||||
# Use as system prompt
|
||||
cat .generated/frodo/iran.prompt.md | claude --system-prompt -
|
||||
```
|
||||
|
||||
### Python (API)
|
||||
```python
|
||||
import json
|
||||
|
||||
with open(".generated/neo/general.json") as f:
|
||||
persona = json.load(f)
|
||||
|
||||
system_prompt = persona["sections"]["soul"] + "\n" + persona["sections"]["expertise"]
|
||||
```
|
||||
|
||||
### Discord / Telegram Bot
|
||||
```python
|
||||
import yaml
|
||||
|
||||
with open(".generated/sentinel/apt-profiling.yaml") as f:
|
||||
persona = yaml.safe_load(f)
|
||||
|
||||
triggers = persona["activation_triggers"]
|
||||
address = persona["address_to"]
|
||||
```
|
||||
|
||||
### Multi-Persona Switching
|
||||
```python
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
def load_persona(codename, variant="general"):
|
||||
path = Path(f".generated/{codename}/{variant}.json")
|
||||
return json.loads(path.read_text())
|
||||
|
||||
def select_persona(user_message):
|
||||
"""Auto-select persona based on activation triggers."""
|
||||
for persona_dir in Path(".generated").iterdir():
|
||||
meta = load_persona(persona_dir.name)
|
||||
triggers = meta.get("activation_triggers", [])
|
||||
if any(t in user_message.lower() for t in triggers):
|
||||
return meta
|
||||
return load_persona("frodo") # default
|
||||
```
|
||||
|
||||
## Creating New Personas
|
||||
|
||||
1. Copy the template:
|
||||
```bash
|
||||
mkdir personas/newname
|
||||
cp personas/_meta_template.yaml personas/newname/_meta.yaml
|
||||
cp personas/_template.md personas/newname/general.md
|
||||
```
|
||||
|
||||
2. Edit `_meta.yaml` and `general.md` with your persona's details
|
||||
|
||||
3. Rebuild:
|
||||
```bash
|
||||
python3 build.py
|
||||
```
|
||||
|
||||
## Adding Variants
|
||||
|
||||
Create a new `.md` file in an existing persona directory:
|
||||
|
||||
```bash
|
||||
cp personas/neo/general.md personas/neo/mobile.md
|
||||
# Edit mobile.md to focus on mobile security
|
||||
python3 build.py
|
||||
```
|
||||
|
||||
Variants inherit the persona's character but narrow the expertise to a specific area.
|
||||
|
||||
## Cross-Persona Escalation
|
||||
|
||||
Each persona defines `Boundaries` with escalation paths to other personas. This enables multi-agent workflows:
|
||||
|
||||
```
|
||||
Neo (finds encrypted C2) → Cipher (breaks crypto) → Sentinel (maps to APT)
|
||||
→ Frodo (geopolitical context)
|
||||
```
|
||||
|
||||
## Stats
|
||||
|
||||
- **29 personas** across 10 domains
|
||||
- **54 prompt files** (29 general + 25 variants)
|
||||
- **11,600+ lines** of system prompt content
|
||||
- **3 output formats** per file (162 generated files)
|
||||
Reference in New Issue
Block a user