How AI Agents Reliably Discover and Load Skills at Runtime

Compatible agents normally discover skills from their name and description, then load the full SKILL.md only after deciding the skill is relevant. Body sections, examples, and scripts guide execution after activation. The exact ranking algorithm is implementation-specific, so teams should evaluate observable activation and output instead of inventing a universal hidden decision process.

What Is Documented—and What Is Not

The Agent Skills specification documents progressive disclosure:

1. Skill metadata is available for discovery.
2. The SKILL.md body loads when the skill activates.
3. Supporting resources load when needed.

OpenAI Codex documents the same high-level behavior: it starts with name and description, loads the body after selection, and reads references or runs scripts as required. GitHub Copilot also requires a description explaining what the skill does and when it should be used.

Those are documented facts.

The vendors do not publish one shared scoring formula that says an exact keyword is worth a particular number of points. Models and runtimes may use semantic matching, explicit invocation, product-specific routing, enabled-skill sets, or other context. Any diagram of the hidden selection process is therefore a teaching model, not a standards guarantee.

The Observable Runtime Model

A useful mental model is:

Task arrives
  ↓
Runtime sees available skill metadata
  ↓
One or more skills appear relevant
  ↓
Runtime activates a skill
  ↓
SKILL.md instructions enter working context
  ↓
References, scripts, or assets load as needed
  ↓
Agent performs work and produces observable output

This model is accurate enough to guide skill design without pretending we can inspect private chain-of-thought or a universal vendor ranking function.

Why the Description Matters Most for Discovery

Consider two descriptions:

description: Helps with testing.

description: Create and update Jest and React Testing Library tests. Use when adding regression coverage, testing components, or repairing failing unit tests.

The second description gives the runtime a clearer capability boundary. It names:

• the outcome: create or update tests;
• the environment: Jest and React Testing Library;
• the situations: coverage, components, and failures.

Our recommendation is to write descriptions for semantic clarity, not exact-string tricks. A user might say “protect this bug from returning” without using the word “test.” A good description explains the underlying capability well enough for that intent to match.

Why Body-Level Triggers Do Not Drive Initial Selection

Suppose the body contains:

## Trigger Phrases

- "add regression coverage"
- "write a unit test"
- "fix the failing test"

If the runtime has not activated the skill, that body content is not yet available through the standard progressive-disclosure model. The list cannot be the initial discovery signal.

We still use trigger lists in some internal skills. For us, they are:

• scope documentation for maintainers;
• a seed set for routing evaluations;
• examples of requests the description should cover.

That is our convention. When a phrase matters for discovery, its meaning must be represented in the description or in another vendor-documented discovery mechanism.

Explicit Invocation Changes the Question

Many runtimes let the user name or invoke a skill explicitly. In that case, selection is no longer purely implicit.

For example:

Use the blog-post skill to revise this article.

The runtime can activate the named skill directly, subject to availability and product behavior. Explicit invocation is useful when:

• the task is high risk;
• several skills overlap;
• the user needs a repeatable named workflow;
• a team is evaluating a new skill;
• implicit selection has been unreliable.

It is not a substitute for good metadata. Other users will still describe tasks naturally.

A Worked Example From Our Repositories

Assume the available metadata includes:

name: planning-research
description: Research a repository and produce an implementation-ready plan. Use when scoping features, identifying dependencies, or preparing work before code changes.

name: plan-critique
description: Review an implementation plan for missing evidence, unsafe assumptions, dependency gaps, and unverifiable acceptance criteria.

Task:

Review this existing plan and tell me whether it is ready to execute.

The expected skill is plan-critique, because the task concerns reviewing an existing plan and determining readiness. planning-research is related but has a different outcome: creating or preparing a plan.

We can observe whether the correct skill loads and whether the output performs a critique. We should not claim to know every internal comparison the model made.

How We Evaluate Skill Routing

Our preferred method resembles a small behavioral test suite.

1. Define Positive Cases

Write prompts that should activate the skill:

2. Define Boundary Cases

