skill compiler
- Repo stars 494
- Author repo Athena-Public
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @winstonkoh87 · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
Phase 1: Pattern Extraction (Analysis)
Perform private analysis in `<analysis>` tags (not written to files):
Phase 2: Skill Draft Generation
Generate a complete SKILL.md with Athena-standard 5W1H frontmatter:
Phase 3: Integration
Write the skill to `.agent/skills/[name]/SKILL.md` (or `examples/skills/[category]/[name]/SKILL.md` for public) Update skill index with the new entry Update `AGENTS.md` skill table (if context_trigger present) Notify user: "📦 Compiled new skill: `[name]` from this session. Review at [path]."
# Skill Compiler — Solved-to-Skill Automation
> **Source:** Hermes Agent by Nous Research (May 2026)
> **Core Claim:** "It's the only agent with a built-in learning loop — it creates skills from experience."
> **Athena Adaptation:** Hermes does this via Python (`agent/curator.py` + `tools/skill_usage.py`). Athena does it via workflow-level pattern detection + markdown SKILL.md generation.
## The Problem This Solves
Athena currently relies on **manual insight filing** during `/end` sessions. The `[S]` and `[V]` markers in session logs capture learnings, but they remain trapped in session logs — they don't **become** reusable skills automatically.
Hermes solved this: when the agent completes a novel task, it automatically creates a new skill from the solution, so the same problem class never requires re-derivation.
## When to Use
### Automatic Trigger (Post-Task Detection)
After any task completion where **ALL** of the following are true:
1. **Novelty**: The task required a solution path not covered by any existing skill
2. **Complexity**: Task took ≥5 agent turns OR involved ≥3 tool calls
3. **Success**: User confirmed the solution worked (explicit or implicit — no corrections in final 2 turns)
4. **Reusability**: The solution generalizes beyond this specific instance
### Manual Trigger
User says: "compile this into a skill", "save this as a skill", "I want to remember how we did this"
## Execution Flow
### Phase 1: Pattern Extraction (Analysis)
Perform private analysis in `<analysis>` tags (not written to files):
```
<analysis>
1. What was the PROBLEM CLASS? (Not the specific instance)
- e.g., "Pairs trading dashboard with cointegration analysis"
- NOT "Dashboard 4-decimal rounding fix"
2. What was the SOLUTION ARCHITECTURE?
- Key steps in order
- Tools/APIs used
- Decision points and their resolution criteria
3. What were the FAILURE MODES encountered?
- What went wrong initially?
- What heuristics resolved it?
4. What is the REUSE SURFACE?
- When would someone encounter this problem class again?
- What context_trigger keywords would match?
5. OVERLAP CHECK
- Which existing skills partially cover this?
- Is this better as a new skill or a subsection of an existing one?
</analysis>
```
### Phase 2: Skill Draft Generation
Generate a complete SKILL.md with Athena-standard 5W1H frontmatter:
```markdown
---
name: [kebab-case-name]
description: "[One-line description of what the skill does]"
vibe: "[One-line emotional hook]"
context_trigger: "[comma-separated trigger keywords]"
auto-invoke: false
model: default
source: "Compiled from session [SESSION_ID] on [DATE]"
compiled_from: "[session log path]"
---
# [Skill Name] — [Subtitle]
> **Compiled**: [DATE] from session [SESSION_ID]
> **Problem Class**: [Description of the general problem this solves]
## When to Use
[Trigger conditions — when should the agent invoke this skill?]
## Solution Architecture
### Step 1: [Phase Name]
[What to do, with specifics]
### Step 2: [Phase Name]
[What to do, with specifics]
## Failure Modes & Mitigations
| Failure | Mitigation |
|---------|------------|
| [What can go wrong] | [How to recover] |
## Validated Patterns
- [V] [Pattern]: [Why it works] | Reapply: [When]
## References
- [Session log](path/to/session/log)
- [Related skill](path/to/related/skill)
```
### Phase 3: Integration
1. **Write** the skill to `.agent/skills/[name]/SKILL.md` (or `examples/skills/[category]/[name]/SKILL.md` for public)
2. **Update** skill index with the new entry
3. **Update** `AGENTS.md` skill table (if context_trigger present)
4. **Notify** user: "📦 Compiled new skill: `[name]` from this session. Review at [path]."
## Curator Integration (Stolen: Hermes `agent/curator.py`)
### Lifecycle States
Compiled skills follow a lifecycle identical to Hermes' curator model:
| State | Criteria | Action |
|-------|----------|--------|
| **active** | Created or used within 30 days | Normal operation |
| **stale** | No invocation for 30+ days | Flag for review at next `/audit` |
| **archived** | No invocation for 90+ days | Move to archive directory |
### Invariants (from Hermes)
- **Never auto-delete** — maximum destructive action is archive
- **Pinned skills are exempt** — manual pin via `pinned: true` in frontmatter
- **Only touch compiled skills** — bundled/manual skills are off-limits
- **Archive is recoverable** — archive directory with successor mapping in README.md
### Umbrella Consolidation Rule (Stolen: Hermes Curator Prompt)
> "A collection of hundreds of narrow skills where each one captures one session's specific bug is a FAILURE of the library — not a feature."
When compiling a new skill, first check if it belongs as a **subsection** of an existing umbrella skill rather than a standalone entry:
1. **PREFIX CLUSTER CHECK**: Does the new skill share a first word or domain keyword with 2+ existing skills?
2. **CLASS-LEVEL CHECK**: Would a maintainer write this as one skill with labeled subsections, or N separate skills?
3. If the answer is "one skill", absorb into the existing umbrella and add a `references/` entry instead.
## Anti-Patterns
- ❌ Compiling trivial tasks (< 5 turns, single tool call)
- ❌ Compiling tasks that are already covered by existing skills
- ❌ Creating overly specific skills tied to one instance (use umbrella pattern instead)
- ❌ Compiling without user confirmation of success
- ❌ One-session-one-skill micro-entries — consolidate into class-level umbrellas
## Hermes Comparison
| Feature | Hermes | Athena |
|---------|--------|--------|
| Skill creation | Automatic (Python `skill_manage`) | Workflow-triggered (this SKILL.md) |
| Skill lifecycle | `curator.py` (7-day review cycle) | `/audit` + archive directory |
| Skill evolution | DSPy + GEPA (self-evolution repo) | Manual via `/steal` + session learnings |
| Skill storage | `~/.hermes/skills/` (SQLite telemetry) | `.agent/skills/` (git-tracked) |
| Consolidation | LLM-driven umbrella-ification pass | Manual during `/audit` |
**Athena advantage**: Skills are version-controlled in git, not SQLite. Every skill change has a commit hash, blame, and diff history. Hermes can't `git blame` a skill edit.
## References
- [Hermes Agent Curator](https://github.com/NousResearch/hermes-agent/blob/main/agent/curator.py) — Source of lifecycle states + umbrella consolidation pattern
- [Hermes Self-Evolution](https://github.com/NousResearch/hermes-agent-self-evolution) — DSPy + GEPA evolutionary optimization (future steal candidate)
Sections and files
Listed in source order.
sections -> The Problem This Solves → When to Use → Automatic Trigger (Post-Task Detection) → Manual Trigger → Execution Flow → Phase 1: Pattern Extraction (Analysis)
terms -> Source · Core Claim · Athena Adaptation · manual insight filing · become · ALL · Novelty · Complexity
files/cmd -> agent/curator.py · tools/skill_usage.py · /end · [S] · [V] · <analysis> · .agent/skills/[name]/SKILL.md · examples/skills/[category]/[name]/SKILL.md
body sha256 -> f9a7d2ff0d5e
The Problem This Solves
Athena currently relies on manual insight filing during
/endsessions. The[S]and[V]markers in session logs capture learnings, but they remain trapped in session logs — they don't become reusable skills automatically. Hermes solved this: when the agent completes a novel task, it automatically creates a new skill from the solution, so the same problem class never requires re-derivation.Automatic Trigger (Post-Task Detection)
After any task completion where ALL of the following are true: Novelty: The task required a solution path not covered by any existing skill Complexity: Task took ≥5 agent turns OR involved ≥3 tool calls Success: User confirmed the solution worked (explicit or implicit — no corrections in final 2 turns) Reusability: The solution generalizes beyond this specific instance
Manual Trigger
User says: "compile this into a skill", "save this as a skill", "I want to remember how we did this"
Phase 1: Pattern Extraction (Analysis)
Perform private analysis in
<analysis>tags (not written to files):Phase 2: Skill Draft Generation
Generate a complete SKILL.md with Athena-standard 5W1H frontmatter: