Context engineering for IDEs: Agents.md & agent skills

Context engineering for IDEs: Agents.md & agent skills

This article was originally published on LogRocket.

Agentic coding is actively cementing its role in modern software development despite the mixed opinions about it. The landscape has moved well beyond the AI-assisted autocomplete era we saw around 2022 with GitHub Copilot. Now, artificial intelligence is a first-class citizen in nearly every Integrated Development Environment (IDE) software engineers use today.

In today’s world, autonomous coding agents can plan, write, test, and modify code with minimal human intervention. They operate across files, reason about tasks, and execute multi-step changes in ways that go far beyond inline suggestions.

As the AI ecosystem expands and newer models emerge, the way we harness these tools continues to evolve. In this article, we’ll explore two emerging techniques — agents.md and agent skills — that let you augment your coding agent’s abilities by helping it understand your project structure, guidelines, and constraints, giving the agent enough context to tackle any task in that environment. With these tools, we can effectively engineer the model’s context window, increasing its probability to solve your given task.

Why Context Engineering Matters in IDEs

Context engineering is the deliberate practice of filling an LLM’s context window with the right information so it has a strong chance of solving the tasks you assign it. In an IDE setting, that means giving your coding agent “background awareness” of what your product is, along with your codebase tech stack, guidelines, and more.

LLMs do not automatically understand your codebase. To reason effectively, they must read files, call tools, infer structure, and piece together how everything fits. That discovery process consumes tokens and time. And when a session resets, that understanding disappears, forcing the agent to rebuild context from scratch.

Context engineering reduces this friction by ensuring the model receives the right information upfront or at the moment it’s needed. Instead of rediscovering your system repeatedly, the model operates with a stable understanding of your project’s boundaries and expectations.

Challenges Without Proper Context

  • Repeated discovery costs: The agent spends tokens re-exploring the repository to understand structure, dependencies, and architecture in every new interaction.
  • Violation of project conventions: Without explicit constraints, generated code may ignore naming conventions, folder structures, architectural patterns, or other important guidelines.
  • Shallow reasoning: Missing domain rules, product constraints, or architectural decisions lead to misaligned solutions.

Benefits of Agents.md and Agent Skills

  • Improved accuracy: Constraining the agent to your architecture and conventions significantly improves the quality of generated code.
  • Efficiency through just-in-time context: Instead of scanning the entire repository, the agent receives targeted, relevant information at the moment it needs it. This reduces token usage and speeds up execution.
  • Safer execution boundaries: Clearly defined skills and scoped responsibilities prevent agents from making unintended changes. They operate within guardrails rather than improvising across the entire codebase.

What Is agents.md?

AGENTS.md is a markdown file at the root of a repository that gives an agent spatial awareness of the codebase. When an AI coding agent starts a session, one of the first things it does its to find and read this file. It then uses its information found in this file as context throughout the session. Think of it as the counterpart to a README.md file — but written for coding agents rather than humans.

A well-written AGENTS.md will cover the project overview, the tech stack, architectural decisions worth knowing about, coding conventions, and any boundaries the agent should respect (for example, files it shouldn't modify or external services it shouldn't call).

This file continues to live in your repository and it’s instructions will persist across sessions. That said, you want to keep it lean. A bloated AGENTS.md wastes context window space and floods the agent with noise. The goal is to give the agent just enough orientation to work within our projects without needing to describe its internals every time.

What are Agent Skills?

While AGENTS.md gives the agent a lay of the land, Agent Skills give it specialized expertise for specific tasks. A skill is a folder containing a SKILL.md file along with any supporting examples, templates, or resources relevant to that domain. You might have a skill for frontend component design, another for writing database migrations, and another for your API integration patterns.

The key idea is progressive disclosure. The agent doesn't load every skill upfront. Instead, it pulls in the relevant skill when the task at hand calls for it, which keeps things efficient and focused.

Skill become particularly valuable for codebases that have repeatable workflows baked into them. Before pushing a feature, maybe you always run a type check, then a lint pass, then update the changelog. If you're relying on the agent to help with that process, you'd otherwise have to explain those steps each time. Package that process into a skill once, and the agent can reference it whenever it's relevant, without you repeating yourself.

