Skip to main content
Routines, reminders, and webhooks that need the same detailed instructions shouldn’t duplicate them. Skills solve this — reusable instruction sets stored as markdown files under ~/.ollim-bot/skills/<name>/SKILL.md. Define a skill once, reference it by name, and every job that uses it gets the same instructions loaded at fire time.

​
How skills work

The bot discovers skills automatically from ~/.ollim-bot/skills/. At startup, it scans for skill directories, reads each SKILL.md, and registers the skill as available. When a routine, reminder, or webhook references skills, the bot loads their instructions and runs them before carrying out the job’s own instructions. Any tools the skill declares in its allowed-tools field are automatically available during execution.
Skills are loaded fresh every time they’re invoked. If you update a skill’s instructions, the next invocation picks up the changes automatically.

​
Bundled skills

The bot ships with two bundled skills — job-config and setup — that live in the bot’s source code rather than in ~/.ollim-bot/skills/. job-config guides tool selection and behavioral configuration when creating background jobs. setup guides initial bot setup and configuration. The bot invokes job-config automatically when you create or edit a routine, reminder, or webhook that needs background config. It determines which tools belong in allowed-tools and which behavioral flags (allow-ping, update-main-session, model) to set — so you don’t have to remember the rules yourself. Bundled skills are always available and don’t need to be created manually. They work the same way as user-created skills but are maintained as part of the bot itself.

​
File format

Each skill lives in its own directory: ~/.ollim-bot/skills/<name>/SKILL.md. The directory name must match the skill’s name field — lowercase with hyphens.
skills/code-review/SKILL.md
---
name: "code-review"
description: "Review code changes for style, correctness, and test coverage."
allowed-tools:
  - "Bash(git *)"
  - "Read(**)"
  - "Glob(**)"
---
Review the staged changes in the repository.

Check for:
- Style violations against the project's conventions
- Logic errors or edge cases
- Missing test coverage for new behavior

Summarize findings as a bulleted list, grouped by file.

​
Frontmatter fields

Skills use the same format as Claude Code skills. ollim-bot-specific behavior is noted below.
FieldRequiredDescription
nameNoSlash command name (/<name>). Defaults to the directory name
descriptionRecommendedWhen the agent should use this skill — used for auto-discovery
argument-hintNoAutocomplete hint for expected arguments, e.g. [issue-number]
allowed-toolsNoTools allowed without prompts when this skill runs. In scheduled jobs, these tools are also available to the background fork
modelNoModel to use when this skill runs
disable-model-invocationNotrue to prevent auto-loading — only invocable with /<name>
user-invocableNofalse to hide from the / menu. Default: true
contextNofork to run in an isolated subagent context (interactive use only, not scheduled jobs)
agentNoSubagent type when context: fork — e.g. Explore, general-purpose
hooksNoHooks scoped to this skill’s lifecycle — see the hooks guide
The markdown body after the closing --- becomes the skill’s instructions — the actual prompt the bot receives when running the skill. String substitutions (only when invoked interactively, not from scheduled jobs): $ARGUMENTS — all arguments passed with /<name> <args>; $ARGUMENTS[N] or $N — argument by 0-based index.
Keep description concise and action-oriented. The bot uses it to decide when a skill is relevant, so it can invoke skills on its own outside of scheduled jobs.

​
Dynamic context injection

Skills sometimes need fresh data at fire time — not hardcoded values. The !`command` syntax embeds shell commands that the bot replaces with the command’s output before running the skill.
skills/repo-status/SKILL.md (body)
Current branch and recent commits:

!`git -C ~/my-project rev-parse --abbrev-ref HEAD`

!`git -C ~/my-project log --oneline -5`

Use this context when reviewing the latest changes.
When the skill loads, the bot replaces each !`command` with the command’s output.

​
Expansion rules

RuleValue
Per-command timeout10 seconds
Total wall-clock cap30 seconds across all commands in one expansion
Max output per command2000 characters (truncated with [...truncated] if longer)
Working directory~/.ollim-bot/
Error handlingFailed commands are replaced with [command failed (exit N): cmd: error_line]
Timed-out commandsReplaced with [command timed out: cmd]
Skipped commandsIf the total 30s cap is reached, remaining commands become [command skipped (total timeout): cmd]
Commands run synchronously and block the skill loading for their duration. Keep commands fast — read-only queries, not long-running processes. The 10-second per-command and 30-second total timeouts are hard caps.

