mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-14 04:02:26 +00:00
db22efbe88
Extends the Windows-gating work to the optional-skills/ tree. Every
SKILL.md that previously omitted the platforms: field now carries an
explicit declaration, which Hermes's loader (agent.skill_utils.
skill_matches_platform) honors to skip-load on incompatible OSes.
58 skills declared cross-platform (platforms: [linux, macos, windows]):
autonomous-ai-agents/blackbox, autonomous-ai-agents/honcho
blockchain/base, blockchain/solana
communication/one-three-one-rule
creative/blender-mcp, creative/concept-diagrams, creative/hyperframes,
creative/kanban-video-orchestrator, creative/meme-generation
devops/cli (inference-sh-cli), devops/docker-management
dogfood/adversarial-ux-test
email/agentmail
finance/3-statement-model, finance/comps-analysis, finance/dcf-model,
finance/excel-author, finance/lbo-model, finance/merger-model,
finance/pptx-author
health/fitness-nutrition, health/neuroskill-bci
mcp/fastmcp, mcp/mcporter
migration/openclaw-migration
mlops/accelerate, mlops/chroma, mlops/clip, mlops/guidance,
mlops/hermes-atropos-environments, mlops/huggingface-tokenizers,
mlops/instructor, mlops/lambda-labs, mlops/llava, mlops/modal,
mlops/peft, mlops/pinecone, mlops/pytorch-lightning, mlops/qdrant,
mlops/saelens, mlops/simpo, mlops/stable-diffusion
productivity/canvas, productivity/shop-app, productivity/shopify,
productivity/siyuan, productivity/telephony
research/domain-intel, research/drug-discovery, research/duckduckgo-search,
research/gitnexus-explorer, research/parallel-cli, research/scrapling
security/1password, security/oss-forensics, security/sherlock
web-development/page-agent
5 skills gated from Windows (platforms: [linux, macos]):
mlops/flash-attention - Flash Attention wheels are Linux-first; Windows
install requires building from source with CUDA
mlops/faiss - faiss-gpu has no Windows wheel; gate rather than
leak partial (faiss-cpu) support
mlops/nemo-curator - NVIDIA NeMo ecosystem has no first-class Windows path
mlops/slime - Megatron+SGLang RL stack is Linux-only in practice
mlops/whisper - openai-whisper + ffmpeg setup on Windows is
non-trivial; gate until Windows install stanza lands
Methodology: scanned every SKILL.md for Windows-hostile signals
(apt-get, brew, systemd, osascript, ptrace, X11 binaries, POSIX-only
Python APIs, Docker POSIX $(pwd) bind-mounts, explicit 'linux-only' /
'macos-only' text). 3 skills flagged as having hard signals on review:
docker-management and qdrant only had POSIX $(pwd) docker examples and
the tools themselves (Docker Desktop, Qdrant) run fine on Windows —
declared ALL. whisper had an apt/brew ffmpeg install path and nothing
else but the openai-whisper Windows install story is rough enough to
warrant gating.
Strict-over-lenient policy: when in doubt, gate. Easier to un-gate after
verified Windows support lands than to leak partial support that
manifests as mid-task failures for Windows users.
104 lines
4.9 KiB
Markdown
104 lines
4.9 KiB
Markdown
---
|
|
name: one-three-one-rule
|
|
description: >
|
|
platforms: [linux, macos, windows]
|
|
Structured decision-making framework for technical proposals and trade-off analysis.
|
|
When the user faces a choice between multiple approaches (architecture decisions,
|
|
tool selection, refactoring strategies, migration paths), this skill produces a
|
|
1-3-1 format: one clear problem statement, three distinct options with pros/cons,
|
|
and one concrete recommendation with definition of done and implementation plan.
|
|
Use when the user asks for a "1-3-1", says "give me options", or needs help
|
|
choosing between competing approaches.
|
|
version: 1.0.0
|
|
author: Willard Moore
|
|
license: MIT
|
|
category: communication
|
|
metadata:
|
|
hermes:
|
|
tags: [communication, decision-making, proposals, trade-offs]
|
|
---
|
|
|
|
# 1-3-1 Communication Rule
|
|
|
|
Structured decision-making format for when a task has multiple viable approaches and the user needs a clear recommendation. Produces a concise problem framing, three options with trade-offs, and an actionable plan for the recommended path.
|
|
|
|
## When to Use
|
|
|
|
- The user explicitly asks for a "1-3-1" response.
|
|
- The user says "give me options" or "what are my choices" for a technical decision.
|
|
- A task has multiple viable approaches with meaningful trade-offs (architecture, tooling, migration strategy).
|
|
- The user needs a proposal they can forward to a team or stakeholder.
|
|
|
|
Do NOT use for simple questions with one obvious answer, debugging sessions, or tasks where the user has already decided on an approach.
|
|
|
|
## Procedure
|
|
|
|
1. **Problem** (one sentence)
|
|
- State the core decision or desired outcome in a single concise sentence.
|
|
- Focus on the *what*, not the *how* — no implementation details, tool names, or specific technologies.
|
|
- Keep it tight. If you need "and", you're describing two problems.
|
|
|
|
2. **Options** (exactly three)
|
|
- Present three distinct, viable approaches labeled A, B, C.
|
|
- Each option gets a brief description, pros, and cons.
|
|
- Options should represent genuinely different strategies, not minor variations of the same approach.
|
|
|
|
3. **Recommendation** (one option)
|
|
- State which option you recommend and why, based on the user's context and priorities.
|
|
- Be direct — this is your professional judgment, not a hedge.
|
|
|
|
4. **Definition of Done**
|
|
- List the specific success criteria for the recommended option.
|
|
- These are concrete, verifiable outcomes — not vague aspirations.
|
|
- If the user picks a different option, revise this section to match.
|
|
|
|
5. **Implementation Plan**
|
|
- Concrete steps to execute the recommended option.
|
|
- Include specific commands, tools, or actions where applicable.
|
|
- If the user picks a different option, revise this section to match.
|
|
|
|
## Verification
|
|
|
|
- Response has exactly one Problem sentence.
|
|
- Response has exactly three Options (A, B, C) with pros and cons for each.
|
|
- Response has a single Recommendation that picks one option with reasoning.
|
|
- Definition of Done and Implementation Plan align with the recommended option.
|
|
- If the user selects a different option, Recommendation, DoD, and Implementation Plan update accordingly.
|
|
|
|
## Example
|
|
|
|
User: "Give me a 1-3-1 for adding retry logic to our API client."
|
|
|
|
Agent:
|
|
|
|
**Problem:** API calls to external services fail intermittently under load and need graceful retry handling.
|
|
|
|
**Options:**
|
|
|
|
- **Option A: Exponential backoff with jitter in a shared utility.**
|
|
Pros: Simple, well-understood pattern; single implementation shared across all callers.
|
|
Cons: No circuit-breaking; callers still block during retries.
|
|
|
|
- **Option B: Retry library (tenacity) as a decorator on each endpoint call.**
|
|
Pros: Configurable per-endpoint; built-in support for circuit breakers and rate limits.
|
|
Cons: Adds a dependency; decorator pattern can obscure control flow.
|
|
|
|
- **Option C: Queue-based async retry with dead letter handling.**
|
|
Pros: Non-blocking; failed calls are tracked and replayable; scales well.
|
|
Cons: Significant complexity increase; requires a queue backend; overkill for low-volume services.
|
|
|
|
**Recommendation:** Option A. The call volume doesn't justify queue infrastructure, and a shared utility with exponential backoff + jitter covers the failure mode cleanly without new dependencies.
|
|
|
|
**Definition of Done:**
|
|
- `api_retry()` utility handles transient HTTP errors (429, 502, 503, 504).
|
|
- Retries up to 3 times with exponential backoff and jitter.
|
|
- All external API calls route through the retry utility.
|
|
- Logs each retry attempt with endpoint and attempt number.
|
|
- Tests cover retry exhaustion, immediate success, and transient-then-success scenarios.
|
|
|
|
**Implementation Plan:**
|
|
1. Create `utils/api_retry.py` with configurable max retries, base delay, and retryable status codes.
|
|
2. Add jitter using `random.uniform(0, base_delay)` to prevent thundering herd.
|
|
3. Wrap existing API calls in `api_client.py` with the retry utility.
|
|
4. Add unit tests mocking HTTP responses for each retry scenario.
|
|
5. Verify under load with a simple stress test against a flaky endpoint mock.
|