Agent Skills Anti-Patterns: 10 Problems and Better Fixes

The most damaging Agent Skills anti-patterns are not missing decorative sections. They are invalid metadata, vague discovery descriptions, procedures that depend on unseen body content, unsafe or unavailable tools, duplicated sources of truth, stale paths, oversized context, false portability claims, unverified routing, and evidence reports that claim more than was tested.

How We Chose These Anti-Patterns

Some failures violate the Agent Skills specification. Others are engineering risks we have learned to watch while maintaining agent workflows across a small Astro website and a much larger TypeScript application.

We label them accordingly:

• Standards defect: contradicts a required format rule.
• Vendor compatibility defect: conflicts with documented product behavior.
• Our engineering judgment: a practice we recommend based on maintainability, safety, and delivery evidence.

That distinction prevents “we prefer this” from becoming “the standard requires this.”

1. Invalid Required Metadata

Category: Standards defect.

The skill directory is missing SKILL.md, lacks name or description, uses an invalid name, or has a name that does not match the directory.

skills/
└── Blog Writer/
    └── instructions.md

Better fix: follow the required contract and run the reference validator:

skills/
└── blog-writer/
    └── SKILL.md

Do this before debating style or examples. Invalid skills may never enter the runtime’s available set.

2. A Description That Does Not Define Use

Category: Quality defect grounded in the standard’s description guidance.

description: Helps with plans.

The agent cannot distinguish planning, plan critique, status reporting, or executing an approved plan.

Better fix:

description: Review implementation plans for missing dependencies, unsafe assumptions, and unverifiable acceptance criteria. Use when evaluating an existing plan before execution.

Our practice is to state capability, situation, and—when useful—a neighboring boundary.

3. Trying to Trigger Discovery From the Hidden Body

Category: Runtime-model defect.

The skill has a long Trigger Phrases section, while its frontmatter remains vague. Under standard progressive disclosure, the runtime sees metadata before it loads the body.

Better fix: put the meaning needed for discovery in description. Keep body trigger lists only as maintainer documentation or test cases.

A missing trigger heading is not a defect. A description that fails to explain when the skill applies is.

4. A Procedure That Cannot Be Executed

Category: Our engineering judgment.

The body says:

Review carefully, follow best practices, and ensure high quality.

Nothing defines the artifact, sequence, decision rules, or evidence.

Better fix: specify observable work:

1. Inspect the current plan and referenced code.
2. Map dependencies and authorization boundaries.
3. Identify unproven acceptance criteria.
4. Produce findings ordered by severity.
5. State which checks were automated, live, or not run.

The exact structure is optional. Actionability is the goal.

5. Unsafe or Imaginary Tool Assumptions

Category: Compatibility and safety defect.

The skill assumes network access, credentials, a browser, unrestricted shell commands, or permission to publish externally. Worse, it may instruct the agent to bypass confirmation.

Better fix:

• declare required capabilities in compatibility guidance;
• request approval where the runtime requires it;
• separate read-only inspection from state-changing actions;
• use code-level authorization for protected operations;
• provide a safe fallback or stop condition;
• never claim an unavailable tool ran.

In our work, “finish continuously” means persist within authorized scope. It does not expand authority to deploy, publish, delete data, or contact people.

6. Duplicated Procedures Across Instructions, Personas, and Skills

Category: Our repository-design judgment.

The same 40-step workflow lives in:

• .github/copilot-instructions.md;
• an agent persona;
• a SKILL.md;
• a README.

The copies drift. An agent receives contradictory commands.

Better fix: choose one procedural source of truth. Keep short principles or links in the other layers.

This does not require eliminating every repeated sentence. A safety principle may appear in a persona and global instructions. The detailed sequence should have one owner.

7. Stale Paths, Commands, Models, or Product Claims

Category: Maintenance defect.

The skill references:

• a renamed directory;
• a removed script;
• a retired model;
• an old package command;
• a capability still marked “coming soon” elsewhere.

Better fix: attach skill review to repository events:

• architecture or package-manager changes;
• provider migrations;
• route or module moves;
• model deprecations;
• product release-state changes;
• repeated runtime failures.

We prefer current-source verification over memory when the fact can drift.

