Agent Skills, Workflows, and Personalities: Why Your Coding Agent Needs All Three

I watched a coding agent spend 45 minutes investigating a Hibernate N+1 query. It searched the codebase, read entity relationships, traced lazy-loading paths, and eventually proposed adding @EntityGraph annotations. Good analysis. One problem: the same investigation had happened in the previous three sessions. Every time, the agent started from scratch.

That's what a codebase without skills looks like. The agent has the capability but no memory of what worked before. Every session is day one.

The one thing to take from this post: a skill is a reusable instruction set that turns a multi-step investigation into a single command. Skills, workflows, and personalities are three layers that compound — each one makes the others more effective.

What agents work with today

Before diving into skills, let's map the landscape. Every major coding agent tool has its own name for the same concept:

ToolWhat they call itFile location
DevinSkills.devin/skills/{name}/SKILL.md
CursorRules.cursor/rules/*.mdc
Claude CodeAGENTS.mdAGENTS.md (any directory)
WindsurfRules.windsurfrules or .windsurf/rules/
GitHub CopilotInstructions.github/copilot-instructions.md
ClineRules.clinerules
aiderConventionsCONVENTIONS.md or .aider/conventions

The names differ. The function is the same: persistent instructions that shape agent behavior across sessions.

The three layers

Layer 1: Rules — what the agent must always do

Rules are constraints that apply to every session. They prevent the agent from repeating known mistakes. Examples from a real Java codebase:

1# Always use the custom @Transactional wrapper
2Use investmentcafe.ngs.util.Transactional, NOT Spring's
3or Jakarta's @Transactional. The custom wrapper does not
4support readOnly=true.
5
6# Constructor injection for new code
7New services use constructor injection (@Service + final fields).
8Do not add @Autowired field injection.

Rules are the cheapest layer to implement. Write them when:

  • An agent makes a mistake you've corrected before
  • A convention exists that the agent can't infer from code alone
  • A security or compliance requirement must never be violated

The trap: too many rules. Every rule consumes tokens from the context window on every turn. A file with 200 rules means the agent is spending 10-15% of its context budget just reading instructions. Be ruthless about what earns a rule.

Layer 2: Skills — reusable multi-step playbooks

A skill is a named procedure the agent can invoke. Unlike a rule (which is a constraint), a skill is an action sequence — read these files, run these commands, produce this output format.

Here's what a real skill looks like (simplified):

 1# Skill: investigate-performance
 2
 3## When to use
 4When a user reports slow API response or a performance regression.
 5
 6## Steps
 71. Read the endpoint's resource class → find the service method
 82. Read the service method → identify database calls
 93. Run `EXPLAIN` on any query with joins or subqueries
104. Check for N+1 patterns: entity loads inside loops
115. Check HikariCP pool metrics if available
126. Report: root cause, affected queries, proposed fix
13
14## Output format
15| Finding | Evidence | Fix |
16|---------|----------|-----|

The skill doesn't replace the agent's reasoning — it gives it a proven investigation path so it doesn't waste 20 minutes figuring out how to investigate before it starts investigating.

When to create a skill:

  • You've guided an agent through the same multi-step process 3+ times
  • The process has a clear trigger ("when X happens, do Y")
  • The steps are specific enough that another developer could follow them

When NOT to create a skill:

  • The process changes every time (use a rule instead)
  • The steps are too generic ("investigate the problem" teaches nothing)
  • You're codifying a workaround instead of fixing the root cause

Layer 3: Personalities — how the agent communicates

This is the most underrated layer. A personality (or persona) defines the agent's communication style, priorities, and the lens through which it evaluates work.

Why does this matter? Because different tasks need different perspectives:

1# ic-critic persona
2You are an adversarial reviewer. Your job is to FALSIFY
3the previous agent's conclusion, not confirm it.
4
5- Start from the evidence, not the claim
6- Check that the fix addresses root cause, not symptoms
7- A "looks good" review is a failed review
1# ic-database-checkpoint persona
2You are a database specialist. You evaluate changes for:
3- Query performance (missing indexes, full table scans)
4- Connection pool safety (leak potential, pool exhaustion)
5- Migration safety (zero-downtime, rollback plan)
6- Multi-tenant isolation (cross-tenant data access)

Without personalities, every agent is a generalist. Generalists miss specialist concerns. A security specialist finds the SQL injection that a generalist reads past. A database specialist catches the missing index that the security specialist doesn't care about.

The personality doesn't change the model — it changes what the model pays attention to.

How the three layers work together

A workflow chains skills into a pipeline. For example, an implementation workflow might be:

  1. Investigate (skill) → understand the problem
  2. Implement (skill) → write the fix
  3. Test (skill) → verify the fix
  4. Review (skill, with critic personality) → challenge the fix
  5. Security checkpoint (skill, with security personality) → check for vulnerabilities

Each step uses the rules. Each evaluation step uses a personality. The workflow orchestrates the sequence. Remove any layer and the pipeline degrades:

  • No rules: the agent makes known mistakes repeatedly
  • No skills: the agent reinvents the investigation every session
  • No personalities: the reviewer rubber-stamps the implementer's work
  • No workflow: steps happen ad-hoc and critical checks get skipped

What this means in practice

If you're starting from zero:

  1. Start with 5-10 rules. The conventions your codebase has that the agent can't infer. Framework choices, naming patterns, forbidden patterns.
  2. Create your first skill after the third time you guide the agent through the same process. Investigation skills are the highest-leverage first skill.
  3. Add a critic personality before adding any other personality. The single biggest improvement in agent output quality is having a second pass that tries to break the first pass's work.
  4. Build workflows only when you have 3+ skills that naturally chain. Premature workflow design leads to rigid pipelines that don't match real work.

The next post covers the mechanics: how to actually write your first skill, what format to use for your tool, and the mistakes that waste the most time.

Next in this series: Creating Your First Agent Skills — templates, anti-patterns, and the five skills every codebase should have.

Posts in this series