diff --git a/.agents/skills/writing-tests/SKILL.md b/.agents/skills/writing-tests/SKILL.md
new file mode 100644
index 0000000..179e5f5
--- /dev/null
+++ b/.agents/skills/writing-tests/SKILL.md
@@ -0,0 +1,25 @@
+---
+  name: writing-tests
+  description: Instructions and guidance on writing tests
+---
+## Location
+- tests are in `tests/`.
+- doctests can be used instead of unit tests if the doctest fully covers the function/method's functionality.
+- fixtures shared by the whole suite are located in `tests/conftest.py`; fixtures shared by the tests of one package are located in the `conftest.py` of that package's test directory.
+
+## Framework
+- tests should assume use of the `pytest` framework.
+- use appropriate features of the `pytest` framework, to include fixtures and mocking.
+- a fixture that returns a class is named in CapWords, as a class is; every other fixture is named in snake_case.
+
+## Creating Test Datasets
+- define test data to include values at the limits of where the output of tested functions/methods changes.
+
+## Writing tests
+- tests should be written to test the INTENDED implementation with a focus on finding bugs.
+- NEVER assume that the implementation is correct and that a test should pass.
+- always test on and either side of limits where output changes.
+- always seek to identify and test edge cases.
+
+## Documentation
+- if including a docstring for a test then docstring should start with an imperative, for example 'Verify' or 'Test'.
diff --git a/AGENTS.md b/AGENTS.md
index eed7787..f6160c4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,6 +30,8 @@ See @pyproject.toml for project metadata and dependencies.
             SKILL.md
         update-agents-md/
             SKILL.md
+        writing-tests/
+            SKILL.md
 .github/                          # GitHub configuration and CI/CD workflows
     workflows/
         build-test.yml            # Runs full test suite on platform/python matrix
@@ -212,6 +214,10 @@ def my_func(param1: int, param2: str = "default", param3: None | str = None) ->
     """
 ```
 
+#### Documentation content
+
+- when **revising documentation to reflect changes in implementation**, do NOT fall into the trap of documenting what's 'not the case' in the context of the previous implementation. Rather, just document what *is* the case, in the context of the revised implementation. Documentation that describes what the implementation does NOT do, in terms of a prior or erroneous implementation, is irrelevant and obfuscating to a reader who never knew of that prior implementation. Only ever make comparisons to erroneous or prior implementations if there is GOOD REASON to fear regression!
+
 ### Comments
 
 - pay particular attention to comments starting with...: 
@@ -226,8 +232,13 @@ def my_func(param1: int, param2: str = "default", param3: None | str = None) ->
 ## Important Notes for AI Agents
 
 1. **NEVER DO RULES**:
-	- Never edit the file `src/valimp/_version.py` - this is auto-generated by the build process.
+    - NEVER schedule a check-in unless specifically asked to.
+    - Never edit the file `src/valimp/_version.py` - this is auto-generated by the build process.
+
+2. **Do not assume that the package is coherent or free of bugs**, or that tests or documentation should be treated as gospel. If you come across a contradiction or a conflict or what you believe to be a bug, then say so.
 
-2. **NumPy docstring style** — all new public functions/classes must use NumPy-convention docstrings and rules as defined under Docstrings section of this @AGENTS.md file.
+3. **NumPy docstring style** — all new public functions/classes must use NumPy-convention docstrings and rules as defined under Docstrings section of this @AGENTS.md file.
 
-3. **Branch naming** — git branches should follow the pattern `<llm_name>/<description>` where the `<llm_name>` placeholder should be replaced with your colloquial name.
+4. **Branch naming** — feature branches should follow the `<agent-name>/<description>` pattern with the following substitutions:
+    - `<agent-name>` -> your name
+    - `<description>` -> very short description of changes