Use prompts that should activate a neighboring skill or none:

Boundary cases are often more informative than obvious positives because they expose overlapping descriptions.

3. Record Observable Evidence

Capture:

• prompt;
• enabled skill set;
• runtime and version;
• whether activation was explicit or implicit;
• activated skill, if observable;
• files or tools used;
• output quality;
• failure category.

Do not record a fabricated explanation of hidden model reasoning.

4. Change One Variable

If routing fails, revise the description, directory installation, or skill boundary—not all three at once. Re-run the same cases.

5. Evaluate Execution Separately

A skill can route correctly and still produce weak work. Score:

• routing: did the intended workflow activate?
• adherence: did the agent follow it?
• outcome: was the artifact correct?

Combining all three into “the skill worked” makes diagnosis difficult.

Common Routing Failures

The Skill Was Never Installed

Before rewriting metadata, verify the runtime can discover the directory. A correct description in the wrong location is still unavailable.

Two Descriptions Claim the Same Job

If both a generic testing skill and a component-testing skill say “use for tests,” selection is ambiguous. Clarify the boundary or consolidate them.

The Description Lists Tools but Not Intent

“Uses Jest, Playwright, and RTL” names tools without saying what outcome the skill provides. State the job first.

The Body Tries to Repair Metadata

A beautiful explanation after activation cannot compensate for an unclear discovery description.

Evaluation Uses Only Exact Phrases

Testing only phrases copied from metadata can produce false confidence. Include paraphrases and realistic project language.

Our Opinionated Description Template

This is a writing aid we use, not a standard field format:

[Action and outcome]. Use when [task situations]. Do not use for [important neighboring boundary, if needed].

Example:

description: Review pull request changes for correctness, security, regression risk, and missing tests. Use for PR or diff review; do not use to implement requested changes unless the user asks.

The boundary sentence is valuable when two skills are close. Omit it when the distinction is already obvious.

Why This Matters for Startups

Small teams often encode a few high-value workflows: releases, incident response, architecture review, security checks, and product planning. Misrouting one of those can waste time or create risk.

A lightweight routing suite gives the team evidence that:

• the workflow is installed;
• normal team language activates it;
• neighboring tasks do not activate it unexpectedly;
• the result follows the intended process.

This is more useful than adding dozens of skills and assuming file count equals maturity.

Key Takeaways

1. Discovery begins with name and description; the body loads after activation.
2. Body trigger lists and examples help maintainers and execution, not standard initial discovery.
3. Exact ranking behavior is runtime-specific.
4. Test routing through observable prompts, activation, and outputs.
5. Evaluate routing, adherence, and outcome as separate dimensions.

Frequently Asked Questions

Can an agent load more than one skill?

Some runtimes can compose or sequentially use skills. Do not assume identical behavior across products; document the runtime tested and evaluate interactions between overlapping skills.

How can I know which skill loaded?

Use product-visible activation information, tool logs, file reads, or controlled output requirements when available. If the runtime does not expose activation, evaluate behavior without claiming hidden certainty.

Should descriptions contain keywords?

They should use concrete domain and task language, but semantic clarity matters more than keyword stuffing. Include terms real users use and describe the capability accurately.

What if implicit selection remains unreliable?

Clarify the description, reduce overlap, verify installation, and use explicit invocation for high-risk workflows. Report the limitation instead of promising deterministic routing.

Official References

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

Conclusion

Skill selection is not magic, but it is also not one universal keyword algorithm. The reliable part is the contract: clear metadata enables discovery, the body guides execution, and evaluation measures what actually happened.

That is how we work with agent routing in practice—document the vendor facts, state our conventions, test observable behavior, and leave hidden reasoning claims out of the evidence.

For authoring guidance, read How to Write Agent Skills That Work Reliably. For cross-tool installation, see Portable Agent Skills Across Copilot, Codex, and Claude and Custom Instructions for AI Coding Agents.

Want repeatable workflows whose activation and outcomes can be evaluated? Explore ByblosAI or contact us.