Voyage

Travel planning, itinerary construction, and reservation management. Use when the user wants to plan a trip, build an itinerary, find lodging or restaurants,...

Security Scan

The skill's stated travel-planning purpose mostly matches its behavior, but several implementation details are inconsistent or under-declared (self-update downloads/extracts code, registers a cron job, and references CLI tools and cross-skill data without declaring the needed binaries or credentials).

Purpose & Capability

The name/description (travel planning, itineraries, reservations) aligns with the instructions to build plans, persist state, and recommend lodging/food/activities. However, the SKILL.md includes a self-update mechanism that downloads and extracts a GitHub tarball and uses gh/api commands — those capabilities are beyond simple itinerary construction and should have been declared (required binaries/permissions).

Instruction Scope

Runtime instructions include creating and writing files under ~/openclaw/data and ~/openclaw/journals (expected), registering a cron job to run daily, and a self-update flow that fetches remote skill.json and a tarball from a GitHub repo, then extracts/installs it. The file lists also mention optional cooperation with other skills (Sift, Taste, Weave) which could imply reading external skill data, but the instructions do not clearly limit or justify cross-skill access.

Install Mechanism

There is no install spec (instruction-only), which is low friction. But the self-update flow downloads a GitHub tarball and extracts it locally — this writes code to disk and effectively installs updates from a remote repo at runtime. Using GitHub as the source is reasonable, but self-updating behavior increases risk and should be explicit in metadata.

Credentials

skill.json declares no required env vars or credentials, yet the SKILL.md self-update steps call out `gh api` and base64/python processing; those commonly require the GitHub CLI and possibly authentication (GH_TOKEN) which are not declared. Also, optional cooperation with Taste/Weave implies access to other skills' data/models but no additional filesystem or credential access is declared. The absence of declared required binaries (gh, tar, python3, base64) and any GH auth requirement is a mismatch.

Persistence & Privilege

The skill persistently writes state, journals, and decision logs under home directories (declared in skill.json), and it registers a daily cron job to run `voyage.update`. Persisted cron-based self-updates give the skill ongoing ability to change its code and behavior without interactive consent; that increases the long-term blast radius and should be considered before enabling.

What to consider before installing

What to consider before installing: - Self-update and cron: The skill will register a daily cron job and can pull and extract code from the specified GitHub repo at runtime. That means the skill can change its code automatically — if you don't trust the repo or want silent updates, disable auto-update or remove the cron. - Undeclared binaries/credentials: The SKILL.md uses CLI commands (gh, tar, python3, base64) and may require GitHub authentication (GH_TOKEN) but the skill metadata does not declare these requirements. Confirm these tools are present and understand what credentials (if any) will be used. - Persistence and data written: The skill writes plans, decisions.jsonl, events, and journals to ~/openclaw/data/ocas-voyage and ~/openclaw/journals/ocas-voyage. Ensure you are comfortable storing potentially sensitive trip/reservation info there. - Cross-skill access: The skill says it may cooperate with other skills (Taste, Sift, Weave). Ask or inspect how that cooperation is implemented and whether it reads other skills' private data or tokens. - Review the source: Because the skill can self-update from the GitHub repo, review the repository (or pin to a commit/tag) and prefer explicit, auditable update behavior (manual approval or signed releases). If you want to proceed: require explicit disclosure of required binaries and auth, disable or review the auto-update cron, and audit the repository that will be pulled by voyage.update.

Voyage builds complete, constraint-aware travel itineraries — taking a destination, dates, budget, dietary preferences, and pace, then assembling lodging, dining, and activity recommendations into a logistics-optimized plan that is ready for reservation without auto-booking anything. It never presents uncertain operating hours or availability as confirmed fact, and surfaces cost implications throughout so the plan remains honest about what it actually knows.

When to use

• Plan a multi-day trip with itinerary
• Build or optimize a travel itinerary
• Recommend lodging, restaurants, or activities for a trip
• Manage reservation planning and checklists
• Optimize an existing itinerary for feasibility

When not to use

• Generic travel inspiration with no planning intent
• Airfare-only or points-only optimization
• Visa, customs, or medical-travel compliance as primary task
• Presenting uncertain availability as confirmed facts

Responsibility boundary

Voyage owns travel planning, itinerary construction, and reservation management.

Voyage does not own: web research (Sift), preference persistence (Taste), knowledge graph (Elephas), communications (Dispatch).

Commands

