How I structure skills vs. commands for agent workflows

Skills and commands are two distinct elements that help structure agent workflows effectively. Skills hold the knowledge that the agent needs to perform a specific task, while commands are the one-word entry points that initiate the repeatable steps. By separating these two components, workflows become shorter, more repeatable, and easier to review.

One common issue with starting with one big prompt is that it becomes fragile and difficult to maintain as it grows. Instead, skills should be considered as reusable sets of instructions for a particular job, such as how migrations are done, how auth is handled, or how tests are written. These should be written once and referenced when needed, rather than re-explained in every session.

When writing a skill, there are a few rules to follow. First, each skill should focus on one job. If the job cannot be named in a few words, it should be split into separate skills. Secondly, skills should reference knowledge rather than issuing orders. They should provide the agent with the information needed to perform the task, while the actual actions to be taken are carried out by commands. The skills should also include project facts, billing rules, naming conventions, and files that should never be touched.

Commands, on the other hand, are short one-word entry points that carry intent and point to the knowledge needed to carry out the associated skill. They should be named after the action and not the topic. For example, commands like "plan," "review," and "test" are used to initiate specific steps in the workflow. It's essential to keep commands thin and focused on a single step. If a command contains too much knowledge, it should be moved into a skill, and the command should call the skill to perform its task.

Each role within an organization should be assigned as a specialist with a specific job title, such as tech lead, builder, reviewer, or security auditor. These specialists have their own routing description, ensuring they pick up the right work when needed. A reviewer's job remains consistent regardless of the tool running the workflow.

Workflows are fixed sequences of steps, not improvisational processes. For instance, the tech lead plans the feature, specialists build it in parallel, and then the reviewer, security auditor, and shipper act as gates before the feature is deployed. This predictability allows for a clear review process, focusing on plan and gated results rather than improvised decisions.

To maintain consistency across multiple coding agents, it's crucial to have a single source of truth for all instruction files. AGENTS.md should serve as the primary source, with CLAUDE.md pointing to it, ensuring that updates to the instructions are centralized. AgentKrew takes this idea further by rendering the same kit to various coding agents, such as Claude Code, Codex, and OpenCode, allowing the defined roles and workflows to remain consistent across different tools.

Every workflow should end with a release gate, which performs a series of checks, including type checks, tests, linting, and building. The gate returns either a "ready" or "blocked" response, providing a clear indication of whether the code is ready to be shipped or if there are issues that need to be addressed. This approach ensures that the human reviewer can quickly identify and resolve problems before the code is deployed.

When deciding which piece of the workflow to focus on, it's helpful to ask a specific question to guide the decision-making process. Skills answer the question, "What should the agent know?" while commands answer, "What should it do now?" An agent represents the human teammate who needs to remember specific context, while a workflow outlines the order of steps required to complete a task.

Maintaining these pieces as versioned and validated kits, as AgentKrew does, ensures that the structure remains consistent across different coding agents, ultimately improving the overall workflow efficiency and reliability.