Agent Personas vs. Skills: Role, Rules, and Workflow

There is an open format for Agent Skills, but there is no universal cross-vendor “persona versus skill” standard. In our repositories, we use a clear design convention: personas describe responsibility and boundaries, persistent instructions describe repository rules, and skills describe repeatable task workflows. The separation reduces duplication without pretending every AI tool implements these files identically.

The Important Caveat First

GitHub Copilot, OpenAI Codex, and Claude Code all support ways to customize agent behavior, but their file names, discovery paths, and runtime features differ. A GitHub custom agent file is not automatically a portable persona standard. An AGENTS.md file is not the same mechanism as a Claude Code skill.

The three-layer model in this article is therefore our architecture convention, developed while maintaining this website and the larger ByblosAI application. We find it useful because it assigns each kind of guidance one primary home:

This is a separation-of-concerns pattern, not a rule imposed by the Agent Skills specification.

What We Mean by a Persona

For us, a persona is a concise role brief. It helps a human or agent understand the perspective from which work should be approached.

Our website repository includes personas for content, design, components, testing, planning, and standards review. The ByblosAI codebase uses the same idea for more specialized engineering and product workflows.

A useful persona can include:

• the role and domain;
• the decisions it can make;
• actions that require escalation or approval;
• quality boundaries;
• the skills or workflows commonly used;
• the expected communication style.

For example:

## Role

Review technical content for accuracy and practical value.

## Boundaries

- Do not invent benchmarks, quotes, or production evidence.
- Distinguish implemented, tested, and planned capabilities.
- Do not edit published content unless the request includes it.

## Relevant Workflows

- Use the blog-post workflow for article changes.
- Use the XEO workflow for answer blocks and source readiness.

The file says what the reviewer is responsible for and what must not be claimed. It does not reproduce the complete editorial workflow.

What We Mean by Persistent Instructions

Persistent instructions describe the repository, not a temporary task. Examples from our application work include:

• use pnpm, not npm or yarn;
• keep strict TypeScript and do not introduce any;
• place database access in the database layer;
• reuse shared components before creating replacements;
• run type checking before completion;
• keep shared-tier dependencies moving in one direction.

Different tools discover these rules differently:

• GitHub Copilot supports .github/copilot-instructions.md and path-scoped .github/instructions/**/*.instructions.md.
• Codex uses repository AGENTS.md files and can apply more specific nested instructions.
• Claude Code uses CLAUDE.md, .claude/CLAUDE.md, and optional path-scoped rules.

In our larger repository, root AGENTS.md and CLAUDE.md files are thin entrypoints. They route agents to the detailed .github catalog, reusable patterns, and scoped instructions. That arrangement is our compatibility choice. It is not proof that every vendor natively treats .github/ the same way.

What Belongs in a Skill

A skill is appropriate when the team needs a repeatable capability that should load for a particular kind of task.

Examples include:

• creating a blog post;
• investigating a browser defect;
• reviewing an implementation plan;
• generating focused tests;
• reconciling a shared-tier update;
• validating a release.

The Agent Skills standard defines the portable core: a skill directory with a required SKILL.md, required name and description metadata, and optional supporting resources. The skill body can then hold the procedure, examples, scripts, and validation needed after activation.

Our recommendation is to put task sequence and task-specific evidence in the skill. That keeps broad repository instructions from growing into a collection of every workflow the team might ever run.

The Boundary Is Not Absolute

Clean architecture does not mean artificial purity. Some information legitimately appears in more than one layer at different levels of detail.

Consider the rule “never invent runtime evidence”:

• A persona may list it as a non-negotiable boundary.
• Persistent repository instructions may establish it as a general reporting standard.
• A deployment skill may explain exactly which browser, provider, credential, and production checks count as runtime evidence.

That is not necessarily harmful duplication. The problem is copying the same detailed procedure into three places and allowing the copies to drift.

Our rule is:

Repeat a principle when the audience needs it; keep the detailed procedure and source of truth in one place.

A Decision Test We Use

When guidance has no obvious home, ask these questions in order:

