Athena Package Creator

Create validated .athena import packages for the Athena note-taking app. These are ZIP archives containing a manifest, markdown notes with aurora tags, and optional assets.

Package Format Overview

package.athena (ZIP) ├── manifest.json # Required: note index with aurora tags ├── notes/ │ ├── project-plan.md # Markdown notes with optional YAML frontmatter │ ├── meeting-notes.md │ └── ... └── assets/ ├── diagram.png # Binary assets referenced from notes └── ...

Read references/athena-spec.md for full schema details when handling unusual configurations.

Creation Workflow

Step 1: Gather Content

Collect all content to package:

• From an athena-work processing session (most common)

• From conversation results the user wants to save

• From uploaded files the user wants to import

• From generated content (research, summaries, analyses)

Step 2: Prepare Notes

For each note, create a markdown file with:

• Slug filename — lowercase, hyphenated, .md extension (e.g., project-plan.md )

• Mandatory header format (see below)

• Optional YAML frontmatter — only title and aurora are parsed; these override manifest values

Place all note files in the notes/ directory.

Mandatory Note Header Format

ALWAYS use this exact structure for every note:

note title

short description

note content here...

• title

— Must match the manifest title for this note

• description — One-line summary of the note's content

— Horizontal rule separator; always present before body content

• Body content follows in standard markdown

Example:

Market Analysis Q1 2026

Competitive landscape analysis covering AI assistant market trends and growth

Overview

The AI assistant market grew 40% year-over-year...

Step 3: Assign Aurora Tags

Every note requires an aurora tag. Use this table for selection:

Aurora Value Use When Examples

commitments

Obligations, promises, deadlines, action items Task lists, deadline trackers, promises made

focus

Deep work, projects needing concentration Project plans, strategy docs, specs

ops

Operations, processes, recurring tasks Runbooks, checklists, SOPs

collab

Collaboration, meetings, shared work Meeting notes, team decisions, feedback

life

Personal, wellbeing, non-work Personal goals, health notes, hobbies

explore

Research, ideas, exploration Research findings, brainstorms, discoveries

archive

Completed/archived items Finished projects, historical records

library

Reference material, resources Guides, documentation, collected resources

Default selection guidance:

• Documentation and guides: library

• Research and analysis: explore

• Actionable items with owners/deadlines: commitments

• Project plans and strategy: focus

• Meeting summaries: collab

Ask the user when the appropriate tag is ambiguous or when notes span multiple categories.

Step 4: Handle Cross-References

Note-to-note links — Use relative paths:

Display Title

Asset references — Use standard markdown image/link syntax:

Download report

Athena's importer remaps these paths to internal UUIDs. References that don't match any file in the package are left unchanged.

Step 5: Build manifest.json

Create the manifest with this structure:

{ "version": 1, "format": "athena", "generatedAt": "<ISO 8601 timestamp>", "source": "claude", "notes": [ { "file": "notes/slug-name.md", "title": "Display Title", "aurora": "focus", "assets": [ { "name": "diagram.png", "file": "assets/diagram.png", "type": "image" } ] } ] }

Required fields: version (must be 1), format (must be "athena" ), notes array (at least one entry), and for each note: file , title , aurora .

Optional fields: generatedAt , source , notes[].assets (may be omitted or empty array).

Step 6: Validate, Fix, and Create

Run the validation-fix-revalidation loop:

• Prepare staging directory — Create a temporary directory with manifest.json , notes/ , and assets/ subdirectories

• Validate — Run the validation script: python3 ${CLAUDE_PLUGIN_ROOT}/skills/athena-package/scripts/validate_athena_package.py <staging-dir>

• Fix issues — If validation reports errors, fix them:

• Missing files: create or remove from manifest

• Invalid aurora tags: correct to valid values

• Header format errors: add/fix # title

• description

• ---

• Cross-reference targets missing: fix paths or remove references

• Revalidate — Run validation again until clean (exit code 0)

• Create package — Run the creation script: python3 ${CLAUDE_PLUGIN_ROOT}/skills/athena-package/scripts/create_athena_package.py <staging-dir> [output-path]

• Deliver — Report the output file path and summary to the user

Validation Feedback Loop

Never skip validation. The .athena format is strict — Athena's importer rejects malformed packages. The validate-fix-revalidate cycle catches issues before the user tries to import.

Common validation errors and fixes:

Error Fix

"manifest.json not found" Create the manifest file

"invalid aurora tag 'X'" Replace with a valid aurora value

"note file 'notes/X.md' not found" Create the file or remove from manifest

"disk file 'notes/X.md' not in manifest" Add to manifest or remove the file

"note missing header format" Add # title\n\n> description\n\n---

"cross-reference target 'notes/X.md' not found" Fix the path or create the target

"asset 'assets/X.png' not found" Add the file or remove the reference

Example

Input: 2 notes from a research session with 1 image asset.

Staging directory:

research-output/ ├── manifest.json ├── notes/ │ ├── executive-summary.md │ └── market-analysis.md └── assets/ └── market-chart.png

manifest.json:

{ "version": 1, "format": "athena", "generatedAt": "2026-02-07T14:30:00Z", "source": "claude", "notes": [ { "file": "notes/executive-summary.md", "title": "Executive Summary", "aurora": "focus", "assets": [] }, { "file": "notes/market-analysis.md", "title": "Market Analysis", "aurora": "explore", "assets": [ { "name": "market-chart.png", "file": "assets/market-chart.png", "type": "image" } ] } ] }

notes/executive-summary.md:

Executive Summary

High-level overview of Q1 2026 strategy findings

Based on our Market Analysis, three key themes emerge...

Key Decisions

1. Prioritize mobile-first experience
2. Launch AI features in March

notes/market-analysis.md:

Market Analysis

Competitive landscape analysis for the AI assistant market

Overview

The AI assistant market grew 40% YoY...

Result: research-output.athena (ZIP, 3 files, ready for import)

Error Handling

Error Recovery

No content to package Ask the user what to include

Validation fails after 3 fix attempts Show remaining errors; ask user for guidance

Script not found Report the issue; manually create the ZIP structure

Python not available Report the issue; manually create the ZIP

Output directory not writable Try current directory; ask user for alternative

Reference Materials

• references/athena-spec.md — Full .athena import format specification: manifest.json schema, required/optional fields, note format with frontmatter override rules, asset handling, cross-reference syntax, aurora tag values, and import behavior (Inbox placement, deduplication, UUID remapping). Read when handling unusual package configurations or debugging import failures.