Add common agent skills

.agents/skills/ci-cd-and-automation/SKILL.md

@@ -0,0 +1,32 @@
+______________________________________________________________________
+
+## name: ci-cd-and-automation description: Keeps delivery workflows automated and repeatable. Use when adding checks, changing pipelines, or improving contributor onboarding.
+
+# CI/CD and Automation
+
+## Overview
+
+Prefer one-command local pipelines and CI parity so contributors can validate changes quickly and consistently.
+
+## Rules
+
+- If a check is required in CI, provide an easy local path to run it.
+- Keep commands discoverable in Poe tasks instead of ad-hoc docs only.
+- Prefer stable defaults and explicit failure signals.
+
+## Project convention
+
+- Maintain a complete local pipeline task: `uv run --frozen poe pipeline`
+- Keep focused tasks for:
+  - `uv run --frozen poe test`
+  - `uv run --frozen poe lint`
+
+## Change checklist
+
+1. Update `pyproject.toml` Poe tasks when checks change.
+1. Keep GitHub Actions and local tasks aligned.
+1. Verify full local pipeline before completion.
+
+## Verification
+
+- `uv run --frozen poe pipeline`

.agents/skills/code-review-and-quality/SKILL.md

@@ -0,0 +1,35 @@
+______________________________________________________________________
+
+## name: code-review-and-quality description: Runs a multi-axis quality review before merge. Use after implementation and before considering work complete.
+
+# Code Review and Quality
+
+## Overview
+
+Every non-trivial change should be reviewed across correctness, readability, architecture, security, and performance.
+
+## Five-axis review
+
+1. Correctness: does behavior match requirements and edge cases?
+1. Readability: is intent clear and maintainable?
+1. Architecture: are boundaries and abstractions appropriate?
+1. Security: are inputs validated and risky paths handled safely?
+1. Performance: any obvious regressions or expensive paths?
+
+## Rules
+
+- Fix critical issues before completion.
+- Keep feedback actionable and specific.
+- Prefer smaller, reviewable changes over large diffs.
+- Approve when the change clearly improves code health, even if not perfect.
+
+## Quality gates
+
+- Tests pass for changed behavior.
+- Lint/type checks pass.
+- No known high-severity defects remain.
+
+## Suggested commands
+
+- `uv run --frozen pytest`
+- `pre-commit run --all-files`

.agents/skills/debugging-and-error-recovery/SKILL.md

@@ -0,0 +1,38 @@
+______________________________________________________________________
+
+## name: debugging-and-error-recovery description: Systematic debugging workflow for failing tests, CI breakages, and runtime errors. Use when behavior is unexpected or a check fails.
+
+# Debugging and Error Recovery
+
+## Overview
+
+Use a disciplined triage loop: reproduce, localize, reduce, fix, and guard against regressions.
+
+## When to use
+
+- CI failures
+- Test regressions
+- Runtime exceptions
+- Template rendering or environment issues
+
+## Workflow
+
+1. Reproduce the issue with the smallest reliable command.
+1. Localize failure to a file, function, or boundary.
+1. Reduce to the minimal failing case.
+1. Implement the smallest safe fix.
+1. Add or update tests to prevent recurrence.
+1. Re-run relevant checks, then broader validation.
+
+## Rules
+
+- Do not patch blindly without reproducing.
+- Prefer evidence from logs, traces, and failing assertions.
+- Keep recovery changes scoped; avoid unrelated refactors.
+- If root cause is uncertain, state assumptions and verify them.
+
+## Suggested commands
+
+- Targeted tests: `uv run --frozen pytest tests/<target> -q`
+- Full tests: `uv run --frozen pytest`
+- Full quality gate: `uv run --frozen poe pipeline`

.agents/skills/incremental-implementation/SKILL.md

@@ -0,0 +1,35 @@
+______________________________________________________________________
+
+## name: incremental-implementation description: Delivers changes in thin, verifiable slices. Use when a task spans multiple files or feels too large for one safe change.
+
+# Incremental Implementation
+
+## Overview
+
+Build in small vertical slices: implement, test, verify, then continue. Each increment should keep the project in a working state.
+
+## When to use
+
+- Multi-file features
+- Refactors with risk
+- Any task where scope is likely to expand
+
+## Increment cycle
+
+1. Implement the smallest complete slice.
+1. Run relevant tests and checks.
+1. Verify behavior manually if needed.
+1. Commit or checkpoint.
+1. Move to the next slice.
+
+## Rules
+
+- Scope discipline: do only what the current slice requires.
+- Keep each increment reversible.
+- Avoid broad cleanups mixed with feature work.
+- Use safe defaults and feature flags when partial work must merge.
+
+## Verification
+
+- `uv run --frozen pytest`
+- `pre-commit run --all-files`

