Skills

Skills are Mogick CLI's core extension mechanism. Each Skill is a Markdown file containing domain knowledge, workflow guidance, and contextual instructions. At startup, the agent scans all configured Skills directories. When a task matches a Skill's description, the agent loads it into the context with skill.load, giving the model specialized guidance for that task.

Skills are designed to be drop-in extensions: no compilation, registration, or service restart is required. Place the .md file in a supported directory and it becomes available the next time Skills are scanned.

Skills directories and precedence

By default, Mogick searches its project, user, and built-in Skills locations.

Location	Scope	Purpose
.mogick/skills/, .agents/skills/	Project and ancestor directories	Project- and workspace-specific Skills
<config-dir>/skills/, ~/.agents/skills/	User	Skills shared across projects
Product built-in path	Product	Skills distributed with Mogick
skills.search_path_extras	Additional paths	Explicitly configured Skills directories

Use project-level Skills for team conventions, project-specific review rules, and deployment workflows. Use user-level Skills for personal conventions and reusable private workflows.

For example, add additional paths explicitly:

{
  "skills": {
    "search_path_extras": ["/absolute/path/to/team-skills"]
  }
}

The default location for new Skills is controlled by skills.create_root ("mogick" or "agents") and skills.create_scope ("project" or "global"). You can also run mogick setup skill to configure these settings interactively.

Skill file format

The filename identifies the Skill, and the agent uses the description field in the YAML frontmatter for semantic matching. A typical Skill looks like this:

---
name: code-review
description: Code review specifications: inspection items, report format and approval process
---

# Code review specifications

1. Check whether the code style conforms to the ESLint configuration
2. Verify type safety to ensure no `any` type escapes
3. Check boundary conditions and error handling
4. Confirm that test coverage has not decreased

In the frontmatter, name is the Skill's unique identifier. It is optional and is inferred from the filename when omitted. The description briefly states when the Skill applies and directly affects matching accuracy. A specific description makes accidental activation on unrelated tasks less likely. The body uses standard Markdown and can contain checklists, code templates, decision trees, or any other instructions that help the agent follow the domain's rules.

Manage Skills

Manage Skills through the filesystem or the TUI. Enter /skills to browse and load available Skills and see their source directories.

To control availability, use the skills.disabled configuration list or the host integration API. The TUI /skills panel is for browsing and loading Skills.

Instructions already loaded into the current context are not replaced automatically during a session. After editing a Skill, reopen the session or reload it through the host's refresh flow. The agent rescans all Skills directories at startup, so new files do not need to be registered manually.

Diagnostics and troubleshooting

When Skills do not behave as expected, use the doctor command to check the system status:

mogick doctor                       # Print a Markdown diagnostic report
mogick doctor --json                # Switch to JSON output
mogick doctor --export ./report.md  # Export the report to a file

By default, doctor renders a Markdown report in the terminal, including the Skills search roots, parsing status, and loaded Skills. Use mogick doctor --export <path> to write the report to a file. If a Skill is not loaded, check its SKILL.md frontmatter, directory permissions, and any paths in skills.search_path_extras.

Skills and MCP

Skills and MCP complement each other: Skills provide the knowledge and workflow for how to perform a task, while MCP provides the tools to perform it. A Skill can tell the agent which MCP tools to call, in what order, and how to handle failures. Built-in Skills include workflows for Syslab and Sysplorer, and custom Skills can reference any connected MCP server.

Path placeholders <config-dir> and <db-path> refer to the effective profile/channel paths; see Data directories.