[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?

[EKtheSage]

I think the examples below show that both use cases are valid.

The PyMC skill is a good example of a user-facing canonical workflow. It does not merely repeat API docs. It guides the agent through Bayesian modeling steps: model specification, priors, inference, diagnostics, posterior predictive checks, and model comparison. That is directly analogous to a reserving workflow skill for chainladder. That is, a skill can encode a consistent, defensible workflow rather than relying on agents to piece it together from scattered docs.

On the other hand, the PyTorch skill is more in line with John's point above. It is more development-facing and helps agents work through issues in a project-specific way. This kind of skills can encode contributor standards and maintenance workflows.

So I do not think this is either user workflow or development workflow. For chainladder, I think both could be useful

• canonical actuarial workflows
• project standards, github workflows, debugging etc.

My vote would be to implement, but keep it narrow and avoid duplicating the docs.

[kennethshsu]

@EKtheSage sounds good. Thanks for following up again.

I think as next steps it could be interesting to see some initial drafts of this skill file and see an example of how it could be helpful.

In the first use case, wouldn't the user/actuary be the best person to do this? Or are you thinking about something that applies to every analysis?

In the second use case, I can see this being useful to the development team here. I think it was mentioned on the other ticket to document dev decisions made.

Would you be interested in leading one of both of these?

[EKtheSage]

Yes, I'd like to tackle this. But probably will be a lower priority. I really want to knock out some of the long-standing ones like documentation improvement and bugs first.