How to Write Reliable Agent Skills for AI Coding Workflows

A reliable Agent Skill separates discovery from execution. The open format requires a SKILL.md with name and description; agents use that metadata to decide whether a skill is relevant, then load the body and supporting resources after activation. Examples, checklists, and scripts improve execution, but they are authoring practices—not required discovery fields.

Why This Distinction Matters

Teams often put good advice in the wrong part of a skill. They add a long list of “trigger phrases” to the body and assume those phrases help an agent discover the skill. They do not help initial discovery when the runtime has not loaded the body yet.

The solution is not to remove examples or trigger lists. It is to understand their real job:

• Metadata helps discovery.
• The body guides execution after activation.
• Supporting files provide detail only when needed.
• Evaluation tells you whether the whole workflow performs reliably.

That model comes from the Agent Skills specification. The recommendations below come from how we maintain skills in this website repository and in our larger ByblosAI application codebase.

What the Standard Requires

The standard is deliberately small. A skill is a directory containing at least one file:

blog-post/
├── SKILL.md
├── references/        # Optional
│   └── editorial.md
├── scripts/           # Optional
│   └── validate.mjs
└── templates/         # Optional project convention
    └── article.md

The required SKILL.md starts with YAML frontmatter:

---
name: blog-post
description: Create or revise Astro blog posts. Use for articles, tutorials, product updates, and editorial audits.
---

The standard requires name and description. It permits optional metadata and additional files. It does not require a “Trigger Phrases” section, a Before/After example, a particular heading structure, or exactly one file in the directory.

Those distinctions matter during reviews. A missing required field is a compliance defect. A missing example may be a quality opportunity, but it is not a standards violation.

What Agents See During Discovery

Agent Skills use progressive disclosure. At startup, a compatible runtime normally makes the skill’s name and description available. If the task appears relevant, the runtime activates the skill and loads the body. References or scripts can be read later as the workflow needs them.

This means the description carries the initial discovery burden:

# Too vague
description: Helps with content.

# Specific about capability and use
description: Create and revise Astro content-collection blog posts. Use when drafting tutorials, product announcements, or evidence-based editorial updates.

Our recommendation is to write the description in two parts:

1. What the skill does: name the artifact or outcome.
2. When to use it: name realistic tasks and boundaries.

Use natural task vocabulary, but do not turn the description into a keyword dump. Clear scope is more useful than a list of synonyms.

What Belongs in the Skill Body

Once activated, the body should help an agent perform the work without guessing. We usually include the following where they add value.

A Concrete Outcome

State what a successful result looks like:

Produce a valid Astro Markdown post with complete frontmatter, a direct answer in the opening, primary-source support for factual claims, and three relevant internal links.

This is more useful than “write a high-quality post” because it defines observable output.

An Ordered Workflow

Use steps when order affects correctness:

1. Read repository and path-specific instructions.
2. Inspect existing content and reusable patterns.
3. Verify time-sensitive claims against primary sources.
4. Draft or edit the artifact.
5. Run the required validation.
6. Report what was verified and what remains unverified.

Our application repository uses this pattern for feature delivery, plan review, testing, and content work. The benefit is not that every workflow looks identical. The benefit is that high-risk steps—research, authorization, validation, and evidence reporting—are difficult to skip.

Examples That Teach Execution

Examples are valuable after activation because they clarify transformations and edge cases:

Before:
"Our product guarantees perfect code quality."

After:
"Our workflow combines automated checks with human review; production results
still depend on the repository, configuration, and release process."

The example does not make the skill discoverable. It makes the active instructions easier to apply consistently.

Checkable Validation

Turn subjective advice into verifiable criteria:

## Validation

- Confirm every factual capability against current code or primary documentation.
- Run the repository's content and build checks.
- Verify internal links resolve.
- Do not present planned or untested behavior as production evidence.

In our repositories, this evidence boundary is a core convention. Passing unit tests is not the same as proving a browser flow, a provider integration, or a production deployment. A good skill tells the agent which kind of evidence is required.

How We Use Trigger Phrases

Some of our skills contain a Trigger Phrases section. That is our authoring convention, not an Agent Skills requirement.