8. A Monolithic Skill That Loads Too Much Context

Category: Our engineering judgment, supported by progressive disclosure.

One SKILL.md contains several thousand lines of API references, templates, troubleshooting, and unrelated variants.

Better fix: keep the entrypoint focused and move detail into direct references:

provider-release/
├── SKILL.md
└── references/
    ├── aws.md
    ├── cloudflare.md
    └── rollback.md

Do not overcorrect by forbidding supporting files. The standard explicitly allows them. Audit relevance, link depth, and consistency instead.

9. “Portable” Because It Uses Markdown

Category: Vendor compatibility defect.

The article or skill claims one .github/skills installation automatically works in Copilot, Codex, and Claude because the files are Markdown.

Better fix: evaluate three layers:

1. format compatibility;
2. native discovery or explicit routing;
3. tool and permission compatibility.

Name the runtime and product surface tested. Use vendor-specific adapters where necessary. Narrow the claim when a runtime has not been exercised.

10. Reporting Evidence That Was Never Produced

Category: Our strongest engineering boundary.

Examples:

• “production ready” after type checking;
• “works in the browser” after unit tests;
• “provider integration verified” with mock responses;
• “human approved” because an agent marked a checklist;
• “the correct skill selected” without observable activation or behavior.

Better fix: label evidence precisely:

This boundary is central to how we work in ByblosAI. We leave live gates open until they are actually run.

Things That Are Not Automatically Anti-Patterns

Supporting Files

Scripts, references, assets, and additional files are allowed and often useful.

No Before/After Example

An example can improve an ambiguous task. It is not mandatory if the workflow is already clear and tested.

No Trigger Phrases Heading

Initial discovery depends on metadata under the standard model. A trigger list is optional documentation.

No Persona Directory

Personas are a repository architecture choice, not a prerequisite for valid skills.

Tool-Specific Adapters

Vendor-specific instructions are honest when labeled and isolated. Pretending they are universal is the problem.

A Diagnostic Table

How We Repair a Skill

Our repair sequence is:

1. Validate the required contract.
2. Confirm the runtime’s documented discovery path.
3. Tighten the description and neighboring boundary.
4. Define the outcome and evidence.
5. Remove unsafe assumptions.
6. Split large references without duplicating them.
7. Run positive and boundary routing cases.
8. Inspect adherence and result quality.
9. Record unverified live or human gates.
10. Assign an owner or review trigger.

This sequence moves from structural availability to operational trust.

Why Startups Should Care

A startup may depend on a small number of skills for release, security review, product discovery, customer migrations, or incident response. A quiet failure in one of those workflows is more expensive than a missing convenience skill.

Start with high-consequence, high-frequency work. Make those skills valid, observable, and maintained before building a large catalog.

Key Takeaways

1. Invalid metadata and unsupported discovery claims are factual defects.
2. Trigger lists and examples are optional practices, not required discovery fields.
3. Supporting files are valid; unsafe, stale, or excessive context is the risk.
4. Our one-source-of-truth layout is a maintainability convention.
5. Never let automated evidence stand in for browser, provider, production, or human proof.

Frequently Asked Questions

What is the most serious Agent Skills anti-pattern?

For availability, invalid metadata or installation is fundamental. For safety, the most serious issue is an agent performing or claiming unauthorized external work. For trust, invented evidence is the most damaging.

Should every skill be vendor-neutral?

No. Vendor-specific tasks need vendor-specific guidance. Keep the core outcome and evidence clear, label adapters, and test the runtime named.

How often should skills be reviewed?

Review them when relevant architecture, commands, models, providers, or policies change. Periodic review is useful, but event-driven review catches drift closer to its cause.

Does a large skill catalog mean a repository is mature?

No. Inventory size can increase overlap and maintenance. Maturity comes from reliable routing, safe execution, current guidance, and evidence.

References

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

Conclusion

The best anti-pattern list is one that helps a maintainer diagnose a real failure. That requires separating standards defects, vendor mismatches, and our own engineering preferences.

Use this list with the Agent Skills Readiness Scorecard, the runtime discovery walkthrough, and the portable skills guide.

Want practical agent workflows with evidence boundaries designed in from the start? Explore ByblosAI or contact us.