Skip to content

Rename default artifact directory from ~/.ai to ~/ai-artifacts #400

Description

@williamthorsen

Problem

Agents frequently ignore the configured artifacts.base_dir preference and default to ~/.ai. This causes permission prompts and writes artifacts to the wrong location.

Root cause: the get-session-context skill has 12 worked examples, 11 of which show "artifact_base_dir": "/Users/william/.ai". This creates a strong few-shot bias — agents pattern-match the examples rather than executing the resolution logic that reads artifacts.base_dir from preferences.

Proposed solution

  1. Rename the default from ~/.ai to ~/ai-artifacts (visible directory, clearer name).
  2. Replace hardcoded paths in worked examples with the placeholder "{artifact_base_dir}". This forces agents to resolve the value from preferences rather than copying from examples. Do not use varied concrete paths — a single consistent placeholder is clearer.
  3. Update all prose references across skills to reflect the new default.
  4. Relative-path example (example 12): change .ai to ai-artifacts (no leading dot — it is not a hidden directory).
  5. User action: remove the artifacts.base_dir setting from ~/.agents/preferences.yaml so the new default applies automatically.

Files to change

  • packages/agents/content/skills/get-session-context/SKILL.md — default value, manifest schema, 12 worked examples, edge cases
  • packages/agents/content/skills/_data/artifact-conventions.md — default mention, export destination path
  • packages/agents/content/skills/orchestrate/SKILL.md — default fallback mention
  • packages/agents/README.md — preferences table default value

Acceptance criteria

  • All references to ~/.ai in packages/agents/ are replaced with ~/ai-artifacts
  • All "artifact_base_dir" values in worked examples use "{artifact_base_dir}" as a placeholder, not a concrete path
  • The relative-path example (example 12) uses ai-artifacts (no leading dot)
  • Export destination in artifact-conventions.md reflects the new default
  • No functional changes to resolution logic (only the default value and documentation change)

Metadata

Metadata

Labels

refactoringImprovement to code without change in functionalityscope:agents

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions