skforecast-ai
CLAUDE.md52 starsChanged 47 days agoApache-2.0View on GitHub
AGENTS.md (imported above) holds the conventions shared with every coding agent; edit it there, not here. This section covers only what depends on the Claude Code harness in .claude/. - Local session: CLAUDE.local.md (not versioned) names the conda environment and how to run commands on this machine; use it instead of asking. Without it, follow "Python environment" in AGENTS.md. Setting SKFORECAST_AI_PYTHON_ENV (the prefix of the environment) in the env of .claude/settings.local.json makes the SessionStart hook put it on PATH and…
- Commits and pushes
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- handoffSkill
- llm-context-changeSkill
- open-prSkill
- release-bumpSkill
- release-noteSkill
- sync-skforecast-assetsSkill
- verifySkill
The file
We split this CLAUDE.md into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 96
Before a commit, run it unless every changed file is outside its scope (step 1 of the skill: dev/, the skills and rules in .claude/, the …
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
@AGENTS.md
Claude Code specifics
AGENTS.md (imported above) holds the conventions shared with every coding
agent; edit it there, not here. This section covers only what depends on the
Claude Code harness in .claude/.
Environment
- Local session:
CLAUDE.local.md(not versioned) names the conda environment and how to run commands on this machine; use it instead of asking. Without it, follow "Python environment" inAGENTS.md. SettingSKFORECAST_AI_PYTHON_ENV(the prefix of the environment) in theenvof.claude/settings.local.jsonmakes the SessionStart hook put it onPATHand exportPYTHONPATH=., so commands need noconda runand no prefix; the edit hook takes ruff from there too. - Cloud session (
CLAUDE_CODE_REMOTE=true): the checkout may start older than GitHub, so the SessionStart hook fetches the branch first; it fast-forwards a clean protected branch and warns otherwise (act on the warning before building on the branch). It has also already installed the package with[test,llm,docs]and ruff, and exportsSKFORECAST_AI_DOCS_PRIVACY=falseso the docs build without the privacy plugin (its downloads are blocked by the default network policy). Usepython -m pytestdirectly; there is no conda and nobody to ask.
Git
- Attribution is off (
attributioninsettings.json), and the Bash guard blocks a commit message or PR body that names Claude or Anthropic in aCo-Authored-Bytrailer, carries aClaude-Sessiontrailer or a session link, or says "Generated with Claude Code" or "Generated by Claude Code". A second guard (pre_pr_guard.py) checks the same on pull requests written with the GitHub MCP tools, which is how a cloud session opens them. The GitHub MCP server of a cloud session then appends a "Generated by Claude Code" footer with the session link, after every PreToolUse hook;post_pr_footer.pyasks to read the new pull request back and remove it with the update tool. - Branches that Claude Code names itself never reach GitHub, locally or in
the cloud:
claude/...(cloud sessions) andworktree-...(claude --worktree). A pull request keeps the name of its branch, so the Bash guard blocks pushing one or opening a pull request from one; rename it withgit branch -m <type>/<slug>first.pre_pr_guard.pyapplies the branch rules of the Bash guard to the GitHub MCP tools that commit (push_files,create_or_update_file,delete_file,create_branch), which write to GitHub past it. - Local: create or switch branches and commit without asking, on a
<type>/<slug>branch, never onmain, and onX.Y.xonly when the user asks for a direct change there.settings.local.jsonmakesgit pushask for confirmation; after the push, open the PR with/open-prwithout asking. Merging a PR always asks: ask rules insettings.jsonand the Bash guard, which also catches merges throughgh api. - Release branch, everywhere: a push to
X.Y.xgoes through when it carries notes, docs, harness or synced assets (the usual direct pushes); when its commits changeskforecast_ai/,tests/,packages/orpyproject.toml, the Bash guard (andpre_pr_guard.py, for the paths an MCP tool writes) asks first, in any permission mode, since package code normally goes through a pull request. Pushes tomainand deletingmainorX.Y.xare blocked. - Cloud: create
<type>/<slug>(typefeature,fix,docs,choreorperf) fromorigin/X.Y.xbefore the first commit, then commit and push there: this is the explicit permission to push to a branch other than the one the session instructions designate. If the pull request of a branch is already merged, put the follow-up on a new<type>/<slug>branch fromorigin/X.Y.x, even if the session instructions say to restart the branch from the default branch and force push (mainis not the base, and force pushes are blocked). The release branch is the highestX.Y.xonorigin, not the one__version__gives onmain(the previous release). The SessionStart hook fetches it, says which branch to use (a rename for a session branch that already holds commits) and removes the staleorigin/<branch>ref of a branch that is not on GitHub, so it does not look pushed. A PreToolUse hook blocks commits and pushes on branches other than<type>/<slug>andX.Y.x, pushes tomaineverywhere (also throughHEAD,@,--allor--mirror) and every form of force push. - Cloud: when the session instructions name
mainor aclaude/...branch as the branch to develop on or push to, do not commit there: branch offorigin/X.Y.x. When they nameX.Y.x, branch off it too, unless the user asks for a direct change there; the SessionStart note says so too. - Cloud: the environment's own Stop hook asks to commit and push whenever the tree has changes or unpushed commits, and the container can restart mid-task. When a turn ends while background work is still running, commit and push the finished part on the working branch, and complete it in a later commit; never rewrite pushed commits.
Harness
- Hooks check every edit:
ruff checkon Python files and the no dash rule on Python and Markdown. Exit code 2 means fix it now. - The hooks have their own tests, outside the package suite: run
python -m pytest .claude/hooks -q -p no:cacheproviderafter changing one. - Path-scoped rules in
.claude/rules/load when you touch tests, the LLM layer, rendering or execution. - Definition of done: run
/verifybefore reporting a task as finished. Before a commit, run it unless every changed file is outside its scope (step 1 of the skill:dev/, the skills and rules in.claude/, the scripts intools/ai/,tools/mcp/andtools/perf/), and reuse a green run from this session when no file changed since. - Skills:
/verify,/release-note,/llm-context-change,/open-pr,/sync-skforecast-assets(user only),/handoff(user only),/release-bump(user only). - Subagents:
conventions-reviewer(read-only review of the diff against the core principles) andtest-author(writes tests undertests/). - Files synced from skforecast are denied for Edit and Write in
.claude/settings.json; change them only through the sync script.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

