| title | The Aeon setup skill |
|---|---|
| description | The operator-facing agent skill that sets up, schedules, edits, and debugs your Aeon instance from a chat — what it does, its modes, and how to install it in Claude Code or any agent tool that supports Agent Skills. |
Aeon ships an Agent Skill (SKILL.md) that turns "how do I set up / schedule / fix this?" into a guided chat. It's the fastest way to drive your instance from a chat — you describe what you want in plain language and it runs the right ./aeon commands for you, with the silent-failure traps already baked in.
It's a portable skill, not tied to one product: Claude Code is the primary host (it auto-loads skills from .claude/skills/, so it's zero-install there), but the skill is just a SKILL.md in the open Agent Skills format — it works with Claude Code, Codex, Hermes, or OpenClaw, and any other agent tool that supports skills.
This is not an Aeon skill. The 92 skills under
skills/run unattended on GitHub Actions. This one runs inside your agent session on your machine - it's the operator's assistant for configuring the instance, not something that runs on a schedule. It doesn't appear inaeon.yml, the packs, or the catalog.
You don't have to learn aeon.yml, cron syntax, or the CLI flags. Mention Aeon (or type /aeon) and it picks the right mode:
| Mode | Ask it when you want to… |
|---|---|
| Start | Stand up a brand-new instance and get one real notification on your phone, fast (it sends you to Aeon Connect if you'd rather not use a terminal) |
| Reschedule | Change when a skill runs, its cadence, or what it focuses on ("move the digest to 7am", "weekdays only") |
| Unblock | Figure out why a skill "didn't run" — it walks the ordered checklist (disabled? invalid cron? Actions off? wrong repo?) |
| Chat → skill | Turn something you just did in the agent into a scheduled skill |
| Edit a skill | Change what an existing skill does — a source, a filter, tone, length |
| What to turn on | Pick skills for what you care about, browse packs, install community packs |
| Strategy & voice | Set STRATEGY.md (the north star) and soul/ (the voice every run speaks in) |
It knows the things that silently break an instance — an unquoted per-skill model: override that is silently ignored, gh pointed at the wrong repo, a missing secret — and it verifies as it goes instead of guessing. (The config-side of that knowledge is also enforced continuously by the aeon-doctor skill.)
You need gh authenticated (gh auth login) — the skill drives everything through the GitHub CLI, same as the dashboard.
Every Aeon instance ships this skill at .claude/skills/aeon/. Claude Code auto-loads skills from a project's .claude/skills/, so there's nothing to install:
- Open your Aeon repo folder in Claude Code — the VS Code or JetBrains extension, or the
claudeCLI in that directory. - Type
/aeon(or just mention Aeon /aeon.yml/ "schedule a skill") and answer its questions.
The setup skill also ships as a Claude Code plugin, so you can install it from a marketplace instead of copying files: versioned, and updatable with /plugin update.
/plugin marketplace add aeonfun/aeon
/plugin install aeon@aeon
Then type /aeon in any session and point it at your instance when it asks which repo. Update later with /plugin update aeon@aeon, or remove it with /plugin uninstall aeon@aeon. (The plugin lives in the plugin/ subdirectory of this repo, a self-contained copy of the setup skill, so installing it never pulls in the unattended skills/ catalog.)
The same plugin installs on Codex too - it ships a Codex manifest and a repo-scoped marketplace catalog (.agents/plugins/marketplace.json):
codex plugin marketplace add aeonfun/aeon
codex plugin add aeon@aeon
From version 0.2.0, the plugin also bundles the hosted Aeon Connect MCP connection and a get-started onboarding skill. Sign in with GitHub and choose your agent repo, then ask it to check setup, run a skill, follow a run or read its output. Onboarding names missing keys without reading their values and offers a first heartbeat run. Changes to skills, strategy, soul, packs or instance settings require confirmation. Switching reaches only other Aeon repos you allowed when connecting. See the plugin README.
Prefer to copy files instead of using the plugin? Drop the skill into your personal Claude Code skills directory so /aeon works in every session:
cp -R .claude/skills/aeon ~/.claude/skills/aeonThen open any directory in Claude Code and type /aeon; point it at your instance when it asks which repo.
The skill is a standard SKILL.md (plus a references/ folder). Any agent that supports Agent Skills — Claude Code, Codex, Hermes, OpenClaw, and others — can use it: drop .claude/skills/aeon/ into that tool's skills location. Everything it does is plain gh + ./aeon commands, so nothing about it is Claude-Code-specific beyond where the file is loaded from.
Five front doors, one engine - all of them work on the same repo, aeon.yml and secrets (the hosted MCP server never reads or writes secret values):
- Aeon Connect (www.aeon.fun/connect) - the dashboard, hosted: sign in with GitHub, create your repo, connect a model, pick skills. Nothing to install; best for a first run. See Quick start.
- Hosted MCP (www.aeon.fun/connect/mcp) - drive an existing agent from ChatGPT, Claude, Claude Code or Cursor: add the URL as a connector, sign in with GitHub, then run skills, read output and memory, and edit strategy and soul from the chat. See Hosted or local?.
- Local dashboard (
./aeon→localhost:5555) - the same click-driven UI, run from your clone. - CLI (
./aeon skills …,./aeon secrets …) — scriptable,--json-friendly. See Command line. - This skill (
/aeonin your agent) — conversational; you say what you want, it runs the CLI and confirms the result.
Use whichever fits the moment — the skill is just the CLI with judgment on top.