Configuring AGENTS.md in Your IDE

The agents.md file lives at the root of your project and does not need any extra special configuration to start working — only that your IDE supports it. Almost all modern coding editors including VSCode, Cursor, and terminal UIs like OpenCode recognize this file and will include it in context at the start of an agent session. In this article, I’ll primarily be working with OpenCode.

Note: Claude Code uses a CLAUDE.md file for the same functionality but doesn't natively support AGENTS.md. You can work around this by referencing your AGENTS.md inside CLAUDE.md like this: @AGENTS.md. This lets you maintain one canonical agents file while making it accessible to Claude Code.

When an agent starts a new session, it reads the system prompt, user instructions and any relevant file in the project. If an AGENTS.md file exists, it becomes part of the context. This file heavily influences the agent’s view of the codebase.

Best practices for structuring an AGENTS.md file

A well-structured AGENTS.md follows a predictable shape. Not every project needs every section, but these are the sections I consistently find myself using:

  1. Project Overview: One or two sentences about what the product does and who it's for. Knowing the target users and core use case anchors every subsequent decision the agent makes.
  2. Agent Guidelines: Behavioral constraints unique to your project: which package manager to use, which branches not to push to, pull request rituals. These aren't things the agent can infer from code alone. They're team standards that need to be written down.
  3. Project Commands: A concise command reference. List dev, build, lint, and any project-specific scripts. The agent shouldn't have to read package.json every time it needs to run something.
  4. Technology Stack: Clearly list the language, framework, auth library, database, state management, styling and other tools that make up your project.
  5. Folder Architecture: Show a simple directory tree so the agent knows where things live. This reduces exploration and helps it place files correctly. Keep only the important structure, not every file.
  6. Code Style: Explain naming rules, import aliases, formatting, component patterns, and how styling is handled. This keeps generated code consistent and avoids large style refactors later.

Patterns from repeated agent behavior are also useful signals. If the same action, mistake, or clarification shows up across sessions, it can be worth capturing as a small rule in your agents file.

It’s also important to keep the AGENTS.md file concise. As it grows behavior becomes less stable, and context rot can appear. Around 200–400 lines (about 1,000–3,000 tokens) works well for me.

In larger repositories, especially monorepos, you can nest AGENTS.md files to help keep context focused. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence. The root file can hold global guidance, while packages or apps define their own local architecture and workflow rules.

Context Engineering your IDE in practice

To evaluate the effectiveness of the two context engineering techniques in question, we’ll run a few experiments on a codebase I built a while back with a friend. It was an attempt to build a reusable SaaS template with Next.js, TypeScript, and Auth.js (v5).

The application is a platform that connects professional dentists with patients. We only got it up to the authentication flow for the patient role before other obligations came in.

It’s in a good spot right now to experiment with AI. We’ll instruct a coding agent to implement Role-based access control (RBAC) so that both dentists and patients can log in to their respective dashboards with proper authorization. At the moment, only patients have access to a dashboard.

Each run is executed under identical conditions:

  • Model: Claude Sonnet 4.5
  • Task: Implement RBAC with an onboarding flow
  • Prompt: Same prompt across all runs
  • Repository state: Identical starting point — asides agents.md and skill files.

To evaluate performance, we’ll track the following metrics:

  1. Total tokens consumed
  2. Number of iterations required
  3. Number of tool calls made
  4. The turn in which the first correct implementation appears — this means the turn at which the agent first wrote implementation files, not when the feature first worked.

The experiment used this implementation prompt shown below:

markdown
# RBAC Implementation Plan (Onboarding Architecture)

You are working in a Next.js App Router project using Auth.js (v5) and Mongoose/MongoDB.

## Product Context

Dentist Direct is a dental appointment scheduling platform to link patients with professional dentists nearby.

Patients should be able to:

- View available appointment slots
- Book appointments with dentists
- Manage their bookings

Dentists should be able to:

