agents-md

Files (1)

• SKILL.md

SKILL.md (first lines)

When asked to create or update AGENTS.md for a repository, follow the procedure below.

## Goal
Create or update `AGENTS.md` for this repository.
The goal is a compact instruction file that helps future OpenCode sessions avoid mistakes and ramp up quickly. Every line should answer: "Would an agent likely miss this without help?" If not, leave it out.

## How to investigate
Read the highest-value sources first:
- `README*`, root manifests, workspace config, lockfiles
- build, test, lint, formatter, typecheck, and codegen config
- CI workflows and pre-commit / task runner config
- existing instruction files (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`)
- repo-local OpenCode config such as `opencode.json`
If architecture is still unclear after reading config and docs, inspect a small number of representative code files to find the real entrypoints, package boundaries, and execution flow. Prefer reading the files that explain how the system is wired together over random leaf files.
Prefer executable sources of truth over prose. If docs conflict with config or scripts, trust the executable source and only keep what you can verify.

## What to extract
Look for the highest-signal facts for an agent working in this repo:
- exact developer commands, especially non-obvious ones
- how to run a single test, a single package, or a focused verification step
- required command order when it matters, such as `lint -> typecheck -> test`
- monorepo or multi-package boundaries, ownership of major directories, and the real app/library entrypoints
- framework or toolchain quirks: generated code, migrations, codegen, build artifacts, special env loading, dev servers, infra deploy flow
- repo-specific style or workflow conventions that differ from defaults
- testing quirks: fixtures, integration test prerequisites, snapshot workflows, required services, flaky or expensive suites
- important constraints from existing instruction files worth preserving
Good `AGENTS.md` content is usually hard-earned context that took reading multiple files to infer.

## Questions
Only ask the user questions if the repo cannot answer something important. Use the `question` tool for one short batch at most.
Good questions:
- undocumented team conventions
- branch / PR / release expectations
- missing setup or test prerequisites that are known but not written down
Do not ask about anything the repo already makes clear.

## Writing rules
Include only high-signal, repo-specific guidance such as:
- exact commands and shortcuts the agent would otherwise guess wrong
- architecture notes that are not obvious from filenames
- conventions that differ from language or framework defaults
- setup requirements, environment quirks, and operational gotchas
- references to existing instruction sources that matter
Exclude:
- generic software advice
- long tutorials or exhaustive file trees
- obvious language conventions
- speculative claims or anything you could not verify
- content better stored in another file referenced via `opencode.json` `instructions`
When in doubt, omit.
Prefer short sections and bullets. If the repo is simple, keep the file simple. If the repo is large, summarise the few structural facts that actually change how an agent should work.
If `AGENTS.md` already exists at `/home/project/woolset`, improve it in place rather than rewriting blindly. Preserve verified useful guidance, delete fluff or stale claims, and reconcile it with the current codebase.

### What good looks like
When deciding whether to keep a piece of information, use this litmus test:
- **Every line answers:** “Would an agent likely miss this without help?”
- **Prefer conventions that differ from framework/language defaults**  
  (e.g., “Zustand stores, not React Context”, “file‑based TanStack routes”, “cart persisted via `zustand/middleware`”).

Examples of high‑signal items that should always survive an edit:
- Non‑obvious install flags like `--legacy-peer-deps`
- Code‑gen commands an agent can’t guess (e.g., `npx tsr generate`)
- Strict compiler/linter settings that break common patterns (`erasableSyntaxOnly`, `noUnusedLocals`)
- Framework‑specific configuration that deviates from the standard template (Tailwind v4 `@theme inline`)
- A crisp table of common commands (build, test, lint, typecheck)

Examples of what to **remove without hesitation**:
- Verbose “anti‑pattern” essays
- Generic language tutorials copy‑pasted from official docs
- Duplicated diagrams already visible in `globals.css` or other design‑system files
- Soft “lessons learned”, “known issues”, “next steps” – anything speculative or self‑referential
- Content that belongs elsewhere (e.g., `README.md`, a dedicated design doc)

From nordeim/neo-crm, MIT.