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
- Rename the default from
~/.ai to ~/ai-artifacts (visible directory, clearer name).
- 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.
- Update all prose references across skills to reflect the new default.
- Relative-path example (example 12): change
.ai to ai-artifacts (no leading dot — it is not a hidden directory).
- 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
Problem
Agents frequently ignore the configured
artifacts.base_dirpreference and default to~/.ai. This causes permission prompts and writes artifacts to the wrong location.Root cause: the
get-session-contextskill 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 readsartifacts.base_dirfrom preferences.Proposed solution
~/.aito~/ai-artifacts(visible directory, clearer name)."{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..aitoai-artifacts(no leading dot — it is not a hidden directory).artifacts.base_dirsetting from~/.agents/preferences.yamlso 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 casespackages/agents/content/skills/_data/artifact-conventions.md— default mention, export destination pathpackages/agents/content/skills/orchestrate/SKILL.md— default fallback mentionpackages/agents/README.md— preferences table default valueAcceptance criteria
~/.aiinpackages/agents/are replaced with~/ai-artifacts"artifact_base_dir"values in worked examples use"{artifact_base_dir}"as a placeholder, not a concrete pathai-artifacts(no leading dot)artifact-conventions.mdreflects the new default