- Manage their availability
- View booked appointments
- Access dentist-specific tools and controls

Currently, the application only supports patients. All users are treated the same after authentication. You must now introduce role-based access control (RBAC) to properly separate dentist and patient experiences.

There are exactly two roles: PATIENT & DENTIST

For now, focus only on the Google OAuth authentication implementation. Authentication and authorization must remain cleanly separated.

## Core Architecture (Required)

- Google OAuth authenticates users only.
- New users are created with role: null.
- After login:
  - If role === null → redirect to /onboarding
  - If role exists → redirect based on role
- Users without a role must NOT access any other protected route.
- You can enforce RBAC using:
  - Next.js Middleware
  - Server-side layout protection
- Role must be propagated into JWT and session.
- Do NOT assign role inside the OAuth callback.

## User Model Update

- Add a role field: Enum: PATIENT | DENTIST
- Role Default: null
- Ensure schema validation is correct.

## Onboarding Route (/onboarding)

Create a single-page onboarding flow.

### Access Rules

- Authenticated + role = null → allow
- Authenticated + role exists → redirect to correct dashboard
- Unauthenticated → redirect to /login

### UI Requirements

Must visually match the app’s existing theme.

Provide:

- Clear heading (e.g., “Select Your Role”)
- Role selection (radio or select)
- Short explanation of what each role means
- Submit button

### Submission Logic

- Use a server action or API route.
- Validate authenticated user server-side.
- Update role in MongoDB.
- Redirect:
  - PATIENT → /dashboard
  - DENTIST → /admin

All updates must be server-side.

## Admin Dashboard (/admin)

Create a simple dentist dashboard.

Requirements:

- Import and reuse the existing sidebar component.
- Render a simple home page inside /admin that clearly shows:
  - A message like: “Logged in as DENTIST”
  - The user’s name or email (draw inspiration from existing /dashboard)

This page is only for confirming RBAC works DO NOT over-engineer the UI. This route must be fully protected via layout-level server logic.

## Session Configuration (Required)

In Auth.js:

- Add role to JWT in jwt callback.
- Expose role via session.user.role in session callback.
- The role must always be accessible from: `session.user.role`

No client-side database lookups for role.

## Middleware Enforcement

Implement global middleware that:

- Redirects unauthenticated users to /login
- If authenticated AND role is null:
  - Allow only /onboarding
  - Redirect all other routes to /onboarding
- If authenticated AND role exists:
  - Allow access normally
  - Prevent users with a role from accessing /onboarding

Middleware acts as a global guard.

## Layout Protection Recap

`/admin` layout

- Only DENTIST allowed
- PATIENT → redirect /dashboard
- Unauthenticated → /login

`/dashboard` layout

- Only PATIENT allowed
- DENTIST → redirect /admin
- Unauthenticated → /login

`/onboarding` layout

- If role exists → redirect appropriately
- If role null → allow

Expected Flow

```
Google Sign-In
    ↓
User created (role = null)
    ↓
Redirect to /onboarding
    ↓
User selects role
    ↓
Role saved to DB
    ↓
Redirect to correct dashboard
```

You may notice that part of the prompt instructs the agent to implement RBAC using either Next.js middleware or server-side layout protection. On the surface this sounds reasonable, but it conflicts with the project's existing configuration.

The app uses Auth.js with a database session strategy, meaning session data is stored in MongoDB rather than encoded in a cookie. This creates a problem for middleware: Next.js middleware runs in the Edge runtime, a lightweight V8 environment that doesn't support Node.js APIs. The MongoDB adapter that Auth.js uses to look up database sessions depends on those APIs — specifically Node’s crypto function which was used to generate a random UUID. So calling auth() inside middleware throws a runtime error.

This caveat wasn’t included in to prompt to see how each session would respond. The agent skill prepared for this experiment (nextauth-authentication) explicitly documents this limitation and describes the correct workaround. The question was whether the skill's guidance would surface at the right moment to prevent the error proactively.

Experiment 1: No Added Context

Setup: Clean repository, no AGENTS.md, no skills loaded. Just the prompt.

