[ENH] Provide an Agent Skill for chainladder workflows

[EKtheSage]

Motivation

A growing number of users interact with Python libraries through AI coding assistants (Claude Code, Cursor, Codex, Gemini, etc.). When asked to perform chainladder tasks ("estimate ultimate losses on this triangle", "fit a Mack chainladder", "produce a development pattern"), these assistants currently rely on whatever they happen to know from training data, which is often outdated or incomplete.

A dedicated "Agent Skill" (a structured markdown file describing chainladder workflows in a format consumable by any AI assistant) would let users and their AI tools reliably reproduce the canonical chainladder workflow from data load to ultimate estimate.

What an Agent Skill is

Agent Skills are vendor-neutral markdown documents (typically named SKILL.md or similar) that describe how to use a library: setup, common tasks, code templates, and links to deeper docs. Claude Code, Cursor, Codex, and others consume them via convention. Some tooling (e.g. Posit's Great Docs) generates them automatically.

Proposed structure

A single SKILL.md (or .claude/skills/chainladder/SKILL.md for the Claude-specific path) at the repo root or in a dedicated skills/ directory, covering:

1. Setup: install via uv / pixi / pip; import conventions
2. Core workflow, end to end:
   • Load a triangle (built-in samples and custom DataFrames)
   • Inspect grain, shape, latest diagonal
   • Fit a development pattern (volume-weighted, simple, etc.)
   • Apply tail factors
   • Produce ultimate estimates (Chainladder, BornhuetterFerguson, CapeCod, MackChainladder)
   • Inspect results (link ratios, IBNR, ultimate, std_err)
3. Common variations: cumulative vs incremental, multi-LOB triangles, custom origin/dev formats, trailing periods
4. Pointers to canonical docs and tutorials for deeper exploration

Why now

• The skill pattern is new enough that no one has raised it yet, but adoption is accelerating across major Python libraries.
• chainladder is well-suited because the canonical workflow is well-defined (it follows a standard actuarial pipeline).
• It dovetails naturally with the Great Docs migration discussion in [DISCUSSION] Migrate documentation to Great Docs + GitHub Pages #716, since Great Docs produces Agent Skill output as a build artifact.

Scope of this issue

• Initial skeleton SKILL.md with the structure above (some sections will be rough drafts to be refined over time).
• Treat as an ongoing document: subsequent PRs would refine each section based on user/assistant feedback.

Happy to take this on as a starter PR if maintainers agree.

[kennethshsu]

From my super limited experience, these agent files are not super useful because most AI assistants already to know to crawl the GitHub page and this project's doc site sits on the same repo. I think a better use of these agent files would be to supplement "knowledge" that is proprietary (for example a company claims dictionary, or something that is unique to the project).

I think it would be redundant to include any of the publically available info again in these agent files. And more, if we were to do this, we would need to force the user on using a specific AI agent, which does not match well to the ethos of this package.

My humble vote is to close and not implement.

@EKtheSage, how did you bypass feature request template?

[jbogaardt]

I can see an agent skill as being valuable on the development side - specifically for enforcement of qualitative project standards. For example

1. Triangle methods should match pandas signatures where possible

2. Estimators must by scikit-learn compliant
   These are trivial, but there are more nuanced ones we can enforce.

3. code changes should consider broadening test coverage

4. Prefer the triangle public API in favor of using triangle internals when developing estimators

Things like this could ensure PRs generally align with the same ethos and i think that would lead to sustained cohesion of the entire package. As for end-user skills, I'd align with Ken's perspective.

[kennethshsu]

Well said @jbogaardt, I like that a lot, but I wonder if this should sit within the codebase or elsewhere, like something similar to Bugbot that reviews each PR?

@EKtheSage what are your thoughts?