Sign Up Sign In

Agent skill

The MCP server exposes each tool with its own description, but some knowledge spans tools and so lives in no single one: start a session before touching a primitive, choose a deadline over a schedule when a task has a due date you must not miss, retry creates with an idempotency key, and never write an escalation policy whose channels have nowhere to send. That cross-tool knowledge is packaged as an agent skill — a single SKILL.md file you add to a skill-aware host so your agent picks up the habits automatically.

Why a skill

A capable agent still gets these wrong, because no per-tool description can teach them:

  • It skips the session bootstrap. Without teams_list → set_current_team, the first primitive call comes back no_team_selected and the agent flails at arguments that were never the problem.
  • It reaches for the wrong primitive. A schedule fires and forgets; a deadline has a completion state and is recallable across sessions. Use a schedule where a deadline belongs and a later, memory-less instance can never ask "did this get done?".
  • It retries a create without an idempotency key and ends up with two approval requests, two deadlines, two watches.
  • It writes an escalation policy that notifies no one — a step firing on the email channel with no notify_emails, or webhook with no webhook_url.

The skill states each habit once, in the agent's own operating instructions, so it does the right thing without being told per task.

Install it

The skill is a single Markdown file — SKILL.md at the root of the repo. There is no bundle to build and nothing to compile: one file, with YAML frontmatter (name, description) and the workflow rules below it.

To install it in a skill-aware host such as Claude Code, drop the file into the host's skills directory (for Claude Code, ~/.claude/skills/aigears/SKILL.md, or the project-local .claude/skills/aigears/SKILL.md). Hosts that discover skills by directory will pick it up on the next run; the agent then applies the habits whenever it connects to the AIGears MCP server. For a host without a skills mechanism, paste the file's contents into your system prompt — the same text works either way.

The skill

The canonical text is the repo file, and it is the single source of truth — this page links it rather than pasting a copy that could drift. Read or install it here:

  • SKILL.md — the four cross-tool rules: session bootstrap, primitive selection, idempotency discipline, and the escalation-destination rule.

When this page and the file disagree, the file is right. Its rules mirror the per-primitive guides — Schedules, Deadlines, Approvals, Watches — and the MCP server reference, which those rules assume you have already read.