Observations

The agent's first move was to spin up an exploration subagent — a task call to map the entire codebase before writing any code. That discovery run cost roughly 130k tokens and 10 API calls on its own, before a single file was written.

Assistant (Build · claude-sonnet-4.5 · 93.8s) Now let me explore the codebase to understand the current structure before implementing the changes. Tool: task Input: ```json { "subagent_type": "explore", "description": "Explore codebase structure", "prompt": "I need to understand the current project structure for implementing RBAC. Please find and report back:\n\n1. The User model location and current schema\n2. The Auth.js configuration file location and current setup\n3. The current middleware file (if any)\n4. The /dashboard route structure and layout\n5. The sidebar component location that needs to be reused\n6. Any existing TypeScript types for User/Session\n7. The overall app directory structure\n\nUse a \"medium\" thoroughness level. Return the file paths and key details about each." } ```

From there, the agent tried multiple enforcement strategies before settling on one. What it landed on was incompatible with the project's session setup: the conflicting database session strategy and Next.js middleware. After a couple more iterations and resolving an issue that triggered the mongoose.models to be undefined, the feature was implemented. The agent ran three debug iterations trying to resolve it.

Notes & Key Insight

The explore subagent is the most visible symptom of missing context. It's an expensive proxy for the situational awareness AGENTS.md is designed to provide upfront. Total tokens consumed: 2,480,627. Total API calls: 81. Estimated cost: ~$2.28.

Experiment 2: With AGENTS.md

Setup: Same repository, same model and same RBAC prompt but included the following AGENTS.md file:

txt
Project Overview
Dentist booking platform built with Next.js 14 App Router, TypeScript, and Auth.js (v5).

Agent Guidelines
- Use `pnpm` only; never `npm`.
- Never push to `main`, `master`, or an active dev branch unless explicitly asked; human reviews/pushes.
- Do not run build commands unless explicitly instructed (Ralph loop cases).
- Never add yourself as author, co-author, or committer.
- If a critical project change happens (new feature, auth flow, schema, major route), update `AGENTS.md` in the same task.
- In `AGENTS.md` updates, prioritize concision over grammar; short + clear wins.

Project Commands
- `pnpm dev`: run next.js dev server
- `pnpm turbo`: run dev server with turbo
- `pnpm build`: build next.js application

## Technology Stack

- **Package Manager**: pnpm
- **Framework**: Next.js 14 (App Router)
- **Language**: TypeScript
- **Authentication**: Auth.js v5 (`next-auth` 5.0.0-beta.15)
- **Database**: MongoDB
- **Data Modeling**: Mongoose
- **State Management (Client)**: Zustand
- **Styling**: Tailwind CSS

Folder Architecture
```txt
/
├── auth.ts                    # Auth.js v5 configuration
├── app/
│   ├── models/
│   │   └── userModel.ts       # Mongoose user schema
│   ├── api/auth/[...nextauth]/route.ts  # Auth.js route handler
│   ├── dashboard/             # Protected dashboard routes
│   ├── (auth)/                 # Auth pages (login, register, logout)
│   └── api/                    # API routes
├── lib/
│   ├── mongodb.ts             # MongoDB client connection
│   ├── connectdb.ts           # Database connection helper
│   └── sendVerificationRequest.ts  # Email verification
└── components/                # React components
```

Authentication
- Library: Auth.js v5 (`next-auth` 5.0.0-beta.15)
- Config: `auth.ts` (root)
- Providers: Google, GitHub, Email (nodemailer)
- Session Strategy: Database (via MongoDBAdapter)
- Session Duration: 5 days (432000 seconds)

Data Layer
- Database**: MongoDB
- Connection**: `lib/mongodb.ts` (singleton pattern with global for dev)
- ORM**: Mongoose

User Model
Defined at `app/models/userModel.ts`:

```typescript
interface UserDocument {
  firstname: string
  lastname: string
  email: string
  password?: string
  provider?: string
  appointments?: AppointmentDocument[]
}
```
- No roles field currently exists in the schema
- Appointments stored as embedded array

