agents: add code review and debugging skills (#453)

* agents: add code review and debugging skills

* agent: rename debug skill to workflows to clarify intent

Author: morelucks

.claude/skills/review/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: review
+description: Quick-reference checklist for code review conventions in leanSpec
+---
+
+# /review - Code Review Checklist
+
+A concise checklist distilled from CLAUDE.md for reviewing leanSpec code.
+
+## Imports
+
+- All imports at file top — no lazy imports inside functions
+- No confusing renames — use qualified access (`x25519.X25519PublicKey`)
+- `from __future__ import annotations` in every file
+
+## Type Annotations
+
+- Never quote annotations when `from __future__ import annotations` is present
+- Prefer narrow domain types (`Bytes32`, `PeerId`, `RequestId`) over raw `bytes`
+- Complete type hints on all function signatures
+
+## Code Style
+
+- Line length: 100 characters max
+- Google docstring style
+- No example code in docstrings — unit tests serve as examples
+- No section separator comments (`# ====`, `# ----`)
+- Module-level constants use docstrings, not comments
+
+## Documentation
+
+- Never use explicit function or method names in docs — names change
+- Write short, scannable sentences — one idea per line
+- Use bullet points or numbered lists for multiple items
+- Never remove existing documentation unless directly invalidated by a code change
+
+## Testing
+
+- Full equality assertions — assert the whole object, not individual fields
+- Descriptive test names explaining the scenario
+- Use `pytest.raises(ExceptionType, match=r"...")` for error tests
+- Boundary values derived from source constants, never hardcoded
+
+## Architecture
+
+- No backward compatibility code — no shims, aliases, or re-exports
+- No unnecessary abstractions — inline is often better for spec code
+- Simplicity over abstraction — readers should understand top-to-bottom
+- SSZ types: domain-specific names (`Attestations`) over generic (`List4096`)
+
+## Before Committing
+
+```bash
+uvx tox -e fix        # Auto-fix formatting
+uvx tox -e all-checks # Verify all checks pass
+```

.claude/skills/workflows/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: workflows
+description: Common developer workflows, commands, and troubleshooting for leanSpec
+---
+
+# /workflows - Repository Workflows
+
+Common developer workflows and commands for working in leanSpec.
+
+## Running Specific Tests
+
+```bash
+# Single test file
+uvx tox -e pytest -- tests/lean_spec/subspecs/networking/discovery/test_transport.py -v
+
+# Single test class or method
+uvx tox -e pytest -- -k "TestDiscoveryTransport::test_start" -v
+
+# With print output visible
+uvx tox -e pytest -- -s -k "test_name"
+```
+
+## Resolving Type Errors
+
+The project uses two type checkers. Run them separately to isolate issues:
+
+```bash
+# Full type check (ty — the primary checker used in CI)
+uvx tox -e typecheck
+
+# Lint check (ruff — catches style and import issues)
+uvx tox -e lint
+```
+
+Common type error patterns:
+- `invalid-assignment` — Wrong type assigned; check if a domain type (`RequestId`, `PeerId`) is expected instead of raw `bytes`
+- `invalid-argument-type` — Function argument type mismatch; verify the function signature
+- `union-attr` — Accessing attribute on a possibly-`None` value; add an `assert is not None` guard
+
+## Inspecting Coverage
+
+After running tests, coverage reports are generated:
+
+```bash
+# View coverage in terminal
+uvx tox -e pytest
+
+# Open HTML report
+open htmlcov/index.html
+```
+
+## Running Interop Tests
+
+Interop tests are excluded from the default test run. Run them explicitly:
+
+```bash
+uv run pytest tests/interop/ -v
+```
+
+## Spell Check Failures
+
+```bash
+# Run spell check
+uvx tox -e spellcheck
+
+# Add legitimate words to the ignore list
+echo "newword" >> .codespell-ignore-words.txt
+```
+
+## Markdown Formatting
+
+```bash
+# Check markdown formatting (docs only)
+uvx tox -e mdformat
+```
+
+## Common Pitfalls
+
+- **Tests pass locally but CI fails**: CI runs checks across Python 3.12, 3.13, and 3.14. Ensure no version-specific syntax is used.
+- **`ruff format` changes after `ruff check --fix`**: Always run format after fix — the fixer doesn't guarantee formatting compliance.
+- **Import ordering issues**: Run `uvx tox -e fix` to auto-sort imports.