1. Is this defined by a published specification or vendor? Document it as a fact and link the source.
2. Is this true across most work in the repository? Put the concise rule in persistent instructions.
3. Is it about responsibility, authority, or behavior for a role? Put it in the persona.
4. Is it a repeatable task with steps and validation? Put it in a skill.
5. Would violating it create a security or data-integrity risk? Enforce it in code, permissions, CI, or policy—not only in prose.

The fifth question is crucial. Instructions influence agent behavior; they are not a substitute for authorization checks, schema validation, or CI gates.

A Before-and-After Example

Before: One Oversized Agent File

You are the testing agent.

- Tests live under test/.
- First inspect the component.
- Use React Testing Library.
- Mock network calls.
- Run pnpm test.
- Never use any.
- Database calls belong in lib/db/.
- Here is a 60-line test template...

This mixes role, repository rules, workflow, and implementation detail.

After: Three Focused Sources

AGENTS.md
  └─ repository-wide architecture and validation rules

.github/agents/test-agent.md
  └─ testing responsibility, authority, and boundaries

.github/skills/test-generation/SKILL.md
  └─ test-generation workflow, examples, and commands

The exact paths are our convention. The design benefit is broader: each source changes for a different reason.

Why This Matters for Startups

Early startup teams regularly combine roles. One engineer may review architecture, fix the UI, and operate production in the same week. AI personas should not create a fictional organization chart that the company does not have.

Instead, use personas to make responsibility explicit:

• Who can approve a release?
• Who decides whether a security finding is accepted?
• Who owns the product trade-off?
• When should the agent stop and ask a human?

Use skills to make recurring execution consistent. This supports a small team without pretending that a persona file creates real accountability on its own.

Common Failure Modes

Treating Our Layout as an Open Standard

.github/agents, .github/instructions, and .github/skills work well for our repositories and align closely with GitHub Copilot. Other tools have different native locations. Present the layout as a repository convention with adapters or entrypoints.

Putting Every Rule in a Persona

This creates large files that are expensive to maintain and difficult to reuse. Keep the persona focused on role and boundaries.

Making Skills Responsible for Authorization

A skill can instruct an agent to request approval, but actual authorization belongs in code and platform policy.

Eliminating All Repetition

Some principles should appear in more than one context. Remove contradictory procedural copies, not every reminder.

Key Takeaways

1. Persona-versus-skill separation is our design convention, not an Agent Skills requirement.
2. Personas describe responsibility and boundaries; skills hold repeatable task workflows.
3. Persistent instructions carry repository-wide or path-scoped standards.
4. Vendor discovery paths differ, so portable intent still needs vendor-aware entrypoints.
5. Critical controls must be enforced by code, CI, or permissions—not only agent prose.

Frequently Asked Questions

Is an AI agent persona part of the Agent Skills standard?

No. The Agent Skills specification defines skills. Vendor-specific custom agents, personas, and persistent instruction files are separate mechanisms.

Should a persona contain any procedural detail?

It can contain a short operating expectation, but the reusable step-by-step procedure should have one primary source of truth. In our repositories that source is usually a skill.

Can one persona use several skills?

Yes. A role may need several workflows, and one skill may be useful to several roles. The relationship is many-to-many rather than a rigid ownership hierarchy.

Does this structure guarantee correct agent behavior?

No. It improves clarity and maintainability. Correctness still depends on the runtime, prompt, tools, permissions, code-level controls, and observed validation.

References

• Agent Skills specification
• GitHub Copilot custom agents
• GitHub Copilot repository instructions
• OpenAI Codex customization
• Claude Code project memory and instructions

Conclusion

Our preferred architecture is not “the one correct folder tree.” It is a maintainable agreement: roles explain responsibility, repository instructions explain enduring constraints, and skills explain repeatable work.

That distinction has helped us keep a small website repository and a much larger application repository understandable to multiple coding agents. It is a practice we recommend because we use it—not a standard we invented on everyone else’s behalf.

Next, the series turns to cross-vendor custom instructions. For the foundation, see How to Write Agent Skills That Work Reliably and the external delivery standards we use.

Need an agent setup that reflects how your team actually works? Explore ByblosAI or contact us.