Separate developer and user agent skills

[drbenvincent]

Summary

• Move user-facing CausalPy agent skills from .github/skills/ into causalpy/skills/ so they live with the source tree and can be distributed as user-facing guidance via Decision AI Hub.
• Keep developer/maintainer skills in .github/skills/, with .cursor/skills, .claude/skills, and .agents/skills continuing to symlink there for in-repo agent workflows.
• Add a causalpy/skills/README.md and update AGENTS.md, README.md, and Cursor command pointers to document the split between developer skills and user-facing skills.
• Remove the previous installer/CLI approach; end-user distribution is handled outside the package via Decision AI Hub.

Changed Skill Layout

• .github/skills/ now contains developer workflow skills only: environment setup, PR workflows, issue handling, review, and marimo workflows.
• causalpy/skills/ now contains user-facing CausalPy usage skills: designing-experiments, performing-causal-analysis, and running-placebo-analysis.
• performing-causal-analysis includes method references for difference-in-differences, interrupted time series, synthetic control, and regression discontinuity.
• The previous loading-datasets user skill was removed because causalpy.load_data() already documents available datasets directly.

Review Notes

• The user-facing skills are intentionally not auto-discovered in the contributor/developer context; this keeps CausalPy maintainer agents focused on repo workflow skills rather than end-user analysis guidance.
• If an agent is explicitly pointed at causalpy/skills/, the folder has a standard skill structure: each skill has a SKILL.md with YAML frontmatter and local reference links resolve.
• This PR does not try to perfect the skill content itself; deeper review of skill quality can happen in a follow-up PR.

Test Plan

• Confirm tracked skill files are split correctly between .github/skills/ and causalpy/skills/.
• Validate causalpy/skills/*/SKILL.md files have frontmatter with name and description.
• Validate local reference links from user-facing SKILL.md files resolve.
• prek passes in CI.
• Python tests pass in CI for 3.11 and 3.14.
• Notebook checks pass in CI.
• Read the Docs preview build passes.

Made with Cursor

[Copilot]

Pull request overview

This PR restructures “AI agent skills” so end-user skills ship inside the causalpy Python package (version-locked to the installed API), while maintainer/developer skills remain in .github/skills/. It also introduces a causalpy skills ... CLI to install those bundled skills into different AI-assistant platform configuration formats and adds a docs llms.txt generator.

Changes:

• Move 4 user-facing skills into causalpy/skills/ as packaged Markdown data.
• Add causalpy skills install|uninstall|list|check CLI plus platform adapters (Cursor/Claude/Copilot/Windsurf/Generic).
• Add make llms-txt to generate docs/source/llms.txt and expose it via Sphinx html_extra_path.

Reviewed changes

Copilot reviewed 21 out of 30 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
README.md	Document new “AI Agent Skills” and CLI usage.
pyproject.toml	Package causalpy.skills Markdown data and add causalpy console script entrypoint.
Makefile	Add llms-txt generator target for docs.
docs/source/conf.py	Include llms.txt in html_extra_path for static publishing.
causalpy/skills/init.py	Expose installer functions from the new causalpy.skills package.
causalpy/skills/_cli.py	Implement causalpy skills ... CLI subcommands.
causalpy/skills/_installer.py	Implement bundled-skill discovery, platform detection, install/uninstall, and version checking.
causalpy/skills/_generate_llms_txt.py	Generate concatenated llms.txt from bundled skills for docs hosting.
causalpy/skills/_platforms/_base.py	Define base adapter contract, version stamping, and removal helpers.
causalpy/skills/_platforms/cursor.py	Cursor adapter writes skills under .cursor/skills/causalpy-*/.
causalpy/skills/_platforms/claude.py	Claude Code adapter writes skills under .claude/skills/causalpy-*/.
causalpy/skills/_platforms/windsurf.py	Windsurf adapter writes skills under .windsurf/skills/causalpy-*/.
causalpy/skills/_platforms/copilot.py	Copilot adapter appends/removes a marked section in .github/copilot-instructions.md.
causalpy/skills/_platforms/generic.py	Generic adapter writes llms-causalpy.txt and provides build_llms_txt().
causalpy/skills/_platforms/init.py	Add platform adapters package marker/docs.
causalpy/skills/designing-experiments/SKILL.md	New bundled user skill content.
causalpy/skills/loading-datasets/SKILL.md	New bundled user skill content.
causalpy/skills/performing-causal-analysis/SKILL.md	New bundled user skill content.
causalpy/skills/performing-causal-analysis/reference/diff_in_diff.md	New user-facing reference doc for DiD.
causalpy/skills/performing-causal-analysis/reference/interrupted_time_series.md	New user-facing reference doc for ITS.
causalpy/skills/performing-causal-analysis/reference/synthetic_control.md	New user-facing reference doc for Synthetic Control.
causalpy/skills/running-placebo-analysis/SKILL.md	New bundled user skill content.
causalpy/skills/running-placebo-analysis/reference/placebo_in_time.md	New user-facing reference doc for Placebo-in-time.
AGENTS.md	Explain the new split between developer vs user skills and installation flow.
.gitignore	Ignore generated docs/source/llms.txt.
.cursor/commands/causalpy_research.md	Update command pointers to new causalpy/skills/ paths.
.cursor/commands/causalpy_methods.md	Update command pointers to new causalpy/skills/ paths.
.cursor/commands/causalpy_extras.md	Update command pointers to new causalpy/skills/ paths.
.cursor/commands/causalpy_estimators.md	Update command pointers to new causalpy/skills/ paths.
.cursor/commands/causalpy_demos.md	Update command pointers to new causalpy/skills/ paths.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[drbenvincent]

For the record: I’m gpt-5.5 acting on behalf of @drbenvincent.

Findings

• Must fix causalpy/skills/_platforms/_base.py: installed skill files get a version comment before YAML frontmatter. My targeted install check produced <!-- causalpy-skills v0.8.0 --> as line 1 and --- as line 2. Cursor/Claude/Windsurf-style skills commonly require frontmatter at byte 0, so this risks making the shipped user skills invisible to the agents they target. Put the stamp inside frontmatter, after the closing frontmatter block, or in a separate managed metadata file.

• Must fix causalpy/skills/_installer.py: platform auto-detection treats any .github/ directory as Copilot. That means causalpy skills install in most GitHub repos can silently create or rewrite .github/copilot-instructions.md, even when the user is only using Cursor/Claude/etc. For developer repos this is especially risky because .github usually means CI, not Copilot. Detect only an existing Copilot-specific file, or require --platform copilot.

• Must fix docs/source/conf.py, Makefile, .readthedocs.yaml: html_extra_path includes llms.txt, but the file is gitignored and RTD invokes Sphinx directly, not make llms-txt. The advertised stable hosted llms.txt URL therefore depends on an unrun generation step. Generate it during the docs build, commit it intentionally, or wire RTD/build config to create it before Sphinx reads html_extra_path.

• Must fix causalpy/skills/_installer.py and platform adapters: the new public CLI writes files, uninstalls files, mutates Copilot instructions, checks versions, and auto-detects platforms, but there are no tests under causalpy/tests/ for this surface. Add tmp_path pytest coverage for install/uninstall/check/list, frontmatter preservation, Copilot detection, and multi-platform behavior.

• Should fix causalpy/skills/_installer.py: check_version() returns the first installed version it finds. In a multi-platform repo, it can report “up to date” while another installed platform is stale. Since version-locking is the main value proposition for agent users, the check should report per-platform status.

• Should fix causalpy/skills/loading-datasets/SKILL.md and causalpy/skills/performing-causal-analysis/SKILL.md: moving these into the wheel makes them user-facing product docs for agents. The dataset skill omits many public datasets, and the analysis skill advertises RD but only links DiD/ITS/SC references. Before release, audit the skill content against the current API so agents don’t teach stale or partial workflows.

Merge Readiness

Verdict: request changes while draft.

Branch status: GitHub reports mergeable, draft, and blocked. CI was still pending when checked; prek and pre-commit were passing, several tests/docs jobs were pending.

PR Summary

The design direction is good: separating maintainer/developer skills from packaged user skills should reduce agent-context pollution for CausalPy contributors while giving end users version-matched agent guidance. The implementation needs tightening around the actual user-agent install path, especially frontmatter preservation, non-surprising platform detection, docs generation, and tests.

Test Evidence

I ran targeted checks in the CausalPy conda env for list_skills(), Cursor install/check/uninstall, and .github-only auto-detection. Those confirmed the frontmatter stamp problem and the broad Copilot detection behavior. Full local tests were not run; remote CI was still pending.

[read-the-docs-community]

Documentation build overview

📚 causalpy | 🛠️ Build #32838765 | 📁 Comparing 85c3e56 against latest (e40af27)

  🔍 Preview build  

2 files changed

± 404.html
± index.html

[drbenvincent]

Addressing GPT 5.5 review (219ed95)

Finding	Status	Commit
Must fix — version stamp before frontmatter	Fixed previously	5934f90
Must fix — .github/ treated as Copilot	Fixed previously (narrowed to require copilot-instructions.md)	2ee21c2
Must fix — RTD won't generate llms.txt	Fixed — conf.py now imports and runs generate() when the file is missing, so Sphinx builds (including RTD) produce it without make llms-txt	219ed95
Must fix — no tests	Fixed previously — 28 tests in test_skills_installer.py	5934f90
Should fix — check_version() returns first match	Fixed — now returns dict[str, str | None] mapping each platform to its installed version; CLI shows per-platform status	219ed95
Should fix — skill content gaps	Fixed — loading-datasets now lists all 21 datasets (8 synthetic + 13 CSV); performing-causal-analysis now includes RD reference with full API docs	219ed95

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.07%. Comparing base (e40af27) to head (85c3e56).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #927   +/-   ##
=======================================
  Coverage   95.07%   95.07%           
=======================================
  Files          87       87           
  Lines       13701    13701           
  Branches      812      812           
=======================================
  Hits        13026    13026           
  Misses        479      479           
  Partials      196      196           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.