🤖Mechanic Agent Skills
Install Mechanic's task-writing expertise directly into your AI coding tool. The mechanic-task-writer skill teaches your AI assistant how to write production-ready Mechanic tasks with correct subscriptions, preview mode, GraphQL queries, bulk operations, and complete importable JSON output.
What are Agent Skills?
Agent Skills are markdown instruction files that get installed into your AI coding tool's configuration directory. When your AI assistant starts a conversation, it reads these files automatically — giving it specialized knowledge without you having to explain anything or paste instructions.
Think of it like a reference manual that your AI always has open. The mechanic-task-writer skill contains Mechanic's task-writing patterns, conventions, and common pitfalls, so your assistant knows how to produce correct task code from the start.
What the skill provides
When installed, the mechanic-task-writer skill gives your assistant deep knowledge of Mechanic's patterns:
Complete importable JSON task output — not just a Liquid script
Correct async/sync patterns (read with
| shopify, write with{% action %})Preview blocks for every subscribed event topic
GraphQL-first Shopify API usage
Proper webhook ID handling (
admin_graphql_api_id)Bulk operation patterns with
__typenameand__parentIdTwo-pass workflows via
mechanic/actions/performCase-insensitive tag comparison
Task options with correct suffixes
Requirements
Node.js 18 or higher installed on your system.
An AI coding tool that supports Agent Skills, such as Claude Code, Cursor, Codex CLI, or Gemini CLI.
Install the skill
Step 1: Run the install command
Open your terminal and run:
The CLI is interactive — it will walk you through a few prompts:
Select agents. The CLI shows a list of AI tools. Tools in the "Universal" group (Cursor, Codex, Gemini CLI, etc.) are always included. If your tool is under "Additional agents" (like Claude Code), use the arrow keys to find it and press space to select it, then enter to confirm.
Choose scope. Select Project (installs to your current directory) or Global (available in all projects).
Choose install method. Select Symlink (recommended — single source, easy updates) or Copy (independent copy).
The CLI will then place the skill file in the correct directory for each selected tool.
You can also install all skills from the package by omitting the --skill flag:
Step 2: Verify the install
In Claude Code, type /skills to see your installed skills. You should see mechanic-task-writer listed.
The /skills command requires the native Claude Code build. If you installed Claude Code via npm, run claude install first to switch to the native version.
You can also check the file directly:
If you installed at the project level, check .claude/skills/ in your project directory instead.
Check that the skill file exists:
You should see a mechanic-task-writer file or directory. If you installed at the project level, check .agents/skills/ in your project directory instead.
In Codex, type $skill to see available skills. You should see $mechanic-task-writer listed.
You can also check the file directly:
Check that the skill file exists:
The skill may also be in ~/.agents/skills/.
If the CLI doesn't detect your tool, you can copy the skill file manually from the GitHub repository. Download the SKILL.md file and place it in your tool's skills directory.
Step 3: Restart your tool
Close and reopen your AI coding tool. Skills are loaded when a session starts, so you need to restart for the new skill to take effect.
Using the skill
Once installed, the skill works automatically. You can use it in two ways:
Just ask naturally. Say something like "help me build a Mechanic task that auto-tags orders over $100" and your assistant will use the skill's patterns automatically.
Use a slash command. In Claude Code, type
/mechanic-task-writerto explicitly invoke the skill. In Codex, use$mechanic-task-writer.
Your assistant will produce complete, importable task JSON with correct subscriptions, preview blocks, and GraphQL queries.
Troubleshooting
The command ran but nothing happened. Check that Node.js 18+ is installed (node --version). The npx skills add command needs Node to run.
I don't see my tool in the agent list. Look under "Additional agents" — not all tools are in the universal group. Use the arrow keys to scroll down, then press space to select your tool.
The skill file isn't in the expected directory. The CLI places files based on which agents you selected during the interactive prompts. If it didn't detect your tool, use the manual install tab above.
Claude Code says /skills is not a command. You're on the npm version of Claude Code. Run claude install to switch to the native build, which supports /skills.
My AI assistant doesn't seem to know Mechanic patterns. Make sure you restarted your tool after installing. Skills are loaded at session start. Also verify the file exists in the correct directory using the verification step above.
I want to update the skill. Run the same install command again — it will overwrite the existing file with the latest version.
Using with the MCP server
For the best results, use Agent Skills together with the Mechanic MCP Server. The MCP server gives your AI assistant access to the task library and documentation at query time, while Agent Skills provide the patterns and conventions for writing correct task code. Together, they cover both reference and execution.
Related resources
Mechanic MCP Server — connect your AI to the task library and docs
Using AI with Mechanic — overview of all Mechanic AI tools
Task library — browse 350+ pre-built automation tasks
GitHub: mechanic-skills — source repository
skills.sh — Agent Skills directory
Last updated
Was this helpful?