An Agent Skills Maturity Model for Engineering Teams

Our Agent Skills maturity model has six levels: personal prompts, shared instructions, focused skills, evaluated workflows, governed operations, and portable capability management. It is an opinionated framework based on how we work—not an industry standard. Progress is measured by observable reliability, evidence, ownership, and safety rather than the number of agent files in a repository.

Why We Built Our Own Model

The Agent Skills specification defines a file format. It does not define how mature an engineering organization is, how many skills it should own, or whether a persona directory is required.

We still need a way to discuss operational progress. In our website and ByblosAI application repositories, the important questions are:

• Is recurring knowledge written down?
• Can the intended runtime find it?
• Does the workflow produce a useful result?
• Are authorization and evidence boundaries explicit?
• Is performance evaluated?
• Does someone keep it current?
• Can another tool or team reuse it without false promises?

The maturity model below is our management and engineering lens for answering those questions.

Level 0 — Personal Prompts

State: each contributor keeps prompts in memory, chat history, or private notes.

What works: experimentation is fast and requires no repository design.

Risk: the process depends on an individual. Results vary, onboarding repeats, and failures are hard to reproduce.

Evidence of this level:

• no shared repository guidance;
• recurring prompts copied manually;
• no agreed validation report;
• outcomes depend heavily on who initiated the task.

Next investment: document three or four durable repository facts and one high-frequency workflow.

For a small startup, this may be enough during exploration. Maturity should follow real need, not fashion.

Level 1 — Shared Repository Instructions

State: the team commits build commands, architecture rules, and validation expectations.

Typical vendor files include:

• .github/copilot-instructions.md;
• AGENTS.md;
• CLAUDE.md;
• path-specific instruction files.

What improves: agents and new contributors start from a common baseline.

Risk: one instruction file becomes a catch-all for every procedure. Broad context grows, rules conflict, and task guidance loads even when irrelevant.

Evidence required to claim Level 1:

• the documented file actually loads in the target runtime;
• commands and paths match the repository;
• critical rules are not only aspirational prose;
• conflicts have been reviewed.

Next investment: extract one repeatable, high-value procedure into a focused skill.

Level 2 — Focused Skills

State: the repository contains valid skills for recurring work.

Examples from our operating model include:

• blog authoring;
• plan critique;
• implementation planning;
• test generation;
• browser investigation;
• dependency maintenance.

What improves: task-specific detail can load on demand rather than living in global context.

Risk: the team assumes valid files automatically mean reliable selection and execution.

Evidence required to claim Level 2:

• required SKILL.md metadata validates;
• descriptions state what and when;
• workflows define observable outcomes;
• the target runtime can discover or explicitly load them;
• supporting files resolve.

Next investment: build behavioral evaluations for routing, adherence, and output.

Level 3 — Evaluated Workflows

State: important skills have realistic positive, paraphrased, boundary, and failure cases.

What improves: the team can distinguish:

• installation failures;
• routing failures;
• instruction-adherence failures;
• output-quality failures;
• unavailable environment capabilities.

Risk: evaluations cover only happy paths or exact phrases copied from descriptions.

Evidence required to claim Level 3:

• runtime and enabled skills are recorded;
• activation or observable behavior is captured;
• outputs are reviewed against explicit criteria;
• failures inform targeted revisions;
• automated checks are not reported as live proof.

Next investment: add governance for high-risk actions, evidence, and maintenance.

Level 4 — Governed Operations

State: skills participate in a controlled engineering system rather than acting as standalone prompts.

In our repositories, governance includes:

• explicit authorization boundaries;
• read-only inspection before risky actions;
• protected database and API layers;
• strict schemas and types;
• CI validation;
• reusable implementation patterns;
• truthful plan and checklist status;
• separation of automated, browser, provider, production, and human evidence.

What improves: the team knows what an agent may do, what requires approval, and what counts as completed.

Risk: process becomes bureaucratic or relies on instructions for controls that should be technical.

Evidence required to claim Level 4:

• destructive and external actions have real permissions;
• critical invariants are enforced in code or CI;
• failures and exceptions are auditable;
• workflows have owners or review triggers;
• stale capabilities are removed or marked.

Next investment: decide whether cross-runtime portability is valuable for the workflows that matter.

Level 5 — Portable Capability Management

State: the organization manages reusable workflows as versioned capabilities with tested runtime adapters.

What improves: core procedures survive changes in coding-agent vendors and can be distributed to different repositories or teams.

Risk: portability becomes a marketing claim instead of a tested property.

Evidence required to claim Level 5:

• the core skill follows the shared format;
• each named runtime has a documented discovery or installation method;
• tool-specific adapters disclose permissions and limitations;
• compatibility is tested per runtime;
• generated copies or packages have drift controls;
• versions and release notes exist where distribution requires them.

Level 5 is not automatically better for every startup. A company using one agent in one repository may receive more value from improving Level 3 evaluations than from packaging multi-vendor adapters.

The Full Maturity Map

Maturity Is Per Capability

A repository does not have to be one level everywhere.

For example:

• release operations may be Level 4;
• blog writing may be Level 3;
• design exploration may remain Level 0;
• a distributed testing skill may be Level 5.

This is healthier than forcing every experiment through the same governance. Apply stronger controls where consequence and frequency justify them.

How We Prioritize the Next Skill

We score candidate workflows using four practical factors:

High-frequency, high-consequence, inconsistent, and verifiable workflows make strong candidates.

Examples:

• release readiness;
• authorization reviews;
• schema migrations;
• plan execution;
• incident investigation;
• customer-data exports.

“Have an agent with a clever personality” is not, by itself, a maturity investment.

A Startup Path Through the Levels

First Month

• Commit the real build, test, and deployment commands.
• Record architecture and security boundaries.
• Create one skill for the most repeated task.

After Repeated Use

• Collect prompts that succeeded and failed.
• Clarify descriptions and boundaries.
• Add validation and failure handling.

Before Delegating High-Risk Work

• Enforce permissions technically.
• Require evidence reports.
• Separate mock, test, staging, provider, and production proof.
• Define human approval points.

When Supporting More Than One Tool

• Choose a canonical content source.
• Add documented discovery adapters.
• Test each runtime.
• Narrow unsupported claims.

This sequence reflects our experience: capability quality matters before catalog size.

What Does Not Prove Maturity

A Large Number of Skills

More files may mean more overlap, drift, and context.

A Perfect Static Score

Format and prose review cannot prove runtime behavior.

One Successful Demo

One prompt does not cover paraphrases, boundaries, permissions, or failure recovery.

“Works With Every Agent”

Compatibility requires installation and execution evidence for each named product.

Autonomous Language

Calling an agent an “executive” or “expert” does not grant authority or prove judgment.

Our Governance Principles

The following are opinionated practices from our delivery work:

1. Reuse before creation. Check existing components, skills, and data flows.
2. One canonical source. Avoid procedural copies that drift.
3. Evidence stays typed. Automated, browser, provider, production, and human proof are different.
4. Authorization is technical. Agent prose cannot replace access control.
5. Plans stay truthful. Do not mark a stage complete without its required evidence.
6. Portability is tested. Shared Markdown is only the first layer.
7. Maintenance is part of ownership. Remove stale paths and capabilities.

These principles are not part of the Agent Skills specification. We recommend them because they have kept complex repository work safer and easier to review.

How to Assess Your Current Level

Choose one important workflow and ask:

1. Is it shared?
2. Is it a valid skill or only a prompt?
3. Can the target runtime load it?
4. Have routing and output been evaluated?
5. Are permissions and evidence boundaries enforced?
6. Is portability actually needed and tested?

The first “no” identifies the next useful investment. Do not jump directly to packaging if the workflow has never been evaluated.

Key Takeaways

1. This maturity model is our opinionated framework, not a published standard.
2. Maturity progresses from shared knowledge to skills, evaluation, governance, and tested portability.
3. Score individual capabilities rather than assigning one flattering label to a repository.
4. File count and autonomous language do not prove maturity.
5. Invest according to workflow frequency, consequence, variability, and verifiability.

Frequently Asked Questions

Does every team need to reach Level 5?

No. Level 5 is valuable when workflows must travel across tools or teams. A single-tool startup may gain more from strong evaluation and governance.

Can a repository skip personas?

Yes. Personas are part of our preferred architecture when roles and boundaries help. They are not required by the Agent Skills standard or this maturity model.

How quickly can a team move up?

There is no responsible universal timeline. A simple workflow can mature quickly; a production release or data migration capability needs more evidence and controls.

Can maturity decrease?

Yes. Stale paths, tool changes, unreviewed failures, and broken compatibility lower the operational level even if the files remain.

References and Related Guides

• Agent Skills specification
• Agent Skills Readiness Scorecard
• Agent Skills Anti-Patterns
• Portable Agent Skills
• External Developer Standards

Conclusion

An agent-ready repository is not one with the most agent files. It is one where important workflows are understandable, discoverable, evaluated, governed, and maintained at the level their risk requires.

That is our perspective after applying these patterns to both focused website work and a large multi-module application. Use the model as a decision aid, adapt it to your team, and keep the labels honest.

Ready to improve the next high-value workflow rather than merely add more files? Explore ByblosAI or contact us.