# Aalmada Bookstore Agents Md

> AGENTS.md Skill

- Skill: `tomevault-io/aalmada-bookstore-agents-md` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/aalmada-bookstore-agents-md`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/aalmada-bookstore-agents-md/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/aalmada-bookstore-agents-md

---


# AGENTS.md Skill

`AGENTS.md` is the README for AI coding agents — it gives tools like GitHub Copilot, Cursor,
and Claude Code the context they need to produce code that fits your project, without
constant back-and-forth correction.

## The Golden Rule: Only Include Non-Obvious Things

This is the most important principle. Before adding any line, ask:
**"Could an agent figure this out by reading the code or config files?"**

If yes — skip it. Agents can read `package.json`, `pyproject.toml`, `*.csproj`, directory
structures, imports, and existing code. AGENTS.md is for the things that *aren't* visible there:

- Project-specific conventions not enforced by any linter or analyzer
- "Never do X" patterns that *look* reasonable but are wrong in this codebase
- Commands that are non-standard or require project-specific flags
- Domain terminology or architectural choices that need explanation
- Common mistakes agents actually make here (discovered from experience)
- Security constraints and rules that must never be violated

**Redundant content actively degrades quality** — it wastes the agent's context window and
dilutes real signal with noise it already has.

## Two Shapes of AGENTS.md

### Root-level `AGENTS.md` (repo root)

Covers the whole project: stack, layout, cross-cutting rules, major patterns, and a doc index.
Aim for ≤ 150 lines. Link to existing guides rather than duplicating them.
Include a short maintenance note telling agents to update related `AGENTS.md` files and
relevant `SKILL.md` files when a new non-obvious pattern is introduced or existing guidance is
stale, but to ask the user for permission before editing those guidance files.

### Component-level `AGENTS.md` (subdirectory)

Scoped to one module, package, or concern (e.g., `src/Api/`, `tests/`).
Create one when:
- The component has non-obvious rules not covered by the root file
- It has its own commands, stack, or lifecycle
- Agents working in that folder would benefit from a tightly-focused cheat sheet

**Don't create a component AGENTS.md just for completeness.** An empty or trivially short
file adds nothing — it just adds noise to the file tree.

---

## Root-Level Structure

```markdown
# <Project Name> — Agent Instructions

## Quick Reference
- **Stack**: List of key technologies
- **Solution/Entry point**: Main file or solution
- **Common commands**: `build`, `test`, `run`, `format` — exact, copy-paste ready
- **Docs**: Links to key guides

## Repository Map
Folder → one-line purpose. Skip folders whose purpose is obvious from the name.

## Major Patterns
Bullet list of architectural decisions agents must know:
- Why a pattern is used (not just that it's used)
- Any non-obvious integration approaches

## Code Rules (MUST follow)
✅/❌ table — see format below.

## Common Mistakes
Concrete anti-patterns agents get wrong in this codebase. Not generic advice.

## Quick Troubleshooting
"Symptom → fix" pairs for problems agents are likely to hit.
```

## Component-Level Structure

```markdown
# <Component Name> — Agent Instructions

## Quick Reference
- **Scope**: `path/to/component/**`
- **Stack**: Techs specific to this component (only if different from root)
- **Commands**: Commands specific to this component

## Key Rules (MUST follow)
✅/❌ table — see format below.

## Common Mistakes
What agents get wrong specifically inside this component.

## Project Layout
Table: path → purpose. Skip obvious paths.

## Quick Troubleshooting
Symptom → fix pairs.

## Documentation Index
Table: topic → guide path. Don't repeat links from root AGENTS.md unless critical.
```

---

## The ✅/❌ Rule Format

Rules work best as a short code block with ✅ for the right pattern and ❌ for the wrong one,
side-by-side. This format is instantly scannable and makes the do/don't unambiguous:

```
✅ Guid.CreateVersion7()          ❌ Guid.NewGuid()
✅ DateTimeOffset.UtcNow          ❌ DateTime.Now
✅ record EventPastTense(...)     ❌ record VerbCommand(...)
✅ [LoggerMessage(...)]           ❌ _logger.LogInformation(...)
```

Rules that belong here:
- API/library choices where the wrong option compiles fine but violates project policy
- Naming conventions that linters don't enforce
- Framework-level gotchas specific to this codebase

Rules to skip:
- Things already caught by error-producing analyzers (the build will stop them anyway)
- Generic best practices any senior dev knows ("don't hardcode secrets", "use async")
- Anything an agent would infer from reading existing code

---

## Content Priority Filter

Run every candidate line through this filter before including it:

| Question | If YES | If NO |
|----------|--------|-------|
| Would an agent deduce this from reading the files? | Skip | Include |
| Does a linter or analyzer already enforce this? | Skip | Include |
| Is this generic advice true of any codebase? | Skip | Include |
| Would an agent without this make a real mistake here? | Include | Skip |
| Is this specific to this codebase's conventions? | Include | Skip |

---

## Single Source of Truth

Don't duplicate content from README, wikis, or existing docs. Link to them:

```markdown
## Documentation Index
| Topic | Guide |
|-------|-------|
| Architecture | `docs/architecture.md` |
| Testing patterns | `docs/guides/testing-guide.md` |
```

This keeps AGENTS.md focused and avoids stale duplication. If two files say the same thing
and one gets updated, they immediately diverge.

---

## Treat It as Living Code

Update AGENTS.md in the **same PR** as the change it documents. If tests now require a
specific flag, a linter is added, or a pattern changes — the AGENTS.md update belongs in
that diff. If the change also makes a scoped `AGENTS.md` or a related `SKILL.md` stale,
update those guidance files too. Ask the user for permission before editing any guidance file.
Reviewers should check AGENTS.md freshness as part of code review.

---

## Checklist Before Saving

- [ ] Every ✅/❌ rule is non-obvious (an agent wouldn't know it without being told)
- [ ] No content duplicated from README or other docs — linked instead
- [ ] All commands are copy-paste ready, wrapped in backticks
- [ ] Root AGENTS.md ≤ 150 lines; component AGENTS.md ≤ 100 lines
- [ ] No generic advice ("write clean code", "handle errors")
- [ ] Each "Common Mistake" names a specific anti-pattern, not a vague category
- [ ] Root AGENTS.md tells agents to refresh related AGENTS/skills when guidance goes stale
- [ ] Root AGENTS.md tells agents to ask the user before editing AGENTS.md or SKILL.md files
- [ ] Every section passes the Content Priority Filter

---
> Source: [aalmada/BookStore](https://github.com/aalmada/BookStore) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-16 -->