Usage · Skills

Skills, at three levels.

A skill is a folder with a SKILL.md file — instructions, and optionally scripts or reference files, that an agent loads only when a task calls for it. DayMug keeps no skills in its database: the Claude and Codex CLIs find them on disk. Where you put the folder decides who gets it — everyone on an AI account, every agent you own, or a single agent.

Persona or skill?

The agent's Role definition (Settings → Agents → edit agent → Role & persona) is sent with every turn: who the agent is, how it talks, what it cares about. A skill is a playbook for one kind of job, pulled in only when needed — so it can be long without costing tokens on every reply. Agents used to have a separate free-text Skills box; it is gone, see below.

What a skill looks like

One directory per skill. The directory name and the name field should match; the description is what the agent reads to decide when to use it, so say plainly what it does and when.

layout

skills/
└── release-notes/
    ├── SKILL.md          # required
    ├── template.md       # optional: files SKILL.md refers to
    └── scripts/
        └── changelog.sh  # optional: scripts the agent may run

SKILL.md

---
name: release-notes
description: Write release notes from the git log. Use for release notes or a changelog.
---

1. Run scripts/changelog.sh to list commits since the last tag.
2. Group them as Added / Changed / Fixed, following template.md.
3. Leave out merge commits and anything touching only tests.

The three levels

Skills from every level are offered together, so give them distinct names. The directory depends on the provider type of the account a conversation runs on: claude and claude-compatible accounts use the Claude layout, codex and openai-compatible the Codex layout.

Level	Who gets it	Claude accounts	Codex accounts
AI account	Every conversation on that provider account, for every user bound to it	`<credential dir>/skills/`	`<credential dir>/skills/`
User	Every agent you own	`<your home>/.claude/skills/`	`<your home>/.agents/skills/` (inside one git repository only)
Agent	That agent's conversations	`<agent work dir>/.claude/skills/`	`<agent work dir>/.agents/skills/`

AI account level

For skills everyone on the account should have — conventions, internal tools, house style. Admins only: the folder lives in the account's credential directory, the one set on Settings → Administration → Providers & models (see Add an account). DayMug hands that directory to the CLI as CLAUDE_CONFIG_DIR or CODEX_HOME, and both CLIs read skills/ inside it.

Find the credential directory Open the account on the Providers page. A claude account with the field left empty uses the service user's ~/.claude.

Create the skill there, as the user DayMug runs as

mkdir -p ~/.daymug/accounts/team-claude/skills/release-notes
$EDITOR ~/.daymug/accounts/team-claude/skills/release-notes/SKILL.md

Start a new conversation Every user bound to the account gets the skill, on every agent. Bound to several accounts? Put a copy in each one that should have it.

Shared means shared

Everyone on the account can read these files — the sandbox keeps the credential directory reachable so the CLI can log in. Keep secrets out of account-level skills; pass them as environment variables instead.

User level

For your own habits, across all your agents. Your home is the work directory your DayMug user was given — by default ~/.daymug/users/<username> (Users and admins). Every agent you create lives inside it, and the CLIs look for skills in the directories above the one a conversation runs in.

Claude — create <your home>/.claude/skills/<name>/SKILL.md. Claude walks up from the conversation's directory and picks up every .claude/skills it passes.
Codex — create <your home>/.agents/skills/<name>/SKILL.md. Codex only walks up to the root of the git repository the conversation is in, so this works when your home is the repository root (git init in it) and the agent directories below it are not repositories of their own. Otherwise use the agent level.

With the sandbox on

A jailed conversation sees only its own working directory (Sandbox), so skills in your home above it are out of reach. If your admin runs the sandbox and has not exempted you, use the agent level — or ask for an account-level skill.

Agent level

For what one agent needs — a project's build and release steps, a report format. The folder goes in the agent's working directory (Settings → Agents → edit agent → Working directory). If that directory is a git repository, commit .claude/skills with the project and everyone who clones it gets the same skills.

in the agent's working directory

mkdir -p .claude/skills/release-notes
$EDITOR .claude/skills/release-notes/SKILL.md

# the same skills for Codex accounts, without a second copy
mkdir -p .agents && ln -s ../.claude/skills .agents/skills

No shell on the server? Ask the agent. It can write inside its own working directory even in the sandbox: “Create a skill in .claude/skills/release-notes that writes release notes from the git log: …”. Codex accounts also ship a built-in skill-creator skill for exactly this.

Check what an agent sees

Start a new conversation and ask: “List the names of every skill available to you.” A skill missing from the answer is in the wrong directory, out of the sandbox's reach, or has a SKILL.md without the name / description header.

Coming from the old Skills field?

Earlier versions had a free-text Skills box next to the role definition (“Go, Python, TypeScript”). It only added a line to the prompt — the same thing the persona does — so it was removed. On upgrade DayMug appends whatever it held to the agent's role definition under a ## Skills heading, so nothing the agent was told is lost. Open Role & persona to tidy it up, and move any step-by-step know-how into a real skill.