# Agent Instructions

> Use when writing project instructions for a coding agent (CLAUDE.md, AGENTS.md, or equivalent). Covers what belongs in them, what does not, structure, and keeping them accurate as the project changes.

- **Type:** Skill
- **Install:** `agentstack add skill-nimadorostkar-claude-skills-collection-agent-instructions`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nimadorostkar](https://agentstack.voostack.com/s/nimadorostkar)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nimadorostkar](https://github.com/nimadorostkar)
- **Source:** https://github.com/nimadorostkar/Claude-Skills-collection/tree/main/skills/agent-tooling/agent-instructions
- **Website:** https://github.com/nimadorostkar/Claude-Skills-collection

## Install

```sh
agentstack add skill-nimadorostkar-claude-skills-collection-agent-instructions
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Agent Instructions

## Purpose

Write the project instruction file an agent reads before touching the codebase. Its job is to convey what the agent cannot infer and would get wrong — not to restate what it can read from the code.

## When to Use

- Setting up a repository for agent-assisted development.
- An agent that repeatedly makes the same wrong assumption about your project.
- Refreshing an instruction file that has drifted from reality.

## Capabilities

- Structuring project instructions for an agent audience.
- Identifying what an agent cannot infer.
- Encoding conventions, commands, and constraints.
- Keeping instructions accurate as the project evolves.

## Inputs

- The codebase, its conventions, and its build and test commands.
- The mistakes agents actually make in this repository.
- The things a new team member always has to be told.

## Outputs

- An instruction file that is short, specific, and correct.
- Commands that work, verified.
- Constraints that prevent the failures you have observed.

## Workflow

1. **Write down what an agent gets wrong** — Start from observed failures, not from a template. If the agent keeps running the wrong test command, that is the first line.
2. **State the commands exactly** — Build, test, lint, run. With the flags. An agent that guesses `npm test` when the project uses `pnpm test:unit` wastes a turn and may run the wrong thing.
3. **Encode the conventions that are not visible** — "We use `Result` types, not exceptions, in the domain layer." An agent can read the code, but it cannot tell a convention from a coincidence.
4. **State the hard constraints** — Never edit generated files. Never commit to main. Never modify the migration history. These prevent real damage.
5. **Keep it short** — This file is loaded on every session. Every line costs context. Ruthlessly cut anything the agent could work out for itself.
6. **Update it when it is wrong** — An inaccurate instruction file is worse than none, because it is trusted.

## Best Practices

- Do not restate what the code says. The agent can read `package.json`. It cannot know that the `test` script is broken and everyone uses `test:ci`.
- Commands must be verified. An instruction file listing a command that fails is a trap that costs a turn every session.
- Be specific about the boundaries: which directories are generated, which are vendored, which must never be edited by hand.
- Record the non-obvious architectural decision. "The `legacy/` module is being strangled; do not add to it, extend `orders/` instead" saves an agent from a well-intentioned wrong turn.
- A long instruction file is diluted. If it exceeds roughly 150 lines, most of it is not earning its place.
- Put project-specific conventions in the file and general engineering practice in skills. The instruction file is about *this* repository.

## Examples

**An instruction file that earns its tokens:**

```markdown
# Project instructions

## Commands
- Install:  `pnpm install --frozen-lockfile`
- Test:     `pnpm test:unit` (fast) / `pnpm test:integration` (needs Docker)
- Lint:     `pnpm lint --fix`
- Typecheck:`pnpm typecheck`
- Run:      `pnpm dev` (requires `.env.local`; copy from `.env.example`)

Do NOT run `pnpm test` — it is an alias for the full E2E suite and takes 25 minutes.

## Conventions
- Domain errors are returned as `Result`, never thrown.
  Exceptions are reserved for programmer error. See `src/shared/result.ts`.
- All money is `Money` (integer minor units). Never a float, never a number.
- Features may not import from other features. Shared code goes in `src/shared/`.
  This is enforced by ESLint; if you hit that rule, move the code rather than
  disabling the rule.

## Boundaries
- `src/generated/` is generated by `pnpm codegen`. Never edit by hand.
- `migrations/` is append-only. Never modify an existing migration, even to fix
  a typo — write a new one.
- `legacy/billing/` is being strangled. Do not add to it. New billing code goes
  in `src/features/billing/`.

## Gotchas
- The integration tests need Docker running. They will fail with a confusing
  connection error if it is not.
- `pnpm dev` binds to port 3000; if it is in use the error is silent and the
  server exits with code 0.
```

Every line here is something an agent would otherwise get wrong, and each one costs it a turn.

## Notes

- The single most valuable content is the "do not run X" line. Agents will find the obvious command and use it; the trap is when the obvious command is the wrong one.
- Treat the instruction file as code: review changes to it, and fix it the moment it becomes inaccurate. A stale line will be followed confidently.
- If the same correction is given to an agent twice in a session, it belongs in the file.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nimadorostkar](https://github.com/nimadorostkar)
- **Source:** [nimadorostkar/Claude-Skills-collection](https://github.com/nimadorostkar/Claude-Skills-collection)
- **License:** MIT
- **Homepage:** https://github.com/nimadorostkar/Claude-Skills-collection

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-nimadorostkar-claude-skills-collection-agent-instructions
- Seller: https://agentstack.voostack.com/s/nimadorostkar
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.