Assistant Commands & Skills

What the folder does

When the Daintree Assistant is backed by Claude, Codex or Copilot, it runs that CLI in a private session folder that Daintree owns, not in your repository. Every time such a session launches, Daintree copies your custom commands and skills from two source folders into that session folder, and the CLI finds them there through its own native discovery: Claude Code reads .claude/commands and .claude/skills from its working directory, Codex reads .agents/skills.

• Global: ~/.daintree/assistant/ applies to every project.
• Per project: <project>/.daintree/assistant/ applies to that project only and takes precedence over the global folder. It sits in the repository's .daintree/ directory and can be committed, so a team can ship assistant commands with the code.

Commands and skills come from four subtrees of each folder: .claude/commands, .claude/skills, .codex/skills and .agents/skills. A fifth, reference/, holds plain reading material and is copied to the same path for all three of those backends. Files such as instructions.md, mcp.json and hooks.json are read by Daintree itself rather than copied, and are not covered on this page. Nothing else in the folder, including the README Daintree creates there, is copied.

This content is assistant-only. Ordinary agent terminals run in your project or worktree, not in the session folder, so a Claude Code or Codex pane you launch for coding never sees anything under .daintree/assistant. That makes the folder the place for instructions about operating Daintree (triage routines, release checklists, how your team names worktrees) that would only be noise to a coding agent. Daintree never writes to ~/.claude, ~/.codex or any other agent configuration to make this work.

Folder layout

Both source folders use the same layout, built from the agents' own hidden directory names:

~/.daintree/assistant/                  (or <project>/.daintree/assistant/)
  .claude/commands/<name>.md            Claude Code slash commands
  .claude/skills/<name>/SKILL.md        Claude-only skills
  .codex/skills/<name>/SKILL.md         Codex-only skills
  .agents/skills/<name>/SKILL.md        Shared skills, for every backend that takes skills

• Commands are single Markdown files. Any .md file under .claude/commands is copied; other file types are ignored.
• Skills are directories. Each one must contain a file named exactly SKILL.md, conventionally with name and description frontmatter. Everything else in the skill directory (scripts, templates, reference notes) is copied with it. A loose file sitting directly in a skills folder is not a skill and is ignored.
• A skill directory without a SKILL.md is invalid. Daintree logs it, skips it, and does not let it hide anything: if a lower-precedence folder has a valid skill of the same name, that one is still used.

.codex/skills is a Daintree convention rather than a place Codex looks. Daintree delivers those skills through the session's .agents/skills folder, because a .codex folder in the working directory would be treated as project configuration by Codex.

Opening the folder

Open Settings > Daintree Assistant > Custom commands and skills and click Open folder, or run Open assistant commands folder from the command palette. Either creates ~/.daintree/assistant if it is missing, with five empty subfolders (the four above and reference/) and a README describing the layout, then opens it in your file manager. Existing files are never overwritten.

The button opens the global folder only. For a per-project folder, create .daintree/assistant/ at the project root yourself and use the same layout.

What each backend receives

What gets copied depends on the CLI that backs the Assistant. Commands are a Claude Code feature, so only Claude-backed sessions get them; skills reach every backend that reads skills from its working directory.

In the Assistant's input bar, autocomplete reads the session folder, so mirrored content can appear next to the built-in and user-level entries: custom commands and skills on / in a Claude session, skills on $ in a Codex session. The menu caches discovery briefly, so a freshly launched session may take a few seconds to list a new entry.

Precedence

When the same command or skill name exists in more than one place, the later source in this list wins:

1. Global .agents/skills (shared)
2. Global backend-specific tree: .claude/commands and .claude/skills for Claude, .codex/skills for Codex
3. Project .agents/skills (shared)
4. Project backend-specific tree

Two consequences worth knowing. A backend-specific skill overrides a shared skill of the same name, so you can keep one general .agents/skills/review and a Claude-tuned .claude/skills/review beside it. And any project skill beats any global one, even a project shared skill against a global Claude-only skill.

The unit of override differs:

• Commands resolve per file. A project .claude/commands/deploy.md replaces the global file at the same path and leaves the other global commands alone.
• Skills resolve per directory. A winning skill replaces the losing one wholesale, including every supporting file; the two are never merged file by file.

Deleting an override brings back what it was hiding. Remove a project's review skill and the next launch gets the global one again. For Copilot, the shared and Claude trees land in separate folders rather than overriding each other, so which of two same-named skills applies is up to Copilot.

When changes take effect