We keep those lists for two practical reasons:

• They help human maintainers understand the intended scope.
• They provide ready-made prompts for behavioral evaluation.

We do not rely on body-level trigger phrases for initial discovery. If a task must influence selection, its meaning belongs in the description. This correction lets us preserve the useful part of trigger lists without making an inaccurate claim about runtime behavior.

When to Use Supporting Files

The standard explicitly permits scripts, references, assets, and other files. Use them when they keep the main workflow focused.

Our preference is a short entrypoint with direct links to focused resources. We avoid deep chains where one reference sends the agent through several more files before it can act.

A Practical Authoring Workflow

Use this sequence when creating or repairing a skill:

1. Define one coherent job. The skill can have several steps, but they should contribute to one outcome.
2. Write compliant metadata. Validate the directory name, name, and description.
3. Describe the evidence boundary. Say what must be inspected, tested, or approved.
4. Add only useful structure. Steps, examples, tables, and templates should reduce ambiguity.
5. Move detail out when needed. Keep the entrypoint readable and link supporting resources directly.
6. Test realistic prompts. Confirm the expected skill activates and the resulting work follows the procedure.
7. Review maintenance risk. Check paths, commands, versions, and external assumptions.

The specification provides a reference validator through skills-ref. Runtime evaluation is still necessary because format validation cannot prove that an agent will choose or follow a skill well.

A Better Quality Rubric

The following rubric is our recommendation, not part of the standard:

Notice what is not scored as a requirement: a specific set of headings, a mandatory trigger list, or a Before/After example in every skill. Those can be excellent choices when they help the task, but ritual structure is not the goal.

Why This Helps Startup Teams

In a startup, important workflows often live in one founder’s or senior engineer’s head. A well-written skill turns that knowledge into a repeatable procedure without pretending the procedure is automatic enforcement.

For example, a release skill can preserve:

• the checks that must pass;
• the person who approves a high-risk change;
• the environments that need manual verification;
• the rollback information that must be recorded.

That reduces avoidable re-explanation and makes external contributors more effective. It does not remove accountability. The team still owns the decision and the evidence.

Key Takeaways

1. The Agent Skills standard requires SKILL.md, name, and description; supporting files are allowed.
2. Initial discovery uses metadata. Body examples and trigger lists help only after activation or during evaluation.
3. Our preferred skills define outcomes, ordered work, safety boundaries, and proportionate validation.
4. Treat examples and checklists as context-dependent good practice, not universal requirements.
5. Validate format and evaluate behavior; neither one replaces the other.

Frequently Asked Questions

Do trigger phrases make a skill easier to discover?

Only when their meaning is present in discovery metadata or the runtime has another documented indexing mechanism. A trigger list inside the body is normally unavailable before activation. We use trigger lists as maintainer documentation and evaluation prompts.

Can an Agent Skill contain more than one file?

Yes. The specification explicitly allows scripts, references, assets, and additional files. SKILL.md is the required entrypoint, not the only permitted file.

Are examples required?

No. Examples are a good authoring technique when they clarify a transformation, edge case, or format. They improve execution quality after the skill loads, but they are not required frontmatter and do not drive initial discovery.

How should a team test a skill?

First validate the format. Then run realistic tasks, observe whether the expected skill activates, inspect the produced artifact, and record failures. Avoid claiming access to hidden model reasoning; evaluate observable behavior.

Standards and Vendor References

• Agent Skills specification
• GitHub Copilot: adding agent skills
• OpenAI Codex customization and skills
• Claude Code skills

Conclusion

Reliable skills are not built by filling every possible section. They are built by respecting the discovery contract, giving the active agent a clear procedure, and verifying the outcome with evidence.

Our rule is simple: label standards as standards, vendor behavior as vendor behavior, and our own patterns as recommendations grounded in practice. That makes the guidance both more honest and more useful.

Continue the series with the forthcoming article on agent personas, or review the foundations in What Are Agent Skills? and How to Structure .github/ for AI Coding Agents.

Want help turning your team’s recurring workflows into evidence-based skills? Explore ByblosAI or contact us.