Workspace layout
How skills and assistants are organized inside a Sundial workspace.
A workspace is where you interact with assistants and files. Each workspace has a .sundial/ directory that organizes the skills and assistants used in that workspace, and an AGENTS.md file at the root for user-editable context.
Workspace layout
The .sundial/ directory
Every workspace contains a .sundial/ directory with two subdirectories:
AGENTS.md # User-editable workspace context (at root)
.sundial/
├── skills/ # All skills used by assistants in this workspace
│ ├── web-search/
│ │ └── SKILL.md
│ ├── pdf-to-text/
│ │ └── SKILL.md
│ └── code-review/
│ ├── SKILL.md
│ └── references/
│ └── best-practices.md
└── assistants/ # All assistants
└── lara/
├── ASSISTANT.md
└── BOOTSTRAP.md # Optional: enables bootstrap mode
Skills are installed from the hub (or created locally) into your agent's skills folder (e.g. .claude/skills/, .cursor/skills/). Assistants live in .sundial/assistants/, each defined by an ASSISTANT.md file with optional companion files.
AGENTS.md
The AGENTS.md file lives at the workspace root — not inside .sundial/. It's user-editable: write whatever workspace context you want the agent to know about. Project descriptions, style preferences, team context, coding conventions — anything that helps your assistants work more effectively.
# My Project
A Next.js app for managing customer feedback.
## Style
- Use Tailwind CSS for all styling
- Prefer server components where possible
- Follow existing naming conventions in /components
## Team Context
- API routes are owned by the backend team
- Design system tokens are in /styles/tokens.tsThe file is hidden by default in the workspace file panel. Toggle it visible with the eye icon. Its contents are injected into the system prompt so assistants can use it as context.
AGENTS.md is yours to edit freely. Unlike internal config files, the runtime never overwrites it. Think of it as your instructions to every assistant in the workspace.Linking and detachment
Skills and assistants exist at two levels: global (in your account, on the hub) and workspace-level (copies inside a specific workspace). When you add one from the hub, it starts in a linked state.
Linked state
A linked skill or assistant tracks the global version. When the author publishes a new version, your workspace copy updates automatically.
| Property | Value |
|---|---|
is_linked | true |
source_skill_id | Points to the original global skill |
source_version | e.g. "1.2.0" |
Behavior | Auto-updates when new version is published |
Detachment
If you edit any file in a linked skill or assistant, it permanently detaches. The workspace copy becomes an independent local version and no longer receives updates from the global source.
This is a one-way operation. There is no “re-link” or “reset to global” action. If you want the original version back, remove the skill and re-add it from the hub.
Lineage tracking
Even after detachment, the original source information is preserved. The workspace copy retains source_skill_id / source_assistant_id and source_version metadata. The UI shows provenance like “forked from web-search v1.2.0” on any customized skill.
| Property | After detachment |
|---|---|
is_linked | false (permanent) |
source_skill_id | Still points to original (for lineage display) |
source_version | Version at time of detachment (e.g. "1.2.0") |
Multi-editor workspaces
All human editors in a workspace can edit any assistant or skill. When one person edits a linked item, it detaches for everyone — the workspace copy is shared, so detachment applies to all collaborators.
Adding skills and assistants
You can add skills and assistants to a workspace in several ways:
- From the web app — Browse the hub, click “Add to workspace,” and select which workspace to add it to.
- From the CLI — Run
npx sundial-hub add web-searchinside your project directory. Skills land in the agent's skills folder. - Manually — Create the directory structure under your agent's skills folder (e.g.
.claude/skills/) and add the files yourself.