DEV Community

Cover image for Beyond AGENTS.md: My Core Agent Skill Stack for Production Web Apps
Sedat Başar
Sedat Başar

Posted on

Beyond AGENTS.md: My Core Agent Skill Stack for Production Web Apps

#ai #webdev #softwareengineering #nextjs

A coding agent can write a type-safe Server Action, pass the build, and still miss a critical authorization check.

It can add a dependency for something the browser already handles natively, recreate a component that already exists in the project, or mark a task as complete without ever testing the flow in a real browser.

The problem is not that agents cannot write code.

The problem is that, when making decisions, they do not always have the right project context, up-to-date technical knowledge, or access to real verification tools.

The solution is neither to put the entire project into one enormous prompt nor to install every skill we come across.

I prefer to separate five responsibilities:

  • AGENTS.md → persistent project rules
  • Feature and domain documentation → project knowledge relevant to specific tasks
  • Skills → technical expertise on demand
  • MCP and development tools → evidence from the running application
  • CI → deterministic checks that cannot be skipped

This article focuses on browser-facing production web applications. Backend-only services naturally require a different baseline.

The goal is not to install as many skills as possible.

It is to build a small, composable core where every tool has a clear purpose.

My Core Skill Set

For a production web application, my baseline consists of seven pieces:

  • AGENTS.md + agents-md
  • modern-web-guidance
  • web-design-guidelines
  • code-security
  • semgrep
  • chrome-devtools
  • a11y-debugging

For React and Next.js, I also add:

  • version-matched Next.js documentation
  • vercel-react-best-practices

If the project uses shadcn/ui, I add:

  • shadcn

This stack does not replace testing strategy, CI rules, or code review. Those still need to be defined specifically for each repository.

I use pnpm in the commands below. If you use npm, replace pnpm dlx with npx.

1. agents-md: AGENTS.md Should Not Be an Encyclopedia 

pnpm dlx skills add getsentry/skills \
  --skill agents-md \
  --agent codex \
  --copy
Enter fullscreen mode Exit fullscreen mode

There are two separate concepts here.

AGENTS.md is persistent repository context available to the agent.

agents-md is a maintenance skill used to create or improve that file.

Installing the skill does not automatically rewrite an existing AGENTS.md.

Sentry's agents-md skill recommends keeping the file below 60 lines where possible and around 100 lines at most.

That is a useful target, but not an absolute rule.

Removing important project decisions simply to get below 100 lines is not context optimization. It is information loss.

So what should stay in AGENTS.md?

Things that affect many different tasks:

  • package manager and verified commands
  • architectural boundaries
  • dependency policy
  • coding preferences
  • fundamental security rules
  • UI conventions
  • pointers to authoritative project documentation

Feature-specific and domain-specific knowledge should live elsewhere.

For example:

docs/
├── authentication.md
├── payments.md
├── provider-integrations.md
├── deployment.md
└── ui-conventions.md
Enter fullscreen mode Exit fullscreen mode

Instead of duplicating those documents, AGENTS.md can simply route the agent to them:

## Authoritative references

Authentication and sessions → docs/authentication.md
Payments and subscriptions → docs/payments.md
External provider integrations → docs/provider-integrations.md
Production migrations → docs/deployment.md
Enter fullscreen mode Exit fullscreen mode

An authentication task can load the relevant security decisions without forcing a simple UI change to pull the entire payment architecture into context.

In this structure, AGENTS.md becomes a context router rather than a knowledge dump.

AGENTS.md vs. Skills

Vercel's AGENTS.md outperforms skills in our agent evals showed an important limitation of passive skill discovery: a useful skill can exist and still never be invoked.

That leads to a distinction I find useful:

Knowledge required for almost every task → AGENTS.md

Expertise needed for a particular task → Skill

Project decisions specific to a feature → Focused documentation

Evidence from the running system → Tool or MCP

This does not mean every installed skill should be listed in AGENTS.md. Skills already describe when they are relevant.

AGENTS.md should instead focus on outcomes the repository requires:

- Materially changed browser flows must be verified in the running application.
- Security-sensitive changes must be treated accordingly.
- Reuse the existing design system before introducing new UI primitives.
- Consult version-matched framework documentation before relying on model memory.
Enter fullscreen mode Exit fullscreen mode