Code Style
- **Imports**: Use `@/*` path alias for src imports (e.g., `@/components/ui/button`)
- **Types**: Prefer `type` over `interface`; use TypeScript strict mode
- **Components**: Use functional components with typed props; extract prop types (e.g., `MessageProps`)
- **Formatting**: Prettier with default config; double quotes for strings
- **Class Names**: Use `cn()` utility from `@/lib/utils` to merge Tailwind classes with clsx
- **Variants**: Use `class-variance-authority` (cva) for component variants
- **Naming**: PascalCase for components, camelCase for functions/variables, kebab-case for files
- **Exports**: Named exports for components and utilities

Observations

The difference was immediate. Instead of spinning up an exploration subagent, the agent's first two actions were targeted read calls on userModel.ts and auth.ts — the two files most relevant to the task. The agent file provided enough context to skip the discovery phase entirely and begin implementation directly. However, having the right context upfront didn't eliminate all errors: the agent still hit the Edge runtime error when implementing middleware with database sessions, which required one debug iteration to resolve.

User: read and implement @rbac-plan.md --- Assistant (Build · claude-sonnet-4.5 · 11.3s) I'll implement the RBAC system with onboarding architecture as specified. Let me start by creating a comprehensive todo list to track this implementation. **Tool: todowrite** **Input:** ```json { "todos": [ { "content": "Update User model to add role field (PATIENT | DENTIST | null)", "status": "pending", "priority": "high" }, { "content": "Update Auth.js config to include role in JWT and session callbacks", "status": "pending", "priority": "high" }, / ** 6 more todos **/ } ``` --- Assistant (Build · claude-sonnet-4.5 · 6.6s) Now let me start implementing. First, I'll examine the current User model and Auth.js configuration. **Tool: read** **Input:** ```json { "filePath": "<project-path>/app/models/userModel.ts" } ```

It worked through all 8 todo items and only hit 1 error concern. The session ended with a clean build test passing. What stood out beyond the metrics was the UI quality. For some reason, this run produced the best onboarding page and admin dashboard of all three runs despite running the same model and same prompt as the others.

Notes & Key Insight

AGENTS.md removed the discovery phase entirely and went straight to reading the specific files needed for the task and then implementing. Looking at the exploration subagent from the first experiment, we’d notice that the data the agent requested for were already provided in the AGENTS.md file. The benefits are clear. Total tokens: 1,175,645. API calls: 42. Zero debug iterations. Estimated cost: ~$1.08. The cleanest session by every measure.

Configuring Agent Skills in Your IDE

Skills can be set up in two ways: per-project or globally. Project level skills live inside your repository at .agents/skills/. They're version-controlled alongside the codebase, and scoped to that project. This is the right setup for skills tied to a specific codebase — a migration workflow, a component scaffolding pattern, or project-specific testing conventions.

Global-level skills live at ~/agents/skills on your machine. These are available across every project on the machine and are the better default for skills that apply broadly: auth patterns, documentation workflows, or code review checklists.

Different agentic editors may also support their own native discovery paths. For example:

txt
# Claude Code / Claude-compatible editors
Project: .claude/skills/<name>/SKILL.md
Global:  ~/.claude/skills/<name>/SKILL.md

# OpenCode
Project: .opencode/skills/<name>/SKILL.md
Global:  ~/.config/opencode/skills/<name>/SKILL.md

# Gemini CLI / Gemini-compatible agent setups
Project: .gemini/skills/<name>/SKILL.md
Global:  ~/.gemini/skills/<name>/SKILL.md

In practice, I recommend using the agents folder name. It’s the most universal convention and works across multiple editors and agent runtimes, making your skills portable regardless of which tool you’re using.