The copy happens when a session's CLI process starts: the first launch, Restart conversation, a new session tab, switching backend, resuming after hibernation or memory eviction, and relaunching Daintree. Hiding and showing the panel does not restart the process, so it does not pick up changes.

After editing a command or skill, restart the conversation (or open a new session tab) to use it. Removing a file from a source folder removes its copy from the session folder on the next launch, so a deleted skill does not linger. Parallel session tabs share one session folder, so starting a tab also refreshes the files beneath tabs already running: Claude Code can pick up changed skills mid-session, but Codex reads skills only at startup. Restarting the conversation is the reliable way to get a clean set.

A Claude-backed Assistant runs with file-editing tools denied, so asking it to create a command or skill fails. Write commands and skills in your editor or in an ordinary agent terminal, then relaunch the Assistant.

Example: a team release command

A team wants every member's Assistant to draft release notes the same way, and to share one CI triage routine whichever backend each person uses. They commit two files to the repository:

.daintree/assistant/
  .claude/commands/release-notes.md
  .agents/skills/triage-ci/SKILL.md

The command is ordinary Claude Code command Markdown:

---
description: Draft release notes from the commits since the last tag
argument-hint: [version]
---
List the commits between the latest tag and HEAD. Group them into Features,
Fixes and Internal, skip merge commits, and draft release notes for $ARGUMENTS.
Do not push, tag or open anything.

The skill is a directory with a SKILL.md:

---
name: triage-ci
description: Find the failing CI check on the focused worktree's pull request and summarize the cause
---
Read the checks for the focused worktree's pull request. For each failing check,
quote the first real error from its log and name the file it points at.

After pulling, a teammate on Claude relaunches the Assistant and gets /release-notes and /triage-ci. A teammate on Codex gets $triage-ci and no release-notes command, because commands are Claude-only; to reach Codex users too, the team would write release notes as a shared skill instead. A teammate who keeps a personal triage-ci in ~/.daintree/assistant/.agents/skills gets the team's version in this project and their own everywhere else.

Limits and skipped content

The folders are user-controlled trees, so the copy is bounded rather than trusting them:

• 2,000 files and 12 levels deep per subtree walked. Past either limit the extra content is skipped and a warning is logged.
• 5 MB per file. A larger file is skipped, and its previous copy in the session folder is removed. A skill whose SKILL.md is over the limit is invalid as a whole.
• Files and folders whose names start with a dot are skipped, as the CLIs' own scanners do.
• Symbolic links are followed, so you can link a shared skill folder in from elsewhere. Link cycles are detected and stop.
• Two skills whose names differ only by letter case (Review and review) cannot coexist, because case-insensitive disks would merge their folders. On every platform the higher-precedence spelling wins and the other is skipped.

Content that is skipped this way is left out quietly and logged; the Assistant still launches.

Trust and review

A skill is instructions, not permission. Whatever a command or skill tells the Assistant to do with Daintree still goes through the same capability tier, confirmation prompts and audit log as anything you type yourself, and a skill cannot raise the tier. The agent CLI's own permissions are separate. For that reason Daintree strips the hooks and allowed-tools frontmatter keys from commands and skills copied from a project's .daintree/assistant, so a repository cannot register hooks or pre-approve tools. The text of the skill still arrives. Content from your global folder is copied unchanged, so treat it as you would your own agent configuration.

Troubleshooting

When the sync fails

Daintree refuses to start a session whose commands and skills it cannot prove are current. If the copy cannot be reconciled, the Assistant does not launch and the panel shows an Assistant couldn't start banner: "Daintree couldn't load this project's assistant folder, so the session didn't start. Retry, or check the logs if it keeps failing." with Retry and Open logs.

This is deliberately stricter than the skipped-content cases above. A new skill that is invalid, or that Daintree fails to copy into a place where nothing was before, is left out and logged, and the Assistant still launches. Launching with stale content would run instructions you deleted or replaced, so the banner appears when:

• a source folder exists but cannot be read, so Daintree cannot tell which skills should exist;
• a previously copied file that should now be gone cannot be removed from the session folder, or a copy could not be refreshed over an old one;
• Daintree's record of what it copied into the session folder is unreadable or corrupt.

For a permissions problem, fix the folder and press Retry. If Retry keeps failing identically and the log reports outdated copies still present, it names the session folder and those files; remove them, or the session folder itself, and retry. The session folder belongs to Daintree and is rebuilt on the next launch. Only backends that receive content (Claude, Codex, Copilot) can hit this; the Daintree Assistant CLI never does.

Common problems