If an agent repeatedly misses a critical workflow, then it makes sense to add a more explicit instruction.

2. modern-web-guidance: Keep the Agent's Web Knowledge Current 

pnpm dlx skills add GoogleChrome/modern-web-guidance \
  --skill modern-web-guidance \
  --agent codex \
  --copy
Enter fullscreen mode Exit fullscreen mode

Google Chrome's Modern Web Guidance provides current web-platform guidance for HTML, CSS, and client-side JavaScript work.

It covers modern capabilities such as native dialogs and popovers, container queries, :has(), View Transitions, anchor positioning, scroll-driven animations, modern forms, and frontend performance techniques.

Its most important contribution is simple:

Before generating another JavaScript abstraction or adding a dependency, check whether the browser already solves the problem.

That makes it useful for UI features, modern CSS, browser interactions, and frontend performance work.

Modern Web Guidance is currently marked as preview, so I would keep an eye on the repository as it evolves.

3. web-design-guidelines: Working UI Is Not Necessarily Good UI 

pnpm dlx skills add vercel-labs/agent-skills \
  --skill web-design-guidelines \
  --agent codex \
  --copy
Enter fullscreen mode Exit fullscreen mode

Vercel's web-design-guidelines reviews the interface produced by the agent.

The distinction from modern-web-guidance is important.

modern-web-guidance asks:

Which modern web approach should I use to build this?

web-design-guidelines asks:

Is the resulting interface actually usable and accessible?

It reviews things like focus visibility, keyboard interaction, form labels, responsive behavior, loading and error states, touch targets, reduced motion, and content hierarchy.

I use it for new or materially changed interfaces, not after every minor CSS edit.

Some recommendations can naturally reflect Vercel's own design preferences, so the project's established design system should always take precedence.

There is also an important accessibility boundary here.

web-design-guidelines can identify likely problems from the implementation.

a11y-debugging and Chrome DevTools verify what actually happens after that interface is rendered and interacted with in the browser.

4. Security: code-security and semgrep 

pnpm dlx skills add semgrep/skills \
  --skill code-security \
  --skill semgrep \
  --agent codex \
  --copy
Enter fullscreen mode Exit fullscreen mode

Semgrep provides two separate skills because writing secure code and operating a static-analysis tool are different jobs.

code-security

code-security is useful while security-sensitive code is being written.

It covers areas such as:

  • injection vulnerabilities
  • XSS
  • CSRF
  • SSRF
  • path traversal
  • JWT validation
  • secrets
  • cryptography
  • race conditions
  • infrastructure security

I consider it especially relevant when working on authentication and authorization, API endpoints, Server Actions, user input, database access, external requests, files, tokens, or infrastructure.

semgrep

The semgrep skill is about using the actual Semgrep tool effectively.

It helps with selecting rulesets, running targeted scans, investigating CI findings, evaluating false positives, and writing custom rules.

The separation is straightforward:

Writing security-sensitive code → code-security

Running or investigating static analysis → semgrep

A skill should not replace the actual security gate.

For production repositories, I also recommend running Semgrep in CI. The Semgrep Community Edition CI documentation is a good starting point.

Semgrep Agent Skills are currently described as beta, which is another reason to keep scanner output independent from the agent's interpretation.

5. chrome-devtools and a11y-debugging: Show the Agent the Real Browser

Install the skills:

pnpm dlx skills add ChromeDevTools/chrome-devtools-mcp \
  --skill chrome-devtools \
  --skill a11y-debugging \
  --agent codex \
  --copy
Enter fullscreen mode Exit fullscreen mode

Connect Codex to Chrome DevTools MCP:

codex mcp add chrome-devtools -- \
  pnpm dlx chrome-devtools-mcp@latest
Enter fullscreen mode Exit fullscreen mode

Source-code review alone is not enough.

A component may look correct while the running application still has:

  • a hydration error
  • a failing network request
  • broken focus order
  • an inaccessible dialog
  • a form flow that simply does not work

The chrome-devtools skill gives the agent a structured workflow for inspecting the running application.

It can navigate to the relevant page, inspect DOM and accessibility snapshots, execute the user flow, check console and network errors, and use performance traces or screenshots when needed.

a11y-debugging adds runtime accessibility checks for semantic HTML, accessible names, labels, keyboard navigation, focus order, dialog behavior, tap targets, and contrast.

