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](notes/other-note.md)

Asset references — Use standard markdown image/link syntax:

![Alt text](assets/filename.ext)
[Download report](assets/report.pdf)

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](notes/market-analysis.md), 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

![Market Share Chart](assets/market-chart.png)

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.