ESProfiler Handbook
Contributing

Agentic Coding

Best practices on using agentic coding in your local development environment.

Agent Code Skills

We use agentic coding in our local development environment to help us write code faster and more efficiently. Skills can be used to help us write code, refactor code, and test code that is consistent with our company's standards and practices.

Overview

The .agents folder (such as the backend .agents folder located in your project workspace at .../backend/.agents) provides domain and stack-specific skills, instructions, and guidelines for AI coding assistants operating within ES Profiler codebases.

Rather than maintaining a single monolithic repository of AI instructions, ES Profiler uses focused, stack-specific agent repositories that clone directly into the root of local project workspaces.

Available Skill Repos

Intent & Architecture Rationale

Why Stack-Specific Repositories?

A common question when designing AI agent workflows is why we use dedicated repositories (e.g., stack-specific .agents repos) rather than a single unified skills repository containing subdirectories for Java, Frontend, Ops, etc.

Q: Why a 'skills for java' repo rather than a single generic 'skills' repo with nested subfolders?

A: Context Budget Optimization.

AI models operate with a finite context window (context budget). If a single generic repository containing skills for all languages, stacks, and tools is loaded into an agent, irrelevant skills are ingested into memory. This consumes valuable context budget, increases noise, and degrades agent reasoning performance.

By maintaining stack-specific .agents repositories and cloning them directly into the target project root, agents only load instructions directly relevant to the active workspace.

Key Benefits

  • Context Window Efficiency: Minimizes token usage by loading only relevant skills for the active project stack.
  • Direct Workspace Integration: Allows IDEs and AI assistants to automatically detect .agents/skills/ at the workspace root without manual configuration.
  • Maintainability & Scope: Teams managing services only need to maintain service-scope specific skills, while other teams manage un-related skills in separate scopes.

Local Development Setup

To use agent skills in your local development environment, clone the stack-specific .agents repository into the root directory of your project suite.

Backend Directory Layout Example

For backend multi-module Java development, the .agents folder is placed directly inside the root backend/ directory alongside all service modules. To do this, git clone the relevant skill repository (e.g. skills-for-java) into the relevant parent folder (e.g. backend/), then rename the folder to .agents.

backend/
├── .agents/
│   ├── README.md
│   └── skills/
│       ├── esp-project-summary/
│       ├── esp-testing-guide/
│       └── java-collection-utils/
├── api-cas/
│   └── pom.xml
├── api-ccs/
│   └── pom.xml
├── api-ces/
│   └── pom.xml
├── api-cps/
│   └── pom.xml
├── api-iengine-runner/
│   └── pom.xml
├── api-mfs/
│   └── pom.xml
├── api-pes/
│   └── pom.xml
└── platform-api/
    └── pom.xml
Always open the top-level root directory (backend/) in both your IDE and your AI Agent environment. This ensures the agent sees .agents/ as part of the root workspace context.

How Skills Move from Repo to Local Dev Agents

When an AI assistant or IDE agent opens the root project directory in your local dev environment, it automatically integrates the .agents repository:

  1. Automatic Skill Discovery: The agent discovers the available skills in .agents/skills/ (such as esp-project-summary, esp-testing-guide, and java-collection-utils).
  2. Context Activation: When performing relevant tasks (e.g., writing unit tests or refactoring collection usage), the agent loads the corresponding SKILL.md instructions into its active context.
  3. Execution According to Project Standards: The agent follows company-specific patterns, test conventions, and helper functions documented within the skill.

Agentic Best Practices

When authoring or maintaining skills within an .agents repository, follow these guidelines:

1. High Signal-to-Noise Ratio

Keep skill documentation (SKILL.md) clear, concise, and actionable. Avoid unnecessary verbosity to conserve the agent's context budget.

2. Single Responsibility Principle

Each skill folder inside .agents/skills/ should address a single domain, tool, or architectural pattern (e.g., esp-testing-guide for testing rules, java-collection-utils for utility patterns).

3. Clear Frontmatter & Description

Always include YAML frontmatter in SKILL.md files defining the skill name and description so agents can determine when a skill is relevant:

---
name: esp-testing-guide
description: Testing standards, mock patterns, and assertion best practices for backend Java services.
---

4. Provide Concrete Examples

Include short, runnable code snippets illustrating "Good" vs "Bad" practices rather than abstract guidance.

5. Keep Local Repositories Synced

Ensure team members periodically pull updates to their local .agents directory so local AI tools operate with the latest architectural standards.

Documentation

ESProfiler's platform documentation is hosted at https://docs.esprofiler.com. You can access it directly from any of our platform tenants by clicking Help > Documentation.

API Guidelines

This guide provides a set of guidelines for designing and implementing APIs in the back-end of ESProfiler

Copyright © 2026