The principle is simple:

The agent should not only read the code it changed. It should verify the affected user flow in the running application.

The scope should remain proportional to the task. Changing a form should trigger verification of that form, not an unnecessary audit of the entire site.

The Chrome DevTools repository also includes specialized skills for things like LCP optimization, memory leaks, and troubleshooting.

I treat those as on-demand debugging workflows rather than part of the default core.

An Additional Layer for Next.js and shadcn/ui

On top of this core, I add two skills when working with my preferred React stack.

One important detail first: I do not add a generic Next.js framework skill.

Current Next.js versions provide documentation matching the installed version under:

node_modules/next/dist/docs/
Enter fullscreen mode Exit fullscreen mode

and can direct coding agents to that source.

That means framework knowledge can come from the version actually installed in the project rather than model memory or another generic skill.

The Next.js AI Coding Agents guide explains this approach in more detail.

6. vercel-react-best-practices 

pnpm dlx skills add vercel-labs/agent-skills \
  --skill vercel-react-best-practices \
  --agent codex \
  --copy
Enter fullscreen mode Exit fullscreen mode

Vercel's React Best Practices skill focuses on React and Next.js performance.

It covers:

  • async waterfalls
  • bundle size
  • server-side performance
  • client-side data fetching
  • unnecessary re-renders
  • rendering cost
  • JavaScript performance

What I particularly like is the prioritization.

It pushes the agent toward high-impact problems such as request waterfalls and bundle cost before spending time on small rendering or JavaScript micro-optimizations.

Vercel explains the same philosophy in Introducing React Best Practices: performance work should be prioritized by actual user impact.

I use this skill for React components, Next.js data fetching, server/client boundaries, and bundle-sensitive changes.

7. shadcn 

pnpm dlx skills add shadcn/ui \
  --skill shadcn \
  --agent codex \
  --copy
Enter fullscreen mode Exit fullscreen mode

The official shadcn skill makes the agent inspect the project's actual configuration before generating code.

Using shadcn info --json, it can discover the framework, Tailwind version, package manager, aliases, installed components, icon library, primitive base, and component paths.

That matters because shadcn is not a traditional component library.

Its component source lives inside the repository, and implementation details can vary depending on the project configuration.

The skill encourages the agent to:

  • check existing components first
  • use the registry when necessary
  • respect the project's Tailwind and primitive setup
  • use semantic tokens
  • inspect diffs before modifying existing components

Project conventions still take precedence. Established form patterns, toast systems, and customized components should not be replaced without a clear reason.

The Final Setup

For a browser-facing production web application, my core is:

AGENTS.md + agents-md
modern-web-guidance
web-design-guidelines
code-security
semgrep
chrome-devtools
a11y-debugging
Enter fullscreen mode Exit fullscreen mode

For React and Next.js:

Version-matched Next.js documentation
vercel-react-best-practices
Enter fullscreen mode Exit fullscreen mode

And when the project uses shadcn/ui:

shadcn
Enter fullscreen mode Exit fullscreen mode

The resulting architecture is intentionally simple:

AGENTS.md
    ↓
Persistent project rules

Feature documentation
    ↓
Domain knowledge loaded when needed

Skills
    ↓
Technical expertise loaded when needed

MCP + development tools
    ↓
Real runtime evidence

Scanners + CI
    ↓
Deterministic verification
Enter fullscreen mode Exit fullscreen mode

Conclusion

Better results from coding agents do not require endlessly longer prompts.

They require better context architecture.

Adding more skills does not automatically improve quality. Without clear responsibilities, an agent can run unnecessary workflows, load duplicate information, or apply expertise where it is not relevant.

With the right boundaries, this core setup helps an agent:

  • apply project conventions more consistently
  • use current technical sources
  • avoid unnecessary dependencies and duplicate components
  • consider security during implementation
  • verify UI in a real browser
  • prioritize performance issues correctly

The main benefit is not that the agent writes more code.

The main benefit is that it makes fewer bad decisions.

I'm intentionally keeping this core small.

If you're using coding agents in production web projects and have a skill you consider essential, I'd be interested to hear what you'd add to this stack.

Drop it in the comments — especially if it covers a responsibility that isn't already represented here.

References

Top comments (0)