Build once, run on any agent: A practical guide to agent skills

Agent skills allow you to capture repeatable instructions so that you and your agents can reuse them. These skills are versioned directories centered on a SKILL.md file that describes when and how to do a specific task. You can share these instructions across agents, but the environment still needs to provide the necessary tools, credentials, and permissions to execute them.

A skill works best when it has a clear job, input, and output. For instance, an agent can be built to check AI-generated changes against the original request. However, the agent should not be responsible for evaluating its own work, as its explanation might influence the review. Instead, a separate verifier should be used to examine the changes and provide evidence for its findings.

When building a larger workflow, coordinating multiple skills can help capture parts of judgment held by different people. In the Data Forge example, a manifest discovers project details like source tables and naming conventions, which are then used by other skills to carry out their respective tasks. This approach ensures that each skill has a defined responsibility and shares project context instead of rediscovering it independently.

To maintain portability, keep project configuration out of the skills. Instead, use a manifest to describe project details such as name, store name, and platform. This allows other teams to use the skills with their own manifests without rewriting them. By separating discovered details from team standards, you enable review and confirmation of these details where necessary.

Finally, incorporate checks and approval points in the workflow to ensure that each phase is completed before moving on to the next one. In the Data Forge support-desk workflow, there are seven phases with human checkpoints at each one. By doing so, you can maintain stability, shared state, and audit trails within the workflow.