The superpowers of a software engineer

Learn your new powers. That is how I have been thinking about coding with AI. The models are stronger every month, and that can feel like losing control. The shift that helped me was simple. Agents do not replace judgment, they amplify it. They still need clear instruction, guardrails, and context, which are all things we already know how to provide.

Agents need to be instructed. The quickest way to start is to make your repo readable for a coding agent before anything else. A small set of instruction files gives the agent context about architecture, constraints, and skills. It is like onboarding a new teammate who reads a few documents, then starts shipping.

Agent instruction files you can add to a repo

There are a few emerging conventions that many tools already recognize. I have tried the ones below because they are simple to add and create an immediate improvement in code suggestions and refactors.

AGENTS.md

AGENTS.md is a lightweight convention for giving coding agents project context in plain Markdown. Think of it as a README for agents: one predictable place that tells any agent how to build, test, and contribute to your codebase.

Where it lives: at the repository root as AGENTS.md, with optional nested copies in subprojects (the closest file wins)
What it contains: plain Markdown with no required fields, typically build and test commands, code style guidelines, testing instructions, security considerations, and PR guidelines
When the agent reads it: agents locate the nearest AGENTS.md automatically when they start working on the repo; the convention is recognized by more than twenty tools, including Claude Code, Cursor, GitHub Copilot, and VS Code

# AGENTS.md

## Setup
- Install deps: `npm install`
- Start dev server: `npm run dev`

## Build and test
- Build: `npm run build`
- Test: `npm test`
- Always run `npm run lint` before committing

## Code style
- TypeScript strict mode on
- Validation with zod at boundaries
- Never return raw errors, map to typed problem responses

## Security
- Never log PII
- RBAC checks live in the service layer

## PR guidelines
- Title format: [scope] short description
- All checks must pass before review

SKILL.md

SKILL.md is the core file of an Agent Skill, an open format started by Anthropic for packaging a repeatable capability the agent loads on demand. Think "how to add an endpoint" or "how to write a migration" written for an agent. A skill is not a single file at the root: it is a folder with a SKILL.md inside, which can also bundle scripts, references, and templates.

Where it lives: one folder per skill, for example skills/add-rest-endpoint/SKILL.md, optionally next to scripts/ and references/ directories
What it contains: YAML frontmatter with at least name and description, followed by the instructions for performing the task
When the agent reads it: through progressive disclosure. At startup the agent loads only each skill's name and description; when a task matches, it reads the full instructions; during execution it can run bundled scripts or open referenced files

---
name: add-rest-endpoint
description: Add a REST endpoint under /v1/* with zod validation, RBAC, OpenAPI docs, and tests
---

# Add REST endpoint

Steps:
1. Define request/response schemas in `src/schemas/*.ts` using zod
2. Implement handler under `src/routes/{resource}.ts`
3. Enforce RBAC in service layer
4. Add OpenAPI spec and run `npm run openapi:gen`
5. Add tests in `tests/{resource}.spec.ts`

Acceptance:
- Tests pass
- OpenAPI docs updated
- Unauthorized access returns 403 with problem+json

CLAUDE.md

CLAUDE.md is read by Claude Code to understand your project context and preferences. It sets expectations about architecture, constraints, and style so the agent can generate code that fits the repo.

Where it lives: at the repository root as CLAUDE.md
What it contains: project overview, architectural map, coding preferences, dependencies, glossary, and explicit non goals
When the agent reads it: when Claude indexes or opens the repo, and whenever it needs guidance about structure or style

# Project overview
Service that exposes a REST API for document processing. Monorepo with `api/` and `worker/`.

# Architecture
- api: Fastify + Prisma, exposes `/v1/*`
- worker: BullMQ processing queue jobs
- db: Postgres 15

# Coding preferences
- TypeScript strict, functional helpers over classes
- Validation with zod at boundaries
- Errors mapped to RFC 7807 problem responses

# Security
- RBAC enforced in service layer
- Never log PII
- All inputs validated with zod

# Non goals
- No GraphQL
- No ORM migrations outside Prisma

Cursor skills

Cursor skills let you define reusable actions the editor can perform on demand. Cursor adopted the Agent Skills format described above, so a skill you write for Cursor is portable to other tools that support the standard.

Where it lives: a folder per skill under .cursor/skills/ or .agents/skills/ in the project, or under ~/.cursor/skills/ for personal skills available in every project
What it contains: a SKILL.md in Markdown with YAML frontmatter: a name matching the folder, a description that tells the agent when to use it, and optional fields like disable-model-invocation to require manual invocation
When the agent reads it: Cursor discovers skills at startup and applies them when the context matches; you can also invoke one explicitly by typing / and the skill name in Agent chat

---
name: add-zod-validation
description: Add zod schemas for incoming HTTP handlers and enforce parsing at boundaries. Use when a route lacks input validation.
---

For each handler in the selected files:
- Create a zod schema for request params, query, and body
- Parse inputs at the start of the handler
- Propagate typed results to the service layer

Acceptance:
- Handlers fail fast with 400 on invalid input
- Types inferred from zod flow through to callers

Reducing tokens without losing context

Strong agents are context hungry, and every token you send or generate costs money and window space. Two open source tools attack the bill from different angles: one makes the agent write less code, the other compresses what you send. Treat their headline numbers as directional. Real savings vary by codebase and prompt shape.

Ponytail

Ponytail is a plugin for coding agents that pushes back on over-engineering. Before writing any code, it walks the agent down a decision ladder: does this need to exist at all, can existing code, the standard library, or a dependency cover it, and only then write custom code.

Claimed reduction: the project reports about 54 percent less code (up to 94 percent on some tasks), roughly 20 percent cheaper and 27 percent faster runs, and about 22 percent fewer tokens than a no-skill baseline in its benchmarks
How it helps: less generated code to review and maintain, cheaper runs, and an agent that reaches for existing solutions before inventing new ones

Link to the project is in the references. An easy way to evaluate it is to give the agent the same feature task with and without the plugin and compare the diffs.

Caveman

Caveman is a token-efficiency toolkit for agent workflows: a compression workbench, a CLI, a memory offload system, and a spec-driven development kit. The compression side reduces verbosity in what you send to the model while keeping the technical details intact.

Claimed reduction: the site's headline claim is cutting 65 percent of your tokens, with an illustrative example showing 69 percent on an authentication task
How it helps: lets an agent hold more of a repository in working memory, which improves cross file reasoning and reduces back and forth retrieval

I would sanity check any compression pass by round tripping a few functions through the agent. If it restores them cleanly and the tests pass, you can be bolder with scope.

A practical path forward

The pattern here is not flashy. Put clear intent into the repo, then give the agent the smallest useful context that still preserves meaning. Start with one instruction file at the root. Add a single skill that matches a task you repeat every week. Try a token reduction pass on a small slice of the code. Each step is easy, and each one makes the agent feel more like a teammate you trust.