.agents/skills/learning-opportunities/SKILL.md

@@ -0,0 +1,129 @@
+______________________________________________________________________
+
+## name: learning-opportunities description: Facilitates deliberate skill development during AI-assisted coding. Offers interactive learning exercises after architectural work (new files, schema changes, refactors). Use when completing features, making design decisions, or when user asks to understand code better. argument-hint: "[orient]" license: CC-BY-4.0 source: "Adapted from DrCatHicks/learning-opportunities" source_url: "https://github.com/DrCatHicks/learning-opportunities/tree/main/learning-opportunities"
+
+# Learning Opportunities
+
+> Invocation argument: `$ARGUMENTS`
+
+## Purpose
+
+The user wants to build genuine expertise while using AI coding tools, not just ship code. These exercises help break the AI productivity trap where high velocity output and high fluency can lead to missing opportunities for active learning.
+
+## When to offer exercises
+
+Offer an optional 10-15 minute exercise after:
+
+- Creating new files or modules
+- Database schema changes
+- Architectural decisions or refactors
+- Implementing unfamiliar patterns
+- Any work where the user asked "why" questions during development
+
+Always ask before starting: "Would you like to do a quick learning exercise on [topic]? About 10-15 minutes."
+
+## When not to offer
+
+- User declined an exercise offer this session
+- User has already completed 2 exercises this session
+
+Keep offers brief and non-repetitive.
+
+## Core principle: Pause for input
+
+End your message immediately after the question. Do not generate any further content after the pause point.
+
+After the pause point, do not generate:
+
+- Suggested or example responses
+- Hints disguised as encouragement
+- Multiple questions in sequence
+- Any teaching content
+
+Allowed after the question:
+
+- Content-free reassurance: "(Take your best guess—wrong predictions are useful data.)"
+- Escape hatch: "(Or we can skip this one.)"
+
+Pause pattern:
+
+1. Pose a specific question or task.
+1. Wait for the user's response.
+1. Provide feedback connected to actual behavior.
+1. If prediction was wrong, clearly identify what was incorrect and explore the gap.
+1. Do not attribute insights the user did not express.
+
+## Exercise types
+
+### Prediction -> Observation -> Reflection
+
+1. Pause with a concrete prediction question.
+1. Wait.
+1. Walk through actual behavior.
+1. Pause for reflection on surprise and match.
+
+### Generation -> Comparison
+
+1. Ask user to sketch approach before showing implementation.
+1. Wait.
+1. Show actual implementation.
+1. Compare and discuss rationale.
+
+### Trace the path
+
+1. Use concrete values.
+1. Pause at each decision point.
+1. Wait before revealing each step.
+1. Continue through full path.
+
+### Debug this
+
+1. Present plausible bug or edge case.
+1. Pause: what breaks and why.
+1. Wait.
+1. Pause: how to fix.
+1. Discuss approach.
+
+### Teach it back
+
+1. Ask user to explain a component as if onboarding a new developer.
+1. Wait.
+1. Provide targeted feedback.
+
+### Retrieval check-in
+
+At start of returning sessions:
+
+1. Ask what they remember about a prior component/scenario.
+1. Wait.
+1. Fill gaps or confirm.
+
+## Facilitation guidelines
+
+- Ask if they want to engage before starting.
+- Honor response time and silence.
+- Adjust difficulty dynamically.
+- Keep exercises effortful but not frustrating.
+- Keep exercises to 10-15 minutes unless user wants deeper work.
+- Be direct about errors and non-judgmental in explanation.
+
+## Hands-on exploration defaults
+
+- Prefer directing users to files over pasting large code snippets.
+- Use completion-style prompts and fading scaffolding.
+- If struggling, increase scaffolding specificity rather than hinting answers.
+
+## Orientation mode (`orient`)
+
+If invoked with `orient`, run a guided repo orientation exercise instead of the default offer flow.
+
+Look for `resources/orientation.md` in this order:
+
+1. `.agents/skills/learning-opportunities/resources/orientation.md`
+1. `~/.agents/skills/learning-opportunities/resources/orientation.md`
+1. `.codex/skills/learning-opportunities/resources/orientation.md`
+1. `~/.codex/skills/learning-opportunities/resources/orientation.md`
+1. `.claude/skills/learning-opportunities/resources/orientation.md`
+1. `~/.claude/skills/learning-opportunities/resources/orientation.md`
+
+If no orientation file is found, stop and ask the user to generate one first.