​
Using skills in jobs

Reference skills by name in the skills: array of a routine, reminder, or webhook’s YAML frontmatter:
routines/morning-code-review.md
---
id: "f3a8b1c2"
cron: "0 9 * * 1-5"
description: "Morning code review"
background: true
skills:
  - "code-review"
  - "repo-status"
---
Review any open PRs in the main project repository.
Ping me if anything needs my attention before standup.
When this routine fires, the bot loads both skills and runs them before carrying out the routine’s instructions. Any tools declared in the skills’ allowed-tools fields are automatically available.

​
Webhooks with skills

Webhooks support skills: in the same way — referenced skills are loaded when the webhook fires:
webhooks/ci-with-review.md
---
id: "ci-review"
isolated: true
skills:
  - "code-review"
  - "repo-status"
fields:
  type: object
  required: [repo, status]
  properties:
    repo:
      type: string
    status:
      type: string
      enum: [success, failure]
  additionalProperties: false
---
CI result for {repo}: {status}. If the build failed, review the changes.

​
Reminders with skills

Reminders work the same way. You can also pass skills via the CLI: 
ollim-bot reminder add --delay 60 -m "Check deployment status" \
  --skills repo-status
For chained reminders, skills carry forward through the entire chain automatically — every follow-up link inherits the same skill set.

​
Skill reference validation

When a routine, reminder, or webhook fires, the bot validates that every skill in the skills: array exists in ~/.ollim-bot/skills/. If any referenced skill is missing, execution is blocked entirely — the job is skipped and the bot logs a warning. For routines and reminders, a pending update is also appended so the bot can self-correct on the next interaction. This matches the behavior for missing subagents — the bot refuses to run a job that depends on something that doesn’t exist, rather than running it in a degraded state.
Missing skill references block execution, not just warn. If you rename or delete a skill, update all routines, reminders, and webhooks that reference it.

​
User skills in the system prompt

The bot distinguishes between three categories of skills:
CategoryExamplesIn system prompt?
User-authoredSkills you create in ~/.ollim-bot/skills/Yes — listed under “Your custom skills”
Generatedroutine-*, reminder-*, webhook-* (auto-created at fire time)No
Bundledjob-config, setup, claude-historyNo
User-authored skills are automatically surfaced in the system prompt so the bot knows they exist and can invoke them interactively or reference them when creating jobs. The listing includes each skill’s name and description.

​
Creating skills

You can ask the bot to create skills for you, or create them manually: 
mkdir -p ~/.ollim-bot/skills/my-skill
Then create ~/.ollim-bot/skills/my-skill/SKILL.md with the frontmatter and instructions body. You can also ask the bot to create a skill conversationally:
“Create a skill called ‘deploy-check’ that verifies the production deployment is healthy by checking the status endpoint and recent error logs.”
The bot creates the skill directory and writes the SKILL.md with appropriate frontmatter and instructions. New or modified skills take effect after /clear, /compact, or /restart.

​
Developer reference

The bot scans ~/.ollim-bot/skills/ at startup and registers all valid skills automatically. Each skill’s description field determines when the bot considers invoking it. Interactive skills are invocable via /<name> in Discord. User-authored skills (not generated or bundled) are listed in the system prompt via list_user_skills() in skills.py.For per-job injection (routines, reminders, and webhooks), the scheduler loads the referenced skills into the prompt and grants the background fork permission to use each skill’s tools via BgForkConfig.with_skill_tools(). Content loading, command expansion, and allowed-tools enforcement all happen automatically. At fire time, validate_skill_refs() checks that every referenced skill has a SKILL.md in the skills directory — missing refs block execution.
When a scheduled job references a skill, the skill’s allowed-tools are automatically merged into the background fork’s tool set. The bot handles deduplication — declaring a tool that’s already in the defaults has no effect. Skills can only grant additional tool permissions, not restrict them — if a tool is in the base set, it remains available regardless of skill configuration.
Skills propagate through reminder chains automatically. When a chained reminder schedules a follow-up via follow_up_chain, the same skills carry forward to every link in the chain.

​
Next steps

Extending overview

Compare skills with routines, reminders, webhooks, and other extensibility mechanisms.

Routines

Create recurring jobs that reference skills via the skills: frontmatter field.

File formats

Full YAML frontmatter reference for all markdown data files.

System prompt

How the system prompt is structured and what gets injected.