Best Practices for creating skills

  1. Keep each skill focused on a single workflow: A skill should cover one clear domain — for example authentication setup, database migrations, or component scaffolding. When skills overlap heavily, agents receive conflicting signals about which one to use.
  2. Write a description that clearly signals when to use the skill: The description field is the primary trigger mechanism agents use to decide whether to load a skill. A good description should:
    • Use imperative phrasing: “Use this skill when…” rather than “This skill does…”
    • Focus on user intent, not internal implementation
    • Mention contexts where the skill applies even if the user doesn’t use exact keywords
  3. Structure the skill directory cleanly: Each skill is a folder containing at minimum a SKILL.md file with frontmatter (name and description) and the instructions. Supporting resources can live alongside it, for example:
    • scripts/ for executable utilities
    • references/ for extended documentation
    • assets/ for templates or sample files
    • Keep the SKILL.md focused on instructions and link to supporting files when needed.
  4. Test your skill’s triggering behavior: Don’t assume the description just works, verify it. Create a small set of test prompts and run them through your agent multiple times.
  5. Consider using a meta-skill for creating new skills: If you find yourself authoring skills often and you want a reliable way to create new skills, leverage Anthropic’s skill-creator skill.

As mentioned earlier, I used the nextauth-authentication skill in this experiment. It covers session strategies, provider setup, TypeScript type extensions, and critically, example patterns required when using database sessions alongside Next.js middleware.

Experiment 3: With Skills

Setup: Same repository, same model, same RBAC prompt and the AGENTS.md from the previous run. The nextauth-authentication skill was also installed globally in the ~/.agents directory. Run the command below in your terminal to install the skill and use the /skill command in your coding IDE to select it.

bash
npx skills add https://github.com/mindrally/skills --skill nextauth-authentication

Observations

This experiment used the same AGENTS.md file as Experiment 2, so the agent didn't need to run an exploration subagent. It proceeded directly with targeted file reads on auth.ts and userModel.ts, then began implementation.

The agent wrote the onboarding flow, admin dashboard, and middleware. But it made a critical mistake: the middleware imported and called auth() from @/auth — the full configuration with database adapter that relied on a Node.js API (crypto). This triggered an Edge runtime error:

Error: The edge runtime does not support Node.js 'crypto' module.

This was exactly the pattern the skill explicitly warns against. After I reported the error, the agent referenced the skill and applied the split-config pattern: creating an Edge-compatible auth.config.ts and updating the middleware to use it instead of the Node.js-dependent @/auth.

After reporting the Edge error, the agent created an edge-compatible split configuration (auth.config.ts) following the skill's recommended pattern. However, that approach was soon abandoned. The agent instead removed the split-config entirely, simplified the middleware to handle only public routes, and moved all authentication logic to server-side page layouts. This eliminated the Edge runtime conflict at the cost of architectural simplicity.

Two additional bugs then surfaced: a Mongoose model initialization error (TypeError: Cannot read properties of undefined (reading 'User')) caused by incorrect use of models.User instead of mongoose.models.User, and hardcoded callback URLs in the login forms that bypassed role checks. Both were resolved through targeted fixes: switching to a try-catch model initialization pattern and creating a /post-login routing page that checks user roles before redirecting. The feature worked by session end, though the final implementation diverged significantly from the skill's edge-compatible pattern.

Why didn't the agent catch the edge error ahead of time?

When I asked why it didn't proactively avoid this mistake despite having the skill in context, the agent admitted:

You're absolutely right to call that out. I apologize for not catching this critical incompatibility upfront. Even though I had both AGENTS.md (which specifies database session strategy) and the NextAuth skill (which warns about Edge runtime incompatibility) in context from the start, I failed to synthesize that information proactively.

Suspecting the initial prompt may not have been explicit enough, I ran a second experiment with a stronger instruction: "Use the attached NextAuth skill as authoritative guidance to implement @rbac-plan.md. Do not start coding until you have listed the skill constraints that affect this task and explained how your design satisfies them."

The agent did list the constraints upfront this time, including the Edge runtime incompatibility. But it still implemented middleware that called @/auth with database strategy. It hit the same crypto error later in the session.

Notes & Key Insight

The skill contained the exact guidance needed to avoid the Edge runtime trap: the split-config pattern for using database sessions with Edge middleware. The agent applied it only after the crash, not before.

