The Agent-Skills Mental Model: From Rules to Evidence
The key question for addyosmani/agent-skills is not how many Markdown files it contains, but how responsibility is divided among them. This chapter examines the repository as a system with five layers—skills, personas, commands, references, and evals—and shows what each layer owns. That model helps readers decide whether they need a workflow, a specialist viewpoint, a repeatable entry point, a checklist, or evidence that the arrangement is working.
The distinction matters because agent guidance becomes fragile when every concern is placed in one undifferentiated prompt. A single block may contain routing rules, implementation advice, security reminders, and review instructions, but it is difficult to know which part should run, who is responsible for a decision, or how to tell whether the guidance changed behavior. Agent-skills addresses that problem by separating the system’s control surfaces.
A skill is a process, not a reference document
A reference document primarily tells a reader what something is or records information they may consult. A skill in this repository has a different job: it guides an agent through a situation. Its description says when it applies. Its process says what to do. Its rationalization table anticipates reasons to skip the process. Its red flags identify behavior that suggests the process is being violated. Its verification section defines the evidence needed to stop.
That difference is easy to miss because both artifacts can be written in Markdown. Consider the distinction between a testing reference and a test-driven workflow. A reference might explain unit tests, integration tests, and end-to-end tests. A workflow tells an agent to discover the repository’s actual test command, write a failing test before changing behavior, make the smallest implementation pass, run the full suite before completion, and stop if a test is being skipped. It governs a sequence of decisions, not just the agent’s vocabulary.
The process orientation also explains why the repository includes common rationalizations. “I’ll write tests after the code works” is not a missing fact; it is a predictable attempt to trade evidence for speed. A skill can answer that attempt at the moment it appears. Similarly, a red flag such as a large untested change is an observation about behavior, not a general warning to remember someday. The skill’s value lies in connecting an action to a checkpoint.
This makes a skill a boundary around agent behavior. It does not guarantee that the agent will comply, and it does not replace project-specific requirements. It does make the intended path explicit enough that a human, a command, or an evaluation can inspect whether the path was followed.
Personas add a viewpoint without taking over routing
A persona answers a different question: who is looking at the work, and what kind of report should they produce? In agent-skills, specialist personas include roles such as a code reviewer, security auditor, test engineer, and web-performance auditor. The role does not replace the underlying workflow. A security persona still uses security guidance; a review persona still evaluates a change across defined dimensions. The persona supplies a perspective and an output shape.
That separation is valuable when one artifact deserves several independent kinds of scrutiny. A code reviewer may notice an unclear abstraction or a missing error path. A security auditor may focus on authorization, secrets, or untrusted input. A test engineer may identify an untested edge case or a missing reproduction. The same change can legitimately need all three observations, but the observations should remain distinguishable until a main decision-maker compares them.
The repository’s /ship command makes this arrangement concrete. It sends the current change to code-review, security, and test specialists in parallel, then merges their reports into a go/no-go decision and a rollback plan. Parallelism is appropriate there because the investigations share an input but do not need to modify one another’s state or wait for one another’s conclusions. The merge is still a separate responsibility: it resolves duplicate findings, promotes security blockers, checks infrastructure and documentation, and turns several views into one decision.
A persona is therefore not a hidden manager. It should not decide which other personas to invoke, paraphrase their findings, or grow a private tree of delegates. That would blur the boundary between viewpoint and orchestration. It would also make it harder for a user to see why a particular review ran and what it cost.
Commands decide when a composition runs
Commands are the user-facing entry points. They make a repeatable workflow easy to invoke without asking the user to reconstruct its setup every time. A command can wrap one skill or one persona, as /review does for a five-axis review. It can also compose several independent personas, as /ship does. The important property is that the command expresses an intentional moment in the lifecycle: define, plan, build, test, review, simplify, or ship.
Commands do not make all phases interchangeable. A specification must precede a plan because the plan depends on the requirements. Implementation depends on a chosen task and its acceptance criteria. A launch decision depends on verification and review. These are dependency relationships, so the repository recommends a user-driven sequence for them rather than an autonomous routing layer that repeatedly summarizes one phase into the next.
That choice protects two kinds of state. The first is decision state: a human may reject a scope assumption or change a boundary before the agent invests in implementation. The second is context state: every paraphrase between hidden sub-agents can omit a qualification that seemed minor but changes the design. Keeping the user or an explicit command as orchestrator makes the handoff visible and lets the next operation read the durable artifact rather than trusting a compressed retelling.
The boundaries become clearer when the same request is viewed through the five layers. Suppose a team wants to change a service endpoint. The command is the entry point that starts the work; it does not decide the endpoint’s response semantics. The relevant skill supplies the process for clarifying the requirement, planning the change, testing it, and stopping when evidence is missing. A persona may inspect the resulting change for security or test gaps, but that persona does not become the owner of the implementation workflow. A shared reference can supply the checklist for the review, while an evaluation can later examine whether the intended workflow was activated and followed. Each layer contributes something different, and no layer needs to duplicate the others to be useful.
This division also keeps failure diagnosis more precise. If the endpoint is wrong because the requirement was vague, the problem belongs near the Define boundary. If the correct workflow was never invoked, the problem may belong to command or routing behavior. If the workflow ran but the agent skipped its verification, the process or enforcement boundary is implicated. If the review found the issue but the final decision ignored it, the merge and human-approval boundary failed. A single “agent prompt” would make all of these look like the same kind of mistake. The layered model turns them into distinct questions with different remedies.
A command can still support automation within an approved boundary. That is a useful design distinction: a repeatable entry point can reduce interaction overhead without pretending that dependency order or human approval has disappeared.
References hold reusable checks at the edge of context
References are shared material that more than one workflow may need, such as a security checklist, a performance checklist, an accessibility checklist, an observability checklist, or a project-wide Definition of Done. Keeping these materials separate prevents every skill from copying the same rules and then drifting apart. A security rule updated in one place can remain the common reference for several workflows.
This layer also supports progressive disclosure. An agent does not need every checklist in every session. It can load the security material for an input-handling change, the browser guidance for a UI issue, or the observability checklist when a production path is being instrumented. The repository treats context as a limited working surface, so “available somewhere in the pack” is not the same as “always injected into every task.”
The ownership boundary matters here. A reference can define what to inspect, but it is not automatically a command to run. A skill decides when the reference is relevant and how its checks fit into the current task. This prevents a shared checklist from becoming an unprioritized wall of requirements while still keeping the underlying standard consistent.
Evals provide a different kind of evidence
The fifth layer asks whether the catalog works as a catalog. A valid skill file is not enough if the surrounding system cannot discover it or if the workflow does not behave as intended when it is invoked. Evals give those questions a place of their own instead of hiding them inside prose.
At this level, the object being measured is not the feature under development. It is the workflow system and the agent’s observable response to it. That separation is important. An evaluation of a skill can provide evidence that a workflow was triggered and followed in a controlled scenario. It cannot, by itself, show that the application being built is correct in production. The later discussion of evaluation will distinguish the different strengths and costs of that evidence.
Why the repository rejects a giant orchestrator
These layers are useful only when information can cross them without losing ownership. A request may enter through a command, select a skill, load a reference, ask a persona for a view, and produce an artifact that an eval can inspect. The arrows are meaningful because each one carries a different kind of responsibility.
A router persona would add a layer without adding a domain judgment. It would decide that another persona should run, pass along a summary, receive a second summary, and return a paraphrase to the user. The repository rejects that pattern because it increases token cost and latency while making context loss harder to detect. A persona that calls another persona creates a similar problem: the first role becomes a hidden orchestrator, and the user cannot easily see why the second role was chosen or which output format controls the result.
The same caution applies to automatically chaining the whole lifecycle. The phases have dependencies and human decision points. A central agent that runs specification, planning, implementation, review, and launch on the user’s behalf would have to summarize every handoff, decide when a direction is settled, and potentially continue through a wrong assumption. The repository prefers the user-driven sequence for this reason. The system is not refusing automation; it is placing automation where the inputs are independent or the boundary has already been approved.
The system model is a decision tool
The five layers answer five different needs. If the problem is “what should the agent do, and how do we know it is finished?”, choose a skill. If the problem is “what viewpoint is missing from this change?”, choose a persona. If the problem is “how do we invoke this repeatedly at a lifecycle boundary?”, choose a command. If the problem is “what shared standard should several workflows consult?”, choose a reference. If the problem is “did the catalog trigger and behave as intended?”, choose an eval.
They can be combined, but they should not be collapsed. A command that merely routes to a persona has little value. A persona that rewrites another persona’s report adds noise. A skill that copies every reference becomes expensive to load and difficult to maintain. An eval that checks only whether a file exists says little about behavior. The repository’s architecture is a practical argument that reliability comes from clear ownership and inspectable handoffs, not from accumulating more instructions in one place.
With that model in hand, the next question becomes concrete: how does a request move through the first two layers, from uncertain intent to a specification and plan that an agent can safely act on?