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