.agents/skills/test-driven-development/SKILL.md

@@ -0,0 +1,43 @@
+______________________________________________________________________
+
+## name: test-driven-development description: Drives development with tests first. Use when implementing logic, fixing bugs, or changing behavior that must be proven.
+
+# Test-Driven Development
+
+## Overview
+
+Write a failing test before writing code that makes it pass. For bug fixes, reproduce the bug with a test first. Tests are proof.
+
+## When to use
+
+- Implementing new behavior
+- Fixing bugs (prove-it pattern)
+- Refactoring behavior with regression risk
+
+## Red-Green-Refactor
+
+1. Define expected behavior first.
+1. Write a failing test (RED).
+1. Implement the smallest change to pass (GREEN).
+1. Clean up without changing behavior (REFACTOR).
+1. Re-run tests after each meaningful change.
+
+## Prove-it pattern for bugs
+
+1. Reproduce the bug with a test.
+1. Confirm the test fails.
+1. Implement the fix.
+1. Confirm the test passes.
+1. Run broader tests to check for regressions.
+
+## Rules
+
+- Prefer state/output assertions over implementation-detail assertions.
+- Keep tests descriptive and behavior-focused.
+- Avoid skipping tests to make the suite pass.
+- Do not run the same command repeatedly without code changes in between.
+
+## Suggested commands
+
+- Targeted: `uv run --frozen pytest tests/test_main.py -q`
+- Full: `uv run --frozen pytest`

.github/PULL_REQUEST_TEMPLATE.md

@@ -24,7 +24,7 @@ Pre-commit checks will automatically run as part of opening this pull request an
 - [ ] Enhancement (adds functionality).
 - [ ] Breaking change (these changes would cause existing functionality to not work as expected).
 
-# Checklist
+## Checklist
 
 Please ensure that all boxes are checked before indicating that this pull request is ready for review.
 

AGENTS.md

@@ -0,0 +1,42 @@
+# Agent Guide
+
+This repository includes local agent guidance in `.agents/skills/`.
+
+## Where agent guidance lives
+
+- Root guide: `AGENTS.md`
+- Skills directory: `.agents/skills/`
+- Skill directories:
+  - `.agents/skills/test-driven-development/SKILL.md`
+  - `.agents/skills/incremental-implementation/SKILL.md`
+  - `.agents/skills/code-review-and-quality/SKILL.md`
+  - `.agents/skills/ci-cd-and-automation/SKILL.md`
+  - `.agents/skills/debugging-and-error-recovery/SKILL.md`
+  - `.agents/skills/learning-opportunities/SKILL.md`
+
+## How to use these skills
+
+- Load relevant skill(s) before making edits.
+- Prefer small changes with frequent validation.
+- Keep work aligned with this project's `pyproject.toml`, CI workflows, and pre-commit hooks.
+
+## Default execution order
+
+1. Apply `test-driven-development` when behavior changes.
+1. Apply `incremental-implementation` for multi-file or higher-risk changes.
+1. Apply `code-review-and-quality` as the final quality gate before completion.
+1. Apply `ci-cd-and-automation` when changing checks, tasks, or pipelines.
+1. Apply `debugging-and-error-recovery` when tests, CI, or runtime behavior fails unexpectedly.
+1. Optionally apply `learning-opportunities` for 10-15 minute learning exercises after design-heavy work.
+
+## Local commands
+
+- Run tests: `uv run --frozen pytest`
+- Run lint/format hooks: `pre-commit run --all-files`
+- Run type checks via pre-commit hook: `pre-commit run ty --all-files`
+- Run full local pipeline: `uv run --frozen poe pipeline`
+
+## Scope expectations
+
+- These instructions are project-local.
+- If team standards evolve, update these files in-place.

CITATION.cff

@@ -23,3 +23,18 @@ license: BSD-3-Clause
 identifiers:
   - type: doi
     value: "10.5281/zenodo.15518401"
+references:
+  - type: software
+    title: "agent-skills"
+    authors:
+      - given-names: Addy
+        family-names: Osmani
+    repository-code: "https://github.com/addyosmani/agent-skills"
+    license: MIT
+  - type: software
+    title: "learning-opportunities"
+    authors:
+      - given-names: Dan
+        family-names: Hicks
+    repository-code: "https://github.com/DrCatHicks/learning-opportunities"
+    license: CC-BY-4.0