Skills, Rules & Notes

The skills server loads prompt artifacts from configured directories and exposes them in two ways:

• MCP prompts for user-invocable slash-command style workflows.
• MCP tools for agent-invocable skills and persisted notes.

A single markdown artifact can be a user prompt, an agent skill, a read-triggered rule, or any combination of those surfaces.

Configuration

Aether’s project scaffold wires skills to .aether/skills and .aether/notes:

.aether/mcp.json

{
  "servers": {
    "skills": {
      "type": "in-memory",
      "args": ["--dir", ".aether/skills", "--notes-dir", ".aether/notes"]
    }
  }
}

--dir is repeatable. On name collision, the last directory wins. --notes-dir is required for save_note and search_notes.

Directory shape

Prompt artifacts can be directory-backed SKILL.md files or flat markdown files directly under a configured --dir.

• Directory.aether/

  • Directoryskills/

    • Directoryrust/

      • SKILL.md
      • traits.md
      • error-handling.md
    • commit.md
    • rust-rules.md
  • Directorynotes/

    • coding-style.md

Directory-backed skills can include auxiliary files that agents load on demand with get_skills. Flat markdown prompt files are useful for small prompts or rules and do not support auxiliary relative paths.

Prompt artifact frontmatter

.aether/skills/rust/SKILL.md

---
name: rust
description: Rust conventions for this project
user-invocable: false
agent-invocable: true
tags: [rust, coding]
triggers:
  read:
    - "**/*.rs"
---

Use project-specific Rust conventions.

See `traits.md` and `error-handling.md` for detailed patterns.

Field	Description
name	Optional identifier. Defaults to the directory name for SKILL.md or filename stem for flat .md files.
description	Discovery text. Empty descriptions default to the resolved name.
user-invocable	Exposes the artifact as an MCP prompt. Directory-backed SKILL.md files default to true; flat files default to false.
agent-invocable	Makes the artifact discoverable through list_skills and loadable with get_skills. Defaults to true.
argument-hint	Optional argument hint for user-invocable prompts.
tags	Tags returned by list_skills and saved in note metadata.
triggers.read	Project-relative glob patterns used as read-triggered rules by the coding server.
globs, paths	Compatibility aliases that also feed triggers.read.

Every authored artifact must have at least one activation surface: user-invocable, agent-invocable, triggers.read, globs, or paths.

Tools

Tool	Description
list_skills	Return lightweight metadata for all agent-invocable skills.
get_skills	Load skill content by exact name and optional relative auxiliary path.
save_note	Append a learning to a topic note under the configured notes directory.
search_notes	Search notes by topic substring or exact tag.

Skill discovery

Recommended flow:

1. Call search_notes for prior learnings relevant to the task.
2. Call list_skills to discover available skills.
3. Call get_skills only for the exact skills needed.

get_skills

{
  "requests": [
    { "name": "rust" },
    { "name": "rust", "path": "traits.md" }
  ]
}

Loading a directory-backed SKILL.md returns availableFiles, excluding hidden files and SKILL.md itself. Auxiliary paths must be relative, must not contain .., and must stay inside the skill directory.

User prompts

User-invocable artifacts are exposed through the MCP prompts protocol.

.aether/skills/commit.md

---
description: Generate a commit message for staged changes
user-invocable: true
agent-invocable: false
argument-hint: "[optional context]"
---

Generate a concise commit message for the currently staged git changes.

Context: $ARGUMENTS

$ARGUMENTS and named MCP prompt parameters are substituted when the prompt is requested.

Notes

Notes are markdown files with frontmatter. save_note normalizes the topic to a kebab-case filename, creates the notes directory if needed, appends to existing notes, and merges tags case-insensitively.

save_note

{
  "topic": "Coding Style",
  "content": "- Prefer integration tests with fakes over mocks.",
  "tags": ["testing", "style"]
}

search_notes is case-insensitive. It matches topic substrings and exact tags.

Shell interpolation

Loaded skill files and MCP prompt bodies support Aether prompt shell interpolation such as !`git branch --show-current` . Commands execute relative to the prompt file directory for get_skills, and relative to the workspace root for MCP prompts.