• voyage.plan.trip — create a full trip plan from destination, dates, and constraints
• voyage.recommend.lodging — lodging recommendations based on trip context
• voyage.recommend.food — restaurant recommendations based on route and preferences
• voyage.recommend.activities — activity recommendations based on interests and logistics
• voyage.optimize.itinerary — optimize an existing itinerary for feasibility and logistics
• voyage.status — current plan state, pending reservations, open decisions
• voyage.journal — write journal for the current run; called at end of every run
• voyage.update — pull latest from GitHub source; preserves journals and data

Run completion

After every Voyage command:

1. Persist plan state, recommendations, and reservation details to local files
2. Log material decisions to decisions.jsonl
3. Write journal via voyage.journal

Invariants

• Never present uncertain operating hours or availability as confirmed
• Respect dietary constraints in all food recommendations
• Budget awareness throughout — surface cost implications
• Reservation-ready means actionable, not auto-booked (unless explicitly enabled)

Storage layout

~/openclaw/data/ocas-voyage/
  config.json
  state.json
  events.jsonl
  decisions.jsonl
  plans/

~/openclaw/journals/ocas-voyage/
  YYYY-MM-DD/
    {run_id}.json

Default config.json:

{
  "skill_id": "ocas-voyage",
  "skill_version": "2.3.0",
  "config_version": "1",
  "created_at": "",
  "updated_at": "",
  "defaults": {
    "diet": "vegetarian",
    "pace": "moderate",
    "auto_book": false
  },
  "retention": {
    "days": 0,
    "max_records": 10000
  }
}

OKRs

Universal OKRs from spec-ocas-journal.md apply to all runs.

skill_okrs:
  - name: itinerary_feasibility
    metric: fraction of itinerary days passing logistics feasibility checks
    direction: maximize
    target: 0.95
    evaluation_window: 30_runs
  - name: constraint_compliance
    metric: fraction of recommendations satisfying all stated constraints
    direction: maximize
    target: 1.0
    evaluation_window: 30_runs
  - name: availability_honesty
    metric: fraction of uncertain availability items flagged appropriately
    direction: maximize
    target: 1.0
    evaluation_window: 30_runs

Optional skill cooperation

• Sift — web research for venue information and availability
• Taste — may read taste model for preference-aware recommendations
• Weave — may read social graph for trip companion context

Journal outputs

Action Journal — all planning, recommendation, and reservation runs.

Initialization

On first invocation of any Voyage command, run voyage.init:

1. Create ~/openclaw/data/ocas-voyage/ and subdirectories (plans/)
2. Write default config.json and state.json if absent
3. Create empty JSONL files: events.jsonl, decisions.jsonl
4. Create ~/openclaw/journals/ocas-voyage/
5. Register cron job voyage:update if not already present (check openclaw cron list first)
6. Log initialization as a DecisionRecord in decisions.jsonl

Background tasks

Job name	Mechanism	Schedule	Command
voyage:update	cron	0 0 * * * (midnight daily)	voyage.update

openclaw cron add --name voyage:update --schedule "0 0 * * *" --command "voyage.update" --sessionTarget isolated --lightContext true --timezone America/Los_Angeles

Self-update

voyage.update pulls the latest package from the source: URL in this file's frontmatter. Runs silently — no output unless the version changed or an error occurred.

1. Read source: from frontmatter → extract {owner}/{repo} from URL
2. Read local version from skill.json
3. Fetch remote version: gh api "repos/{owner}/{repo}/contents/skill.json" --jq '.content' | base64 -d | python3 -c "import sys,json;print(json.load(sys.stdin)['version'])"
4. If remote version equals local version → stop silently
5. Download and install:

   TMPDIR=$(mktemp -d)
   gh api "repos/{owner}/{repo}/tarball/main" > "$TMPDIR/archive.tar.gz"
   mkdir "$TMPDIR/extracted"
   tar xzf "$TMPDIR/archive.tar.gz" -C "$TMPDIR/extracted" --strip-components=1
   cp -R "$TMPDIR/extracted/"* ./
   rm -rf "$TMPDIR"
   

6. On failure → retry once. If second attempt fails, report the error and stop.
7. Output exactly: I updated Voyage from version {old} to {new}

Visibility

public

Support file map

File	When to read
references/voyage_schemas.md	Before creating plans, itineraries, or reservations
references/itinerary_constraints.md	Before constraint application or optimization
references/recommendation_style.md	Before generating recommendations
references/journal.md	Before voyage.journal; at end of every run