What's telling is that even with an explicit instruction to analyze constraints before coding, the agent still made the same mistake. This suggests skills aren't a silver bullet. Their value depends heavily on how well the agent actually applies the content — and that remains inconsistent.

The final implementation was the most architecturally sophisticated of the three runs, with clean separation of concerns. But it also came at significant cost: 6,013,893 tokens across 108 API calls versus 1,175,645 tokens and 42 calls for the AGENTS.md session. Skills can elevate code quality, but they don't guarantee the agent will follow critical guidance proactively. Prompt engineering still matters.

Comparison Results & Notes

MetricNo ContextWith agents.mdWith Skills
Total tokens2,480,6271,175,6456,013,893
API calls8142108
File reads151325
New files written9610
File edits17623
Debug iterations3+13
First impl. turnTurn 5Turn 12Turn 1
Code sophisticationLowMediumHigh
Est. cost (API, claude-sonnet-4.5)$2.28~$1.08*~$5.57*

All three sessions ran on claude-sonnet-4.5. Costs calculated at $3/M input, $15/M output, $0.30/M cache read tokens.

The first implementation turn is also an interesting statistic. A lower number here doesn’t necessarily mean better. The Skills session started writing on Turn 1 but still needed 3 debug cycles to reach a working state. The AGENTS.md session didn't write until ~Turn 12, and required 1 debug iteration (Edge runtime fix) before working. The implementation was otherwise correct from the start.

What the numbers reveal: The AGENTS.md approach delivered the best ROI. It cut token usage by more than half compared to the no-context run, required minimal debugging (1 iteration), and produced largely correct code on the first implementation attempt. The Skills run, by contrast, consumed 6M tokens (5x the cost) because the agent front-loaded heavy context on every turn, even when irrelevant to the immediate task. Despite the cost, it produced the most architecturally correct code, suggesting skills shine when code quality is paramount and token budget is flexible. The no-context experiment ran without guidance, causing the agent to do a lot of work and thrash through multiple debugging cycles before eventually delivering a solution.

Practical Pitfalls When Using AGENTS.md and Skills

  1. Overloading context: A bloated AGENTS.md is as useless as none at all. When you pack in your README, outdated architecture notes, and every edge case you've ever hit, the genuinely important constraints get buried in noise. Prioritize brevity. If a section doesn't affect how the agent reasons or behaves on a given task, it probably doesn't belong there.
  2. Skill bloat: Skills work best when scoped tightly. A 2,000-line skill covering your entire auth system, component library, and API patterns front-loads everything regardless of what the task actually requires. If a skill is growing large, split it into smaller focused units.
  3. Unsafe shell access: Skills can trigger bash commands. Be careful about the skills you install online and deliberate what your skills ask the agent to execute automatically, especially anything destructive, network-dependent, or environment-modifying. Make execution boundaries explicit — what should run, and what should always wait for a human to confirm.
  4. Environment variable exposure: Skills that reference .env files or surface config values as part of a debugging workflow can leak credentials into session logs. Scope what the agent is allowed to read, and avoid patterns that pull sensitive values into the context window unnecessarily.

Conclusion

AGENTS.md and agent skills elevate your AI agent from one that just writes code to one that writes your code with your conventions, constraints, and architecture baked in. The experiments here show a real cost-quality tradeoff.

My advice if you want to see instant improvements in your AI workflow is to start with an AGENTS.md file. It's low effort, persists across sessions, and has an outsized impact on agent output quality. Layer skills on top for complex, domain-specific work where code quality justifies the token budget. As context engineering matures, expect more tooling — automated skill generation, IDE integrations that read your CI pipeline, and multi-modal context beyond text. The engineers who get the most out of agentic coding will be the ones who learn to curate context deliberately.

Building an engineering team?

I'm an experienced full-stack TypeScript engineer who enjoys architecting and building software applications while creating polished interfaces with enjoyable user experiences.

Schedule a chat

Connect With Me (:

You can easily connect with me through any of the platforms below. If you want to work together, lets have a chat!

Made with by Chinwike © All rights reserved.