> ## Documentation Index > Fetch the complete documentation index at: https://docs.ollim.ai/llms.txt > Use this file to discover all available pages before exploring further. # Skills > Create reusable instruction sets that routines, reminders, and webhooks can reference for repeatable workflows. 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//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 **three bundled skills** — `job-config`, `setup`, and `improve-routine` — that live in the bot's source code rather than in `~/.ollim-bot/skills/`. | Skill | Purpose | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `job-config` | Guides tool selection and behavioral configuration when creating background jobs | | `setup` | Walks you through initial bot configuration | | `improve-routine` | Diagnoses and fixes routine quality issues — data source confusion, embellishment propagation, model/tool mismatches, report quality | 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`](/scheduling/background-forks#adding-tools) and which behavioral flags (`allow-ping`, `update-main-session`, `model`) to set — so you don't have to remember the rules yourself. Invoke `/improve-routine routines/.md` when a routine produces wrong results, pings at bad times, or needs structural fixes. It runs a diagnostic pass in plan mode before proposing changes, then spawns critic subagents to verify the fix prevents the reported failure. Not for creating new routines — use the agent conversationally for that. 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//SKILL.md`. The directory name must match the skill's `name` field — lowercase with hyphens. ```yaml title="skills/code-review/SKILL.md" theme={null} --- 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](https://code.claude.com/docs/en/skills). ollim-bot-specific behavior is noted below. | Field | Required | Description | | -------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- | | `name` | No | Slash command name (`/`). Defaults to the directory name | | `description` | Recommended | When the agent should use this skill — used for auto-discovery | | `argument-hint` | No | Autocomplete hint for expected arguments, e.g. `[issue-number]` | | `allowed-tools` | No | Tools allowed without prompts when this skill runs. In scheduled jobs, these tools are also available to the background fork | | `model` | No | Model to use when this skill runs | | `disable-model-invocation` | No | `true` to prevent auto-loading — only invocable with `/` | | `user-invocable` | No | `false` to hide from the `/` menu. Default: `true` | | `context` | No | `fork` to run in an isolated subagent context (interactive use only, not scheduled jobs) | | `agent` | No | Subagent type when `context: fork` — e.g. `Explore`, `general-purpose` | | `hooks` | No | Hooks scoped to this skill's lifecycle — see the [hooks guide](/extending/hooks) | 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 `/ `; `$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. ```markdown title="skills/repo-status/SKILL.md (body)" theme={null} 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 | Rule | Value | | ---------------------- | --------------------------------------------------------------------------------------------------- | | Per-command timeout | 10 seconds | | Total wall-clock cap | 30 seconds across all commands in one expansion | | Max output per command | 2000 characters (truncated with `[...truncated]` if longer) | | Working directory | `~/.ollim-bot/` | | Error handling | Failed commands are replaced with `[command failed (exit N): cmd: error_line]` | | Timed-out commands | Replaced with `[command timed out: cmd]` | | Skipped commands | If 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: ```yaml title="routines/morning-code-review.md" theme={null} --- 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: ```yaml title="webhooks/ci-with-review.md" theme={null} --- 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: ```bash theme={null} 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](/extending/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: | Category | Examples | In system prompt? | | ----------------- | ------------------------------------------------------------------ | --------------------------------------- | | **User-authored** | Skills you create in `~/.ollim-bot/skills/` | Yes — listed under "Your custom skills" | | **Generated** | `routine-*`, `reminder-*`, `webhook-*` (auto-created at fire time) | No | | **Bundled** | `job-config`, `setup`, `improve-routine`, `claude-history` | No | 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: ```bash theme={null} 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 `/` 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 Compare skills with routines, reminders, webhooks, and other extensibility mechanisms. Create recurring jobs that reference skills via the `skills:` frontmatter field. Full YAML frontmatter reference for all markdown data files. How the system prompt is structured and what gets injected.