mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-24 05:41:40 +00:00
docs: deep audit — fix stale config keys, missing commands, and registry drift (#22784)
* docs: deep audit — fix stale config keys, missing commands, and registry drift Cross-checked ~80 high-impact docs pages (getting-started, reference, top-level user-guide, user-guide/features) against the live registries: hermes_cli/commands.py COMMAND_REGISTRY (slash commands) hermes_cli/auth.py PROVIDER_REGISTRY (providers) hermes_cli/config.py DEFAULT_CONFIG (config keys) toolsets.py TOOLSETS (toolsets) tools/registry.py get_all_tool_names() (tools) python -m hermes_cli.main <subcmd> --help (CLI args) reference/ - cli-commands.md: drop duplicate hermes fallback row + duplicate section, add stepfun/lmstudio to --provider enum, expand auth/mcp/curator subcommand lists to match --help output (status/logout/spotify, login, archive/prune/ list-archived). - slash-commands.md: add missing /sessions and /reload-skills entries + correct the cross-platform Notes line. - tools-reference.md: drop bogus '68 tools' headline, drop fictional 'browser-cdp toolset' (these tools live in 'browser' and are runtime-gated), add missing 'kanban' and 'video' toolset sections, fix MCP example to use the real mcp_<server>_<tool> prefix. - toolsets-reference.md: list browser_cdp/browser_dialog inside the 'browser' row, add missing 'kanban' and 'video' toolset rows, drop the stale '38 tools' count for hermes-cli. - profile-commands.md: add missing install/update/info subcommands, document fish completion. - environment-variables.md: dedupe GMI_API_KEY/GMI_BASE_URL rows (kept the one with the correct gmi-serving.com default). - faq.md: Anthropic/Google/OpenAI examples — direct providers exist (not just via OpenRouter), refresh the OpenAI model list. getting-started/ - installation.md: PortableGit (not MinGit) is what the Windows installer fetches; document the 32-bit MinGit fallback. - installation.md / termux.md: installer prefers .[termux-all] then falls back to .[termux]. - nix-setup.md: Python 3.12 (not 3.11), Node.js 22 (not 20); fix invalid 'nix flake update --flake' invocation. - updating.md: 'hermes backup restore --state pre-update' doesn't exist — point at the snapshot/quick-snapshot flow; correct config key 'updates.pre_update_backup' (was 'update.backup'). user-guide/ - configuration.md: api_max_retries default 3 (not 2); display.runtime_footer is the real key (not display.runtime_metadata_footer); checkpoints defaults enabled=false / max_snapshots=20 (not true / 50). - configuring-models.md: 'hermes model list' / 'hermes model set ...' don't exist — hermes model is interactive only. - tui.md: busy_indicator -> tui_status_indicator with values kaomoji|emoji|unicode|ascii (not kawaii|minimal|dots|wings|none). - security.md: SSH backend keys (TERMINAL_SSH_HOST/USER/KEY) live in .env, not config.yaml. - windows-wsl-quickstart.md: there is no 'hermes api' subcommand — the OpenAI-compatible API server runs inside hermes gateway. user-guide/features/ - computer-use.md: approvals.mode (not security.approval_level); fix broken ./browser-use.md link to ./browser.md. - fallback-providers.md: top-level fallback_providers (not model.fallback_providers); the picker is subcommand-based, not modal. - api-server.md: API_SERVER_* are env vars — write to per-profile .env, not 'hermes config set' which targets YAML. - web-search.md: drop web_crawl as a registered tool (it isn't); deep-crawl modes are exposed through web_extract. - kanban.md: failure_limit default is 2, not '~5'. - plugins.md: drop hard-coded '33 providers' count. - honcho.md: fix unclosed quote in echo HONCHO_API_KEY snippet; document that 'hermes honcho' subcommand is gated on memory.provider=honcho; reconcile subcommand list with actual --help output. - memory-providers.md: legacy 'hermes honcho setup' redirect documented. Verified via 'npm run build' — site builds cleanly; broken-link count went from 149 to 146 (no regressions, fixed a few in passing). * docs: round 2 audit fixes + regenerate skill catalogs Follow-up to the previous commit on this branch: Round 2 manual fixes: - quickstart.md: KIMI_CODING_API_KEY mentioned alongside KIMI_API_KEY; voice-mode and ACP install commands rewritten — bare 'pip install ...' doesn't work for curl-installed setups (no pip on PATH, not in repo dir); replaced with 'cd ~/.hermes/hermes-agent && uv pip install -e ".[voice]"'. ACP already ships in [all] so the curl install includes it. - cli.md / configuration.md: 'auxiliary.compression.model' shown as 'google/gemini-3-flash-preview' (the doc's own claimed default); actual default is empty (= use main model). Reworded as 'leave empty (default) or pin a cheap model'. - built-in-plugins.md: added the bundled 'kanban/dashboard' plugin row that was missing from the table. Regenerated skill catalogs: - ran website/scripts/generate-skill-docs.py to refresh all 163 per-skill pages and both reference catalogs (skills-catalog.md, optional-skills-catalog.md). This adds the entries that were genuinely missing — productivity/teams-meeting-pipeline (bundled), optional/finance/* (entire category — 7 skills: 3-statement-model, comps-analysis, dcf-model, excel-author, lbo-model, merger-model, pptx-author), creative/hyperframes, creative/kanban-video-orchestrator, devops/watchers, productivity/shop-app, research/searxng-search, apple/macos-computer-use — and rewrites every other per-skill page from the current SKILL.md. Most diffs are tiny (one line of refreshed metadata). Validation: - 'npm run build' succeeded. - Broken-link count moved 146 -> 155 — the +9 are zh-Hans translation shells that lag every newly-added skill page (pre-existing pattern). No regressions on any en/ page.
This commit is contained in:
Teknium
GitHub
parent
ea2d66ddc0
commit
252d68fd45
181 changed files with 5498 additions and 122 deletions
|
|
@ -0,0 +1,262 @@
|
|||
---
|
||||
title: "Excel Author"
|
||||
sidebar_label: "Excel Author"
|
||||
description: "Build auditable Excel workbooks headless with openpyxl — blue/black/green cell conventions, formulas over hardcodes, named ranges, balance checks, sensitivit..."
|
||||
---
|
||||
|
||||
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
|
||||
|
||||
# Excel Author
|
||||
|
||||
Build auditable Excel workbooks headless with openpyxl — blue/black/green cell conventions, formulas over hardcodes, named ranges, balance checks, sensitivity tables. Use for financial models, audit outputs, reconciliations.
|
||||
|
||||
## Skill metadata
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Source | Optional — install with `hermes skills install official/finance/excel-author` |
|
||||
| Path | `optional-skills/finance/excel-author` |
|
||||
| Version | `1.0.0` |
|
||||
| Author | Anthropic (adapted by Nous Research) |
|
||||
| License | Apache-2.0 |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `excel`, `openpyxl`, `finance`, `spreadsheet`, `modeling` |
|
||||
| Related skills | [`pptx-author`](/docs/user-guide/skills/optional/finance/finance-pptx-author), [`dcf-model`](/docs/user-guide/skills/optional/finance/finance-dcf-model), [`comps-analysis`](/docs/user-guide/skills/optional/finance/finance-comps-analysis), [`lbo-model`](/docs/user-guide/skills/optional/finance/finance-lbo-model), [`3-statement-model`](/docs/user-guide/skills/optional/finance/finance-3-statement-model) |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
:::info
|
||||
The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
|
||||
:::
|
||||
|
||||
# excel-author
|
||||
|
||||
Produce an .xlsx file on disk using `openpyxl`. Follow the banker-grade conventions below so the model is auditable, flexible, and reviewable by someone other than the person who built it.
|
||||
|
||||
Adapted from Anthropic's `xlsx-author` and `audit-xls` skills in the [anthropics/financial-services](https://github.com/anthropics/financial-services) repo. The MCP / Office-JS / Cowork-specific branches of the originals are dropped — this skill assumes headless Python.
|
||||
|
||||
## Output contract
|
||||
|
||||
- Write to `./out/<name>.xlsx`. Create `./out/` if it does not exist.
|
||||
- Return the relative path in your final message so downstream tools can pick it up.
|
||||
- One logical model per file. Do not append to an existing workbook unless explicitly asked.
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
pip install "openpyxl>=3.0"
|
||||
```
|
||||
|
||||
## Core conventions (non-negotiable)
|
||||
|
||||
### Blue / black / green cell color
|
||||
- **Blue** (`Font(color="0000FF")`) — hardcoded input a human entered. Revenue drivers, WACC inputs, terminal growth, market data.
|
||||
- **Black** (default) — formula. Every derived cell is a live Excel formula.
|
||||
- **Green** (`Font(color="006100")`) — link to another sheet or external file.
|
||||
|
||||
A reviewer can then scan the sheet and immediately see what's an assumption vs. what's computed.
|
||||
|
||||
### Formulas over hardcodes
|
||||
Every calculation cell MUST be a formula string, never a number computed in Python and pasted as a value.
|
||||
|
||||
```python
|
||||
# WRONG — silent bug waiting to happen
|
||||
ws["D20"] = revenue_prior_year * (1 + growth)
|
||||
|
||||
# CORRECT — flexes when the user changes the assumption
|
||||
ws["D20"] = "=D19*(1+$B$8)"
|
||||
```
|
||||
|
||||
The only hardcoded numbers permitted:
|
||||
1. Raw historical inputs (actual revenues, reported EBITDA, etc.)
|
||||
2. Assumption drivers the user is meant to flex (growth rates, WACC inputs, terminal g)
|
||||
3. Current market data (share price, debt balance) — with a cell comment documenting source + date
|
||||
|
||||
If you catch yourself computing a value in Python and writing the result, stop.
|
||||
|
||||
### Named ranges for cross-sheet references
|
||||
Use named ranges for any figure referenced from another sheet, a deck, or a memo.
|
||||
|
||||
```python
|
||||
from openpyxl.workbook.defined_name import DefinedName
|
||||
wb.defined_names["WACC"] = DefinedName("WACC", attr_text="Inputs!$C$8")
|
||||
# then elsewhere:
|
||||
calc["D30"] = "=D29/WACC"
|
||||
```
|
||||
|
||||
### Balance checks tab
|
||||
Include a `Checks` tab that ties everything and surfaces TRUE/FALSE:
|
||||
- Balance sheet balances (assets = liabilities + equity)
|
||||
- Cash flow ties to period-over-period cash change on the BS
|
||||
- Sum-of-parts ties to consolidated totals
|
||||
- No rogue hardcodes inside calc ranges
|
||||
|
||||
Example:
|
||||
```python
|
||||
checks = wb.create_sheet("Checks")
|
||||
checks["A2"] = "BS balances"
|
||||
checks["B2"] = "=IS!D20-IS!D21-IS!D22"
|
||||
checks["C2"] = "=ABS(B2)<0.01" # TRUE/FALSE
|
||||
```
|
||||
|
||||
### Cell comments on every hardcoded input
|
||||
Add the comment AS you create the cell, not later.
|
||||
|
||||
```python
|
||||
from openpyxl.comments import Comment
|
||||
ws["C2"] = 1_250_000_000
|
||||
ws["C2"].font = Font(color="0000FF")
|
||||
ws["C2"].comment = Comment("Source: 10-K FY2024, p.47, revenue line", "analyst")
|
||||
```
|
||||
|
||||
Format: `Source: [System/Document], [Date], [Reference], [URL if applicable]`.
|
||||
|
||||
Never defer sourcing. Never write `TODO: add source`.
|
||||
|
||||
## Skeleton: typical financial model
|
||||
|
||||
```python
|
||||
from openpyxl import Workbook
|
||||
from openpyxl.styles import Font, PatternFill, Alignment, Border, Side
|
||||
from openpyxl.comments import Comment
|
||||
from openpyxl.utils import get_column_letter
|
||||
from pathlib import Path
|
||||
|
||||
BLUE = Font(color="0000FF")
|
||||
BLACK = Font(color="000000")
|
||||
GREEN = Font(color="006100")
|
||||
BOLD = Font(bold=True)
|
||||
HEADER_FILL = PatternFill("solid", fgColor="1F4E79")
|
||||
HEADER_FONT = Font(color="FFFFFF", bold=True)
|
||||
|
||||
wb = Workbook()
|
||||
|
||||
# --- Inputs tab ---
|
||||
inp = wb.active
|
||||
inp.title = "Inputs"
|
||||
inp["A1"] = "MARKET DATA & KEY INPUTS"
|
||||
inp["A1"].font = HEADER_FONT
|
||||
inp["A1"].fill = HEADER_FILL
|
||||
inp.merge_cells("A1:C1")
|
||||
|
||||
inp["B3"] = "Revenue FY2024"
|
||||
inp["C3"] = 1_250_000_000
|
||||
inp["C3"].font = BLUE
|
||||
inp["C3"].comment = Comment("Source: 10-K FY2024 p.47", "model")
|
||||
|
||||
inp["B4"] = "Growth Rate"
|
||||
inp["C4"] = 0.12
|
||||
inp["C4"].font = BLUE
|
||||
|
||||
# --- Calc tab ---
|
||||
calc = wb.create_sheet("DCF")
|
||||
calc["B2"] = "Projected Revenue"
|
||||
calc["C2"] = "=Inputs!C3*(1+Inputs!C4)" # formula, black
|
||||
|
||||
# --- Checks tab ---
|
||||
chk = wb.create_sheet("Checks")
|
||||
chk["A2"] = "BS balances"
|
||||
chk["B2"] = "=ABS(BS!D20-BS!D21-BS!D22)<0.01"
|
||||
|
||||
Path("./out").mkdir(exist_ok=True)
|
||||
wb.save("./out/model.xlsx")
|
||||
```
|
||||
|
||||
## Section headers with merged cells
|
||||
|
||||
openpyxl quirk: when you merge, set the value on the top-left cell and style the full range separately.
|
||||
|
||||
```python
|
||||
ws["A7"] = "CASH FLOW PROJECTION"
|
||||
ws["A7"].font = HEADER_FONT
|
||||
ws.merge_cells("A7:H7")
|
||||
for col in range(1, 9): # A..H
|
||||
ws.cell(row=7, column=col).fill = HEADER_FILL
|
||||
```
|
||||
|
||||
## Sensitivity tables
|
||||
|
||||
Build with loops, not hardcoded formulas per cell. Rules:
|
||||
|
||||
- **Odd number of rows/cols** (5×5 or 7×7) — guarantees a true center cell.
|
||||
- **Center cell = base case.** The middle row/col header must equal the model's actual WACC and terminal g so the center output equals the base-case implied share price. That's the sanity check.
|
||||
- **Highlight the center cell** with medium-blue fill (`"BDD7EE"`) and bold.
|
||||
- Populate every cell with a full recalculation formula — never an approximation.
|
||||
|
||||
```python
|
||||
# 5x5 WACC (rows) x terminal growth (cols) sensitivity
|
||||
wacc_axis = [0.08, 0.085, 0.09, 0.095, 0.10] # center row = base 9.0%
|
||||
term_axis = [0.02, 0.025, 0.03, 0.035, 0.04] # center col = base 3.0%
|
||||
|
||||
start_row = 40
|
||||
ws.cell(row=start_row, column=1).value = "Implied Share Price ($)"
|
||||
ws.cell(row=start_row, column=1).font = BOLD
|
||||
|
||||
for j, g in enumerate(term_axis):
|
||||
ws.cell(row=start_row+1, column=2+j).value = g
|
||||
ws.cell(row=start_row+1, column=2+j).font = BLUE
|
||||
|
||||
for i, w in enumerate(wacc_axis):
|
||||
r = start_row + 2 + i
|
||||
ws.cell(row=r, column=1).value = w
|
||||
ws.cell(row=r, column=1).font = BLUE
|
||||
for j, g in enumerate(term_axis):
|
||||
c = 2 + j
|
||||
# Full DCF recalc formula (simplified for illustration).
|
||||
# In a real model this references the full projection block.
|
||||
ws.cell(row=r, column=c).value = (
|
||||
f"=SUMPRODUCT(FCF_range,1/(1+{w})^year_offset) + "
|
||||
f"FCF_terminal*(1+{g})/({w}-{g})/(1+{w})^terminal_year"
|
||||
)
|
||||
|
||||
# Highlight center cell (base case)
|
||||
center = ws.cell(row=start_row+2+len(wacc_axis)//2,
|
||||
column=2+len(term_axis)//2)
|
||||
center.fill = PatternFill("solid", fgColor="BDD7EE")
|
||||
center.font = BOLD
|
||||
```
|
||||
|
||||
## Recalculating before delivery
|
||||
|
||||
openpyxl writes formula strings but does not compute them. Excel recalculates on open, but downstream consumers (auto-check scripts, CI) need computed values.
|
||||
|
||||
Run LibreOffice or a dedicated recalc step before delivery:
|
||||
|
||||
```bash
|
||||
# LibreOffice headless recalc
|
||||
libreoffice --headless --calc --convert-to xlsx ./out/model.xlsx --outdir ./out/
|
||||
```
|
||||
|
||||
Or use a Python recalc helper (see `scripts/recalc.py` in this skill).
|
||||
|
||||
## Model layout planning
|
||||
|
||||
Before writing any formula:
|
||||
1. Define ALL section row positions
|
||||
2. Write ALL headers and labels
|
||||
3. Write ALL section dividers and blank rows
|
||||
4. THEN write formulas using the locked row positions
|
||||
|
||||
This prevents the cascading-formula-breakage pattern where inserting a header row after formulas are written shifts every downstream reference.
|
||||
|
||||
## Verify step-by-step with the user
|
||||
|
||||
For large models (DCFs, 3-statement, LBO), stop and show the user intermediate artifacts before continuing. Catching a wrong margin assumption before you've built downstream sensitivity tables saves an hour.
|
||||
|
||||
Checkpoint pattern:
|
||||
- After Inputs block → show raw inputs, confirm before projecting
|
||||
- After Revenue projections → confirm top line + growth
|
||||
- After FCF build → confirm the full schedule
|
||||
- After WACC → confirm inputs
|
||||
- After valuation → confirm the equity bridge
|
||||
- THEN build sensitivity tables
|
||||
|
||||
## When NOT to use this skill
|
||||
|
||||
- Users in a live Excel session with an Office MCP available — drive their live workbook instead.
|
||||
- Pure tabular data export with no formulas — `csv` or `pandas.to_excel` is simpler.
|
||||
- Dashboards / charts with heavy interactivity — use a real BI tool.
|
||||
|
||||
## Attribution
|
||||
|
||||
Conventions (blue/black/green, formulas-over-hardcodes, named ranges, sensitivity rules) adapted from Anthropic's Claude for Financial Services plugin suite, Apache-2.0 licensed. Original: https://github.com/anthropics/financial-services/tree/main/plugins/vertical-plugins/financial-analysis/skills/xlsx-author
|
||||
Loading…
Add table
Add a link
Reference in a new issue