How to Write an AI Agent Skill File That Reduces Guesswork

A prompt can tell an agent what to do once. A skill file can document how a team handles that class of work repeatedly.

For developers, the distinction matters. An agent may have repository access and the right tools, yet still has to make decisions about scope, references, validation, and failure handling. If those decisions are undefined, a technically valid result can still be the wrong result.

This guide builds a small, generic skill for reviewing API changes. The point is not to prescribe one universal Agent Skills format. It is to show how to turn vague intent into an executable workflow.

Skill discovery, instruction loading, and tool use vary by model, agent runtime, system instructions, and available tools. Treat the structure below as a portable design pattern, then adapt it to your platform.

The problem with a reasonable instruction

Consider this prompt:

Review this API and make sure it follows best practices.

It sounds clear, but the agent still has to decide:

• Which API contract is authoritative?
• Does the review include authentication and permissions?
• Should it modify code or only produce a report?
• Which tests should it run?
• What should it do when information is missing?
• What does a completed review contain?

Different models may fill those gaps differently. The result can be reasonable without matching the workflow you intended.

Prompt versus skill

I use this distinction:

• A prompt says, “Do this task now.”
• A skill says, “This is how we handle this type of task.”

A useful skill does not make a model magically smarter. It makes the operating boundaries visible.

At minimum, it should define:

1. Trigger: when the skill applies
2. Goal: what outcome it should produce
3. Scope: what is included and excluded
4. Workflow: steps the agent can follow
5. References: information to read under specific conditions
6. Constraints: actions and claims that are prohibited
7. Uncertainty handling: what to do when evidence is missing
8. Completion criteria: how to validate the result

A practical directory structure

Start with one file while the workflow is small. Split it when references, examples, or reusable scripts become large enough to distract from the main instructions.

api-review-skill/
├── SKILL.md
├── references/
│   ├── api-contract.md
│   ├── security-rules.md
│   ├── output-examples.md
│   └── troubleshooting.md
├── scripts/
│   └── validate.sh
└── assets/
    └── review-template.md

The exact file names and supported directories depend on the platform and runtime. More importantly, models may not select or load these files in the same way. The main file should therefore explain why and when each reference matters.

A generic SKILL.md example

---
name: api-change-review
description: "Review API changes for contract compatibility,"
  security boundaries, and required validation. Use when an
  endpoint, request schema, response schema, authentication,
  or permission behavior changes.
---

# API Change Review

## Goal

Produce a review report that identifies contract-breaking changes,
security-sensitive changes, missing validation, and unresolved assumptions.

## Scope

Review the proposed change and related tests.
Do not modify implementation files unless the user requests edits.

## Workflow

1. Read the changed files and the API contract.
2. Identify changes to endpoints, fields, status codes, and behavior.
3. If authentication, secrets, or permissions are involved,
   read the security rules.
4. Compare the tests with the changed behavior.
5. Produce the required report.
6. Run the validation command when the environment supports it.

## Reference routing

- Read `references/api-contract.md` for endpoint or schema changes.
- Read `references/security-rules.md` for authentication,
  secrets, or permission changes.
- Read `references/output-examples.md` only when the report format
  is unclear.
- Read `references/troubleshooting.md` when validation fails.

## Constraints

- Do not invent endpoints, fields, metrics, or test results.
- Do not expose credentials, customer data, or internal URLs.
- Do not present an unimplemented requirement as released behavior.
- Flag assumptions that require human review.

## Required output

1. Summary
2. Contract-breaking changes
3. Security-sensitive changes
4. Missing or affected tests
5. Assumptions requiring review
6. Validation performed

## Completion criteria

- Every changed behavior is mapped to the contract.
- Security-sensitive changes are explicitly identified.
- Validation results state what was and was not run.
- Unresolved assumptions are visible.

This example is intentionally generic. It demonstrates an instruction contract, not a claim about one platform's required syntax.

Before and after

Before

Review this API and make sure it follows best practices.

After

Review the API change using the api-change-review skill.

Use `references/api-contract.md` as the contract source.
If the change touches authentication, secrets, or permissions,
also apply `references/security-rules.md`.

Produce the required review report. Do not modify implementation files.
State which validation commands were run and flag unresolved assumptions.

The second instruction is not better because it is longer. It is better because fewer operational decisions are left undefined.

Turn the index into a routing table

A file list tells an agent what exists. A routing table explains when a file becomes relevant.

Reference	Read when	Skip when
api-contract.md	An endpoint, schema, status code, or behavior changes	The task does not involve an API contract
security-rules.md	Authentication, secrets, roles, or permissions are involved	The task has no security-sensitive behavior
output-examples.md	The required report shape is unclear	The output contract is already explicit
troubleshooting.md	Validation cannot run or fails	Validation succeeds normally

This table is guidance, not an enforcement mechanism. Actual reference selection still depends on the model, runtime, context strategy, and tools.

Single file or multiple files?

Keep the skill in one file when:

• it has one short workflow
• all constraints fit without hiding the main steps
• examples are small
• no reusable scripts are needed

Split the skill when:

• references are long or domain-specific
• several workflows share the same rules
• examples make the main file difficult to scan
• validation scripts are reusable
• sensitive rules require separate ownership or review

The main file should remain enough to answer two questions: What should the agent do, and where should it look next?

Treat skills like software

A skill can contain instructions, references, and executable code. Review an external skill before using it, especially when it can access files, call a network service, or run scripts.

Check for:

• file access outside the expected scope
• network and API destinations
• hardcoded credentials
• destructive file operations
• hidden instructions that attempt to bypass system rules
• scripts whose behavior has not been reviewed

For organizational use, sandboxing and coexistence tests may also be appropriate. Different models can respond to the same instruction or tool surface differently.

Validation checklist

- [ ] The description states when the skill should trigger.
- [ ] The goal and scope are explicit.
- [ ] The workflow contains observable steps.
- [ ] Each reference has a condition for when to read it.
- [ ] Prohibited actions and claims are listed.
- [ ] Missing information has a defined handling rule.
- [ ] The output contract is reusable and testable.
- [ ] Completion criteria can be checked.
- [ ] No secrets or internal URLs are embedded.
- [ ] Executable scripts have been reviewed.
- [ ] The skill was tested on tasks that should trigger it.
- [ ] The skill was tested on tasks that should not trigger it.

Final takeaway

Before handing a skill to an agent, read it as if you were a developer joining the project today:

Can I complete the work from this information? What would I still have to guess? If I must make a decision, do I know which direction to take?

A good skill does not remove reasoning. It removes avoidable guessing.

Read the canonical article on NEXT4I: https://www.next4i.com/dev-notes/en

Comments

[Jo Do]

"A technically valid result can still be the wrong result" is the argument for skill files in one line. The scope decisions are the ones that matter - an agent that cannot ask "how deep do I go" will pick a depth at random and defend it confidently. One addition from experience: a failure-handling section that says what to do when the skill cannot apply beats another paragraph of happy-path procedure.