# Hermes Skill-Building Playbook

> **Author:** Hermes System Reference  
> **Location:** `/root/hermes-dashboard/public/SKILL_PLAYBOOK.md`  
> **Purpose:** Complete reference for building, modifying, and maintaining Hermes skills.

---

## Table of Contents

1. [What Is a Skill?](#1-what-is-a-skill)
2. [File Structure Reference](#2-file-structure-reference)
3. [SKILL.md Frontmatter Reference](#3-skillmd-frontmatter-reference)
4. [The Two Types of Skills](#4-the-two-types-of-skills)
5. [How to Build a New Script-Backed Skill (Step by Step)](#5-how-to-build-a-new-script-backed-skill-step-by-step)
6. [Key Technical Rules](#6-key-technical-rules)
7. [Key File Locations](#7-key-file-locations)
8. [Routing Priority in SOUL.md](#8-routing-priority-in-soulmd)
9. [Active Skills Reference Table](#9-active-skills-reference-table)
10. [Modifying Existing Skills](#10-modifying-existing-skills)

---

## 1. What Is a Skill?

A **skill** is a folder at `/root/.hermes/skills/{category}/{skill-name}/` containing at minimum one file: `SKILL.md`.

### The SKILL.md File

The `SKILL.md` has two parts:

1. **YAML frontmatter** — structured metadata: name, description, version, tags, trigger phrase
2. **Markdown body** — the actual instructions the agent follows

When the agent loads a skill via `skill_view(name="skill-name")`, the full content of `SKILL.md` is injected into its working context. From that point on, the agent behaves according to the instructions in that skill.

### Why Skills Exist

Skills are **persistent working procedures**. Unlike instructions given in-context (which are forgotten when the session ends), skills survive across sessions. Every time Hermes encounters the trigger phrase associated with a skill, it can reload the exact same procedure — deterministically.

This makes them ideal for:
- Workflows you run repeatedly (LOI generation, deal screening, document creation)
- Behavioral rules you always want applied (stop-slop, output formatting)
- Reference knowledge the agent should always have available (investment thesis, buy box)
- Complex multi-step procedures with scripts that live on disk

### Supporting Files

Skills can contain more than just the `SKILL.md`. Supporting files live in subdirectories of the skill folder:
- **Python scripts** — the actual generators, run via `execute_code` or `terminal`
- **Templates** — base document templates the agent copies and fills in
- **Reference docs** — additional markdown files loaded via `skill_view(name="skill-name", file_path="references/doc.md")`

---

## 2. File Structure Reference

```
/root/.hermes/skills/
├── {category}/                          ← category folder (pe-os, productivity, creative, etc.)
│   └── {skill-name}/                   ← skill folder — must match `name:` in frontmatter
│       ├── SKILL.md                    ← REQUIRED: frontmatter + instructions
│       ├── templates/                  ← OPTIONAL: document templates, base scripts
│       │   └── base_document.py        ← pe-brand template lives here
│       ├── references/                 ← OPTIONAL: reference docs loaded via skill_view(file_path=)
│       │   └── criteria.md
│       └── scripts/                    ← OPTIONAL: Python scripts the agent runs
│           └── generate_report.py
```

### Real Examples

```
/root/.hermes/skills/pe-os/deal-screener/
├── SKILL.md
├── extract.py          ← universal extractor (PDF, DOCX, PPTX, etc.)
├── post.py             ← posts report to Slack thread
└── save_pipeline.py    ← saves deal JSON to CRM database

/root/.hermes/skills/pe-os/pe-acquisition-loi/
├── SKILL.md
└── generate_loi.py     ← generates branded .docx LOI

/root/.hermes/skills/productivity/pe-brand/
├── SKILL.md
└── templates/
    └── base_document.py    ← master .docx template (use this for ALL docx)
```

---

## 3. SKILL.md Frontmatter Reference

Every `SKILL.md` must begin with YAML frontmatter between `---` delimiters:

```yaml
---
name: skill-name              # Must match the folder name exactly
description: >-               # One sentence — what it does and when to use it
  Short description here.
version: 1.0.0                # Semantic version — increment on meaningful changes
tags: [tag1, tag2, tag3]      # Free-form tags for search/organization
trigger: Trigger phrase        # When the agent should auto-load this skill
---
```

### Field Notes

| Field | Required | Notes |
|---|---|---|
| `name` | Yes | Must exactly match the folder name. Mismatches cause `skill_view` failures. |
| `description` | Yes | One concise sentence. Shown in Toolkit tab of dashboard. |
| `version` | Recommended | Helps track when a skill was last meaningfully updated. |
| `tags` | Optional | Array of strings. Useful for grouping, not currently auto-routed. |
| `trigger` | Recommended | The phrase(s) that should prompt Hermes to auto-load this skill. Also echoed in SOUL.md routing. |

### Multi-line Description

For longer descriptions, use the YAML block scalar:

```yaml
description: >-
  Generates a branded Letter of Intent (.docx) for a PE acquisition target.
  Queries the CRM for deal data, builds the document, and delivers it via Slack.
```

---

## 4. The Two Types of Skills

### Type A — Instruction Skills

**Pure markdown instructions.** The agent reads the SKILL.md and knows how to behave. No scripts involved.

**Best for:**
- Behavioral guidance (how to write prose, how to format output)
- Reference information (investment thesis, buy box criteria, brand guidelines)
- Contextual knowledge the agent should carry in-session

**Examples:**
- `pe-os/pe-investment-thesis` — the firm's core investment thesis and market conviction
- `creative/stop-slop` — rules for removing AI writing patterns from all prose output
- `pe-os/pe-buy-box` — exact financial thresholds and sector targets for acquisitions
- `pe-os/pe-knowledge-base` — architecture and current state of the Empire Core AI system

**Structure of a Type A SKILL.md:**

```markdown
---
name: stop-slop
description: Remove AI writing patterns from prose.
version: 2.1.0
tags: [writing, style, prose]
trigger: Always apply these rules to all prose output.
---

# Stop-Slop Rules

Never use the following phrases:
- "It's worth noting that..."
- "In conclusion..."
...
```

### Type B — Script-Backed Skills

**The SKILL.md instructs the agent to run a Python script on disk.** The skill is essentially a wrapper that:
1. Tells the agent what script to run
2. Specifies the arguments (usually `--deal-id N` or `--company "Name"`)
3. Describes how to verify success and deliver the output

**Best for:**
- Document generation (LOIs, business plans, reports)
- Data processing (deal screening, CRM operations)
- Any workflow where deterministic, repeatable output matters

**Examples:**
- `pe-os/pe-acquisition-loi` — runs `generate_loi.py`, produces a branded .docx LOI
- `pe-os/deal-screener` — runs `extract.py → analyze → post.py` pipeline
- `productivity/pe-brand` — the master template; other scripts copy from `base_document.py`

**Why script-backed skills are more reliable:**

| Instruction Skills | Script-Backed Skills |
|---|---|
| Agent re-invents the wheel each session | Code is fixed on disk — same result every time |
| Subtle changes in LLM output break formatting | Script output is deterministic |
| Errors are vague ("something went wrong") | Errors are specific Python tracebacks |
| Hard to debug | Easy to test: run the script directly |
| Drift over time as model updates | Immutable until you edit the file |

**Structure of a Type B SKILL.md:**

```markdown
---
name: pe-acquisition-loi
description: Generate a branded Letter of Intent (.docx) for a PE acquisition target.
version: 1.0.0
tags: [pe-os, loi, acquisition, docx]
trigger: LOI, letter of intent, draft LOI, generate LOI
---

# PE Acquisition LOI Skill

## Workflow

1. Identify the target company from the user's message or CRM
2. Run the script:
   ```
   ~/pptxenv/bin/python3 /root/.hermes/skills/pe-os/pe-acquisition-loi/generate_loi.py \
     --deal-id 2
   ```
3. Parse the `SAVED:` line from stdout, verify file size > 30KB
4. Deliver: `MEDIA:/root/.hermes/plans/loi_CompanyName_2026.docx`
```

---

## 5. How to Build a New Script-Backed Skill (Step by Step)

### Step 1: Create the Directory

```bash
mkdir -p /root/.hermes/skills/pe-os/my-new-skill
```

Use the appropriate category. Current categories: `pe-os`, `productivity`, `creative`, `software-development`, `research`, `mlops`, `github`, `apple`, `media`, `data-science`, `slack`, `airtable`, `email`, `gaming`, `devops`, `mcp`, `note-taking`, `leisure`, `smart-home`, `social-media`, `legal`, `autonomous-ai-agents`, `red-teaming`, `configuration`.

For PE-OS work, always use `pe-os`. For general productivity tools, use `productivity`.

### Step 2: Write the Python Generator Script

**Always use `~/pptxenv/bin/python3`** for any work involving `.docx` files. The standard `python3` does not have `python-docx` installed.

**Copy helpers from the pe-brand template:**

```bash
# Read the master template before writing your script
cat /root/.hermes/skills/productivity/pe-brand/templates/base_document.py
```

The `base_document.py` file contains helper functions like:
- `add_header_bar(doc, title, subtitle)` — branded header with gold accent bar
- `add_section_header(doc, text)` — section divider with visual styling
- `set_cell_bg(cell, hex_color)` — set table cell background (use hex string without `#`)
- `sf(r, g, b)` — convert RGB tuple to a shared font color object

**Script template pattern:**

```python
#!/usr/bin/env python3
"""
my_generator.py — Generates [document type] for [purpose]
Usage: ~/pptxenv/bin/python3 my_generator.py --deal-id 2
       ~/pptxenv/bin/python3 my_generator.py --company "Acme Corp"
"""
import argparse, sys, os
sys.path.insert(0, '/root/.hermes/skills/productivity/pe-brand/templates')
from base_document import *   # imports add_header_bar, add_section_header, sf, set_cell_bg, etc.

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('--deal-id', type=int)
    parser.add_argument('--company', type=str)
    args = parser.parse_args()
    
    # ... build the document ...
    
    output_path = f'/root/.hermes/plans/my_document_{company_name}_{year}.docx'
    doc.save(output_path)
    size = os.path.getsize(output_path)
    print(f'SAVED: {output_path} ({size:,} bytes)')

if __name__ == '__main__':
    main()
```

**Test the script directly before writing the SKILL.md:**

```bash
~/pptxenv/bin/python3 /root/.hermes/skills/pe-os/my-new-skill/generate_X.py --deal-id 2
```

**Quality targets:**
- Script runs in < 5 seconds
- Output file > 30 KB (a good multi-page .docx)
- Prints `SAVED: /path/to/file.docx (X bytes)` to stdout — agent parses this line

### Step 3: Write the SKILL.md

Create `/root/.hermes/skills/pe-os/my-new-skill/SKILL.md`:

```markdown
---
name: my-new-skill
description: >-
  Generates [document] for [purpose]. Use when user asks for [trigger phrase].
version: 1.0.0
tags: [pe-os, document-type, relevant-tag]
trigger: trigger phrase, alternate phrase, keyword
---

# My New Skill

[One paragraph explaining what this skill does and when it applies.]

## Trigger Conditions

Load and execute this skill when the user's message contains **ANY** of the following:
- `trigger phrase`
- `alternate phrase`
- `relevant keyword`

## Workflow

**Step 1: Identify the target**
- Check the user's message for a company name or deal ID
- If unclear, query the CRM: `SELECT id, target_name FROM deals WHERE status='Active'`

**Step 2: Run the script**
```bash
~/pptxenv/bin/python3 /root/.hermes/skills/pe-os/my-new-skill/generate_X.py --deal-id N
```
Or by company name:
```bash
~/pptxenv/bin/python3 /root/.hermes/skills/pe-os/my-new-skill/generate_X.py --company "CompanyName"
```

**Step 3: Verify the output**
- Parse the `SAVED:` line from stdout to get the file path
- Check file exists and size > 30 KB: `ls -la /path/to/file.docx`
- If size < 30 KB, the script failed silently — re-run with debug output

**Step 4: Deliver**
Output on its own bare line:
```
MEDIA:/root/.hermes/plans/my_document_CompanyName_2026.docx
```
Then say: "Here's your [document type]." Do not say "download" or "link."

## Hard Rules

- NEVER write document content by hand — always run the script
- NEVER delegate to a subagent (subagents write to isolated filesystems — files will not survive)
- Max 2 retries if the script errors — if it fails twice with the same error, stop and report it
- File delivery MUST use the `MEDIA:` prefix on its own bare line
```

### Step 4: Add Routing to SOUL.md

Edit `/root/.hermes/SOUL.md` and add a routing section in the `## Task Routing` block. Insert it BEFORE "CRM Queries" (which is the catch-all for deal questions):

```markdown
### My New Document — PRIORITY LEVEL [N]
If ANY message contains "trigger phrase", "alternate phrase", or "keyword":
1. Call skill_view(name="my-new-skill") and follow it exactly.
2. The script at /root/.hermes/skills/pe-os/my-new-skill/generate_X.py does all the work — run it with --deal-id N or --company "Name".
3. Parse the SAVED: line from stdout, verify file size > 30KB, then deliver with MEDIA:/path/to/file.docx on its own bare line.
4. Never write content by hand. Never delegate to a subagent. The file must stay on local disk.
```

**Current routing order (highest to lowest priority):**
1. Deal Screening → LOI Generation → Business Plan → [Your New Skill Here] → CRM Queries

### Step 5: Test in Hermes Slack

1. Say the trigger phrase in Slack: `"Create a [your document] for Acme Corp"`
2. Confirm Hermes loads the skill (it will say something like "Loading skill...")
3. Confirm the document is delivered (file appears in Slack thread)
4. Confirm the file opens correctly in Word/Pages

**If it fails at Step 2 (script error):** Run the script manually in terminal and fix the Python error. Re-test.

**If it fails at delivery (no file in Slack):** Verify the `MEDIA:` line is correct and the file path is absolute. Check that `HERMES_SESSION_CHAT_ID` and `HERMES_SESSION_THREAD_ID` are set.

---

## 6. Key Technical Rules

Breaking these rules causes failures — some silent, some cryptic. Memorize these.

### Python Environment

| Rule | Correct | Wrong |
|---|---|---|
| Python env for docx work | `~/pptxenv/bin/python3` | `python3` (no python-docx installed) |
| Python env for system scripts | `python3` is fine | — |

### Helper Function Calling

| Rule | Correct | Wrong |
|---|---|---|
| Call standalone helpers | `add_header_bar(doc, "Title", "Sub")` | `doc.add_header_bar(...)` |
| Call set_cell_bg | `set_cell_bg(cell, 'C8A84B')` | `set_cell_bg(cell, '#C8A84B')` |

### Color Argument Types

| Function | Accepts | Example |
|---|---|---|
| `sf(r, g, b)` (shared font color) | RGB tuple — three integers 0–255 | `sf(200, 168, 75)` |
| `set_cell_bg(cell, hex)` | Hex string WITHOUT `#` | `set_cell_bg(cell, 'C8A84B')` |
| Do NOT mix these | Passing hex to `sf()` causes a crash | Passing tuple to `set_cell_bg()` causes a crash |

### File Delivery

| Rule | Correct | Wrong |
|---|---|---|
| Deliver a document | `MEDIA:/absolute/path/file.docx` on its own bare line | Any other method (write_file, inline, etc.) |
| Path must be absolute | `/root/.hermes/plans/file.docx` | `~/plans/file.docx` or relative path |
| Never say "download" | "Here's your document." | "Here's a link to download your document." |

### Document Creation

| Rule | Correct | Wrong |
|---|---|---|
| Create a .docx | `doc.save('/path/to/file.docx')` inside a Python script | Using `write_file` tool |
| Output path | `/root/.hermes/plans/` (the plans directory) | `/tmp/` (gets cleaned up) |
| Run script | `execute_code` or `terminal` tool | Never re-write the script inline |

### Delegation and Subagents

| Rule | Correct | Wrong |
|---|---|---|
| Document generation | Agent runs script directly | Delegating to a subagent |
| Why not subagent | Subagents write to isolated filesystems — files don't survive back | — |
| When to delegate | Only for pure research/analysis tasks that don't produce files | — |

### Error Handling

| Rule | Correct | Wrong |
|---|---|---|
| Script retry limit | Max 2 retries on the same error | Looping indefinitely |
| On repeated failure | Stop and report the specific error | Keep retrying or give up silently |
| On script fix | Fix only the specific broken line | Rewriting the whole script |

### Document Assembly Module (DEPRECATED)

```
❌ DO NOT USE: /root/.hermes/skills/productivity/pe-brand/templates/document_assembly.py
✅ USE INSTEAD: /root/.hermes/skills/productivity/pe-brand/templates/base_document.py
```

`document_assembly.py` is deprecated. `base_document.py` is self-contained and has all helpers.

---

## 7. Key File Locations

### Core System Files

| What | Path |
|---|---|
| All skills | `/root/.hermes/skills/` |
| Agent soul/routing | `/root/.hermes/SOUL.md` |
| Agent config (model, system prompt) | `/root/.hermes/config.yaml` |
| CRM database | `/root/.hermes/crm.db` |
| Agent memories | `/root/.hermes/memories/` |

### Document Generation

| What | Path |
|---|---|
| Pe-brand master template | `/root/.hermes/skills/productivity/pe-brand/templates/base_document.py` |
| Pe-brand deprecated template | `/root/.hermes/skills/productivity/pe-brand/templates/document_assembly.py` |
| Generated documents output | `/root/.hermes/plans/` |
| Temp build scripts | `/tmp/build_doc.py` (cleaned up between sessions) |

### PE-OS Skills

| What | Path |
|---|---|
| Deal screener skill | `/root/.hermes/skills/pe-os/deal-screener/SKILL.md` |
| Deal screener extractor | `/root/.hermes/skills/pe-os/deal-screener/extract.py` |
| Deal screener Slack poster | `/root/.hermes/skills/pe-os/deal-screener/post.py` |
| Deal screener CRM saver | `/root/.hermes/skills/pe-os/deal-screener/save_pipeline.py` |
| LOI skill | `/root/.hermes/skills/pe-os/pe-acquisition-loi/SKILL.md` |
| LOI generator | `/root/.hermes/skills/pe-os/pe-acquisition-loi/generate_loi.py` |
| Investment thesis | `/root/.hermes/skills/pe-os/pe-investment-thesis/SKILL.md` |
| Buy box criteria | `/root/.hermes/skills/pe-os/pe-buy-box/SKILL.md` |
| 100-day playbook | `/root/.hermes/skills/pe-os/pe-100-day-playbook/SKILL.md` |
| Stop-slop rules | `/root/.hermes/skills/creative/stop-slop/SKILL.md` |

### Dashboard

| What | Path |
|---|---|
| Dashboard public files | `/root/hermes-dashboard/public/` |
| Dashboard HTML | `/root/hermes-dashboard/public/index.html` |
| Dashboard JS | `/root/hermes-dashboard/public/app.js` |
| Dashboard server | `/root/hermes-dashboard/server.js` |
| This playbook | `/root/hermes-dashboard/public/SKILL_PLAYBOOK.md` |

---

## 8. Routing Priority in SOUL.md

Skills are routed top-to-bottom in the `## Task Routing` section of `/root/.hermes/SOUL.md`. The first matching rule wins.

### Current Priority Order

| Priority | Skill | Trigger Phrases |
|---|---|---|
| 1 (Highest) | Deal Screening | `screen`, `screening`, `protocol`, `analyze this deal`, deal PDF/CIM/teaser attached |
| 2 | LOI Generation | `LOI`, `letter of intent`, `draft LOI`, `generate LOI`, `create LOI`, `prepare acquisition documents` |
| 3 | Documents (General) | Any `.docx`, report, brief, plan, showcase request |
| — (catch-all) | CRM Queries | Any question about deals, acquisitions, pipeline, investors, operators, contacts |

### How to Insert a New Skill

1. Open `/root/.hermes/SOUL.md`
2. Find the `### CRM Queries — MANDATORY FIRST STEP` section
3. Insert your new routing section **directly above** CRM Queries (unless it needs higher priority than LOI)
4. Use this template:

```markdown
### [Your Skill Name] — PRIORITY [N]
If ANY message contains "[trigger1]", "[trigger2]", or "[trigger3]":
1. Call skill_view(name="your-skill-name") and follow it exactly.
2. The script at /root/.hermes/skills/[category]/[skill-name]/generate_X.py does all the work.
3. Parse the SAVED: line, verify file size > 30KB, deliver with MEDIA:/path on its own bare line.
4. Never write content by hand. Never delegate. File must stay on local disk.
```

### Why Order Matters

If "CRM Queries" appears before your skill, any message containing a deal company name will get routed to a CRM lookup instead of your skill. Always put specific skills above the generic catch-alls.

---

## 9. Active Skills Reference Table

> This table reflects the skills directory as of the playbook creation date. Run the command below to regenerate it.

```bash
find /root/.hermes/skills -name "SKILL.md" | grep -v "_deleted" | sort | while read f; do
  dir=$(dirname "$f")
  name=$(basename "$dir")
  parent=$(basename "$(dirname "$dir")")
  trigger=$(grep "^trigger:" "$f" 2>/dev/null | head -1 | sed 's/trigger: *//')
  echo "| \`$parent/$name\` | $trigger |"
done
```

### PE-OS Skills (Core Acquisition Workflow)

| Skill Path | Trigger / Use Case |
|---|---|
| `pe-os/deal-screener` | Screen inbound deal from Slack thread (PDF, CIM, teaser) |
| `pe-os/pe-acquisition-loi` | `LOI`, `letter of intent`, `draft LOI`, `generate LOI` |
| `pe-os/pe-investment-thesis` | Load for firm's investment philosophy and market thesis |
| `pe-os/pe-buy-box` | Load for exact financial thresholds and sector targets |
| `pe-os/pe-100-day-playbook` | Post-acquisition integration playbook — 5-phase framework |
| `pe-os/pe-knowledge-base` | Architecture of the Empire Core AI system |
| `pe-os/slack-blockkit` | Build rich Slack messages using Block Kit for deal screens |

### Productivity Skills

| Skill Path | Trigger / Use Case |
|---|---|
| `productivity/pe-brand` | Load whenever building any .docx — master design system |
| `productivity/docx-document-creation` | General .docx creation workflow |
| `productivity/powerpoint` | Any .pptx file — creation, editing, generation |
| `productivity/google-workspace` | Gmail, Calendar, Drive, Sheets, Docs via Python |
| `productivity/notion` | Notion API — pages, databases, blocks |
| `productivity/linear` | Linear issues, projects, teams via GraphQL |
| `productivity/nano-pdf` | Edit PDFs with natural-language instructions |
| `productivity/ocr-and-documents` | Extract text from PDFs and scanned documents |
| `productivity/slack-output-delivery` | How to deliver documents/reports in Slack |

### Creative Skills

| Skill Path | Trigger / Use Case |
|---|---|
| `creative/stop-slop` | Always active — removes AI writing patterns from all prose |
| `creative/excalidraw` | Hand-drawn diagrams in Excalidraw JSON format |
| `creative/manim-video` | Mathematical/technical animations using Manim |
| `creative/ascii-art` | ASCII art using pyfiglet, cowsay, boxes, toilet |
| `creative/ascii-video` | ASCII art video pipeline |
| `creative/popular-web-designs` | 54 production design systems extracted from real sites |
| `creative/songwriting-and-ai-music` | Songwriting, Suno prompts, parody/adaptation |

### Software Development Skills

| Skill Path | Trigger / Use Case |
|---|---|
| `software-development/systematic-debugging` | Any bug, test failure, or unexpected behavior |
| `software-development/test-driven-development` | Before writing any implementation code |
| `software-development/subagent-driven-development` | Execute plans with independent parallel tasks |
| `software-development/plan` | Inspect context, write markdown plan into active workdir |
| `software-development/writing-plans` | Create comprehensive plans from specs/requirements |
| `software-development/requesting-code-review` | Pre-commit verification pipeline |

### MLOps Skills

| Skill Path | Trigger / Use Case |
|---|---|
| `mlops/training/axolotl` | Fine-tune LLMs with Axolotl |
| `mlops/training/unsloth` | Fast fine-tuning — 2-5x faster, 50-80% less VRAM |
| `mlops/training/trl-fine-tuning` | SFT/RL fine-tuning with TRL |
| `mlops/training/grpo-rl-training` | GRPO/RL fine-tuning for reasoning |
| `mlops/inference/vllm` | High-throughput LLM serving with PagedAttention |
| `mlops/inference/llama-cpp` | CPU/Apple Silicon/consumer GPU inference |
| `mlops/inference/gguf` | GGUF quantization with llama.cpp |
| `mlops/models/stable-diffusion` | Text-to-image generation |
| `mlops/models/whisper` | Speech recognition, 99 languages |
| `mlops/huggingface-hub` | Search, download, upload models and datasets |
| `mlops/cloud/modal` | Serverless GPU cloud for ML workloads |

### Research Skills

| Skill Path | Trigger / Use Case |
|---|---|
| `research/arxiv` | Search and retrieve academic papers |
| `research/polymarket` | Prediction market data and prices |
| `research/blogwatcher` | Monitor blogs and RSS/Atom feeds |
| `research/research-paper-writing` | End-to-end ML/AI research paper pipeline |

### GitHub Skills

| Skill Path | Trigger / Use Case |
|---|---|
| `github/github-pr-workflow` | Full PR lifecycle — create, monitor, merge |
| `github/github-issues` | Create, manage, triage GitHub issues |
| `github/github-code-review` | Review code changes, inline comments on PRs |
| `github/github-repo-management` | Clone, create, fork, configure repos |
| `github/codebase-inspection` | LOC counting, language breakdown, code analysis |

### Autonomous AI Agents Skills

| Skill Path | Trigger / Use Case |
|---|---|
| `autonomous-ai-agents/hermes-agent` | Guide to using and extending Hermes itself |
| `autonomous-ai-agents/codex` | Delegate coding tasks to OpenAI Codex CLI |
| `autonomous-ai-agents/opencode` | Delegate coding tasks to OpenCode CLI |

### Apple / macOS Skills

| Skill Path | Trigger / Use Case |
|---|---|
| `apple/imessage` | Send/receive iMessages via imsg CLI |
| `apple/apple-notes` | Manage Apple Notes via memo CLI |
| `apple/apple-reminders` | Manage Apple Reminders via remindctl CLI |
| `apple/findmy` | Track Apple devices/AirTags via FindMy |

### Media Skills

| Skill Path | Trigger / Use Case |
|---|---|
| `media/youtube-content` | Fetch YouTube transcripts, structured summaries |
| `media/yt-dlp-downloader` | Download audio/video from YouTube and 1000+ sites |
| `media/gif-search` | Search and download GIFs from Tenor |
| `media/songsee` | Spectrograms and audio feature visualizations |

### Other Skills

| Skill Path | Trigger / Use Case |
|---|---|
| `airtable/airtable-rest-api` | Read/write Airtable via REST API |
| `airtable/airtable-interface-extensions` | Build Airtable Interface Extensions (React) |
| `email/himalaya` | Manage emails via IMAP/SMTP with himalaya CLI |
| `slack/slack-report-posting` | Generate and post reports to Slack from PDFs |
| `note-taking/obsidian` | Read, search, create notes in Obsidian vault |
| `smart-home/openhue` | Control Philips Hue lights via OpenHue CLI |
| `social-media/xitter` | Interact with X/Twitter via x-cli |
| `data-science/jupyter-live-kernel` | Stateful Python execution via Jupyter kernel |
| `devops/webhook-subscriptions` | Create/manage webhook subscriptions |
| `mcp/native-mcp` | Connect to external MCP servers |
| `legal/loi-creation-for-acquisition` | LOI generation (legacy — prefer `pe-acquisition-loi`) |

---

## 10. Modifying Existing Skills

### Editing a Skill's Instructions

Changes to `SKILL.md` take effect **immediately** — no restart required. The agent reads the file fresh each time `skill_view` is called.

```bash
# Edit the SKILL.md directly
nano /root/.hermes/skills/pe-os/pe-acquisition-loi/SKILL.md
# Or via editor of your choice — changes are live instantly
```

### Updating a Generator Script

1. Edit the `.py` file directly
2. Re-test manually before telling anyone it's fixed:
   ```bash
   ~/pptxenv/bin/python3 /root/.hermes/skills/pe-os/pe-acquisition-loi/generate_loi.py --deal-id 2
   ```
3. Verify `SAVED:` line appears and file is > 30 KB
4. Bump the `version:` in the SKILL.md to track the change

### Adding a New Trigger Phrase

Add it in **two places** — both must match:

1. **SKILL.md frontmatter:**
   ```yaml
   trigger: LOI, letter of intent, draft LOI, generate LOI, new phrase
   ```

2. **SOUL.md routing section:**
   ```markdown
   If ANY message contains "LOI", "letter of intent", "draft LOI", "generate LOI", "new phrase":
   ```

If you only add it in one place, the routing will be inconsistent.

### Deprecating a Skill

1. Add a deprecation notice at the top of the SKILL.md body:
   ```markdown
   > **DEPRECATED** — Use `pe-os/pe-acquisition-loi` instead. This skill is no longer maintained.
   ```
2. Remove or comment out its routing section in SOUL.md
3. Do NOT delete the folder — it serves as documentation of what was tried

### Versioning

Increment the `version:` field in SKILL.md whenever you make a meaningful change:
- Patch (`1.0.0` → `1.0.1`): Fix a bug, correct a path, clarify an instruction
- Minor (`1.0.0` → `1.1.0`): Add new functionality, new trigger phrases
- Major (`1.0.0` → `2.0.0`): Rewrite the workflow, change the script architecture

### Testing a Modified Skill

After any change:
1. Run the script manually if it's script-backed
2. Trigger via Slack with a test message
3. Verify the output matches expectations
4. If it breaks something, `git diff` (if the skills folder is tracked) or restore from backup

---

## Quick Reference Card

### "I need to build a new document type"

```
1. mkdir -p /root/.hermes/skills/pe-os/my-skill
2. Copy base_document.py pattern → write generate_X.py  
3. Test: ~/pptxenv/bin/python3 generate_X.py --deal-id 2
4. Write SKILL.md with frontmatter + 4-step workflow
5. Add routing to SOUL.md (above CRM Queries)
6. Test in Slack with trigger phrase
```

### "Something broke in document generation"

```
1. Run the script directly in terminal first
2. Check: using ~/pptxenv/bin/python3? (not python3)
3. Check: sf() gets RGB tuple, set_cell_bg() gets hex string
4. Check: add_header_bar(doc, ...) not doc.add_header_bar(...)
5. Check: file path is absolute in MEDIA: line
6. Max 2 retries — if same error twice, report it
```

### "I need to add a trigger phrase"

```
1. Edit SKILL.md trigger: field
2. Edit SOUL.md routing section (same section, add the phrase)
3. Both must match — inconsistency causes missed routing
```

### "I want to know what skills exist"

```bash
find /root/.hermes/skills -name "SKILL.md" | grep -v "_deleted" | sort
```

Or use the Hermes dashboard Toolkit tab → Skills panel.

---

*This playbook is a living document. Update it whenever the skill architecture changes.*  
*Last generated from: `/root/.hermes/skills/` directory*