atlas-package-cloner
Use Atlas to initialize Nim projects, install or update Atlas-managed dependencies, configure dependency directories, inspect Atlas-generated nim.cfg paths, handle Atlas overrides, features, plugins, lockfiles, and local Nim environments. Use when setting up or repairing Nim dependency workflows that use Atlas instead of Nimble's global package path.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 5
- Forks
- 2
01 前言 Front Matter
- name
- atlas-package-cloner
- description
- Use Atlas to initialize Nim projects, install or update Atlas-managed dependencies, configure dependency directories, inspect Atlas-generated nim.cfg paths, handle Atlas overrides, features, plugins, lockfiles, and local Nim environments. Use when setting up or repairing Nim dependency workflows that use Atlas instead of Nimble's global package path.
02 资源文件 3
- 参考文档references/custom_deps_and_overrides.md1.0 KB
- 参考文档references/features_and_replay.md822 B
- 参考文档references/start_project.md625 B
03 SKILL.md 正文
Atlas Package Cloner
Rules
Project State
- Treat either root
atlas.configor<deps>/atlas.configas Atlas config. Atlas prefers rootatlas.configwhen present, butatlas initcreatesdeps/atlas.configby default. - Use
atlas initfrom the project root to initialize Atlas state. - Use
atlas init --deps=DIRoratlas --deps=DIR initwhen the project intentionally uses a dependency directory other thandeps/. - After initialization, inspect
<deps>/atlas.config; the default config recordsdeps,nameOverrides,urlOverrides,pkgOverrides,plugins,resolver, andgraph. - Do not assume
atlas initcreatesnim.cfg. Atlas has code paths that patchnim.cfgwhen dependency operations need compiler paths.
Commands
- Use
atlas use <url|pkgname>to add a dependency. - Use
atlas installwhen the Nimble file already contains requirements and Atlas should materialize the dependency graph. - Use
atlas update [filter]to refresh dependency refs. Prefer a filter when only one dependency needs an update. - Use
atlas link <path>only for local project linking tasks; be prepared to inspect generated link files and the linked project's dependency graph state. - Use
atlas pin [atlas.lock]to pin current dependency checkouts. - Use
atlas rep [atlas.lock]to replay a lockfile.atlas replayandatlas reproduceare aliases. - Use
atlas --noexec rep [atlas.lock]when replay should avoid build actions that may run arbitrary code. - Use
atlas env <nimversion>for project-local Nim environments, for exampleatlas env 1.6.12oratlas env devel.
Package Names, URLs, And Indexes
- Package names are resolved through Atlas' package lookup table, populated from
packages.json, plus configurednameOverrides. - URL inputs are parsed as URLs and can be rewritten with
urlOverrides. - Forge aliases are valid package references:
| Alias | Expands to |
|---|---|
gh:user/repo or github:user/repo |
https://github.com/user/repo |
gl:user/repo or gitlab:user/repo |
https://gitlab.com/user/repo |
srht:user/repo or sourcehut:user/repo |
https://git.sr.ht/~user/repo |
cb:user/repo, cberg:user/repo, or codeberg:user/repo |
https://codeberg.org/user/repo |
- Atlas downloads
packages.jsoninto the package cache by default, usingpackages.nim-lang.orgwith GitHub fallback. - Use
--packagesRepoonly when the workflow needs the fullnim-lang/packagesgit repository behavior. - Use
--forceGitToHttpswhen dependency URLs needgit://rewritten tohttps://. - If a package name or URL resolves incorrectly, fix
nameOverrides,urlOverrides, orpkgOverridesin<deps>/atlas.configinstead of editing generated paths by hand.
Generated nim.cfg Paths
- Atlas'
nim.cfgpatcher uses this section shape:
############# begin Atlas config section ##########
--noNimblePath
--path:"deps/pkg"
############# end Atlas config section ##########
- Inspect the Atlas section in
nim.cfgwhen imports fail. - Preserve user-written content outside the Atlas begin/end section.
- Do not hand-edit generated
--pathentries as the first fix. Correct the dependency graph, package metadata, or config overrides instead.
Resolution And Overrides
- Atlas supports
MinVer,SemVer, andMaxVerresolver algorithms. - The generated default config uses
SemVer. - Set resolver policy in
<deps>/atlas.configor with--resolver=minver|semver|maxverwhen the task requires a specific policy. - Use
nameOverridesfor package-name-to-URL mapping. - Use
urlOverridesfor URL rewrite rules. - Use
pkgOverrideswhen multiple URLs conflict for the same package shortname. - Keep overrides in Atlas config so future
install,use,update, andrepcommands remain repeatable.
Features
- Atlas supports Nimble
featurestatements. - Pass feature flags explicitly with
--feature=<feature>. Pass multiple--featureoptions when multiple features are required, or use--features=<list>for a comma- or space-separated list. - Use
--allFeaturesonly when every declared feature should be enabled. - Use
--keepFeaturesor-kwhen the command should reuse feature defines from the currentnim.cfg. - Feature request flags populate runtime context; they are not saved as fields in
atlas.config. - In Nimble requirements, feature syntax has the shape
require "somelib[testing]".
Plugins And Build Actions
- Atlas plugins are
*.nimsfiles read from the project-relative directory configured by thepluginsfield. - Treat plugin execution as potentially arbitrary code execution because plugins can call external tools.
- Inspect the configured plugin directory before enabling plugins or replaying dependencies with execution enabled.
- Use
--noexecwhen the task only needs dependency graph setup or lockfile replay and build actions should not run.
Virtual Nim Environments
atlas env <version>creates a project-local Nim environment under the dependency directory.- After a successful env setup, activate it explicitly:
- Unix:
source deps/nim-<version>/activate.sh - Windows:
deps\nim-<version>\activate.bat
- Unix:
- Do not assume the virtual Nim environment is active in later shell sessions.
Workflow
- Inspect the project root.
Look for
*.nimble,nim.cfg,atlas.lock,deps/, and any custom dependency directory. - Locate Atlas config.
Check root
atlas.configfirst, then<deps>/atlas.config; if--depsor--confdiris in use, inspect that configured location. - Choose the Atlas command.
Use
init,use,install,update,link,pin,rep, orenvaccording to the task. Run commands from the project root unless--project=pathis intentional. - Check policy before changing dependencies. Read resolver, overrides, plugins, feature needs, lockfile state, and existing Nimble requirements.
- Run the smallest Atlas operation.
Use filters for targeted updates and
--noexecwhen arbitrary build actions should not run. - Verify generated state.
Inspect
<deps>/atlas.config,project.nimble,nim.cfg, andatlas.lockas applicable. Compile or test the smallest Nim target that imports the affected package. - Preserve reproducibility.
If the dependency set must remain stable, run
atlas pinafter successful setup and keep the lockfile with the project when that is the repository policy.
Task Examples
- For a new project that adds a dependency, read
references/start_project.md. - For custom dependency directories and overrides, read
references/custom_deps_and_overrides.md. - For feature flags, lockfiles, and replay, read
references/features_and_replay.md.
Common Mistakes
| Mistake | Why it is wrong |
|---|---|
Looking only for root atlas.config |
Verified atlas init writes deps/atlas.config by default even though root config is preferred when present. |
Assuming atlas init creates nim.cfg |
Verified init creates Atlas config only; dependency operations are what drive path patching. |
Editing generated nim.cfg paths first |
Atlas can regenerate that section; fix config, package metadata, or dependency resolution instead. |
| Enabling plugins without inspection | Plugins are NimScript files and may execute external commands. |
References
references/start_project.md— Atlas adoption: project setup, dependency addition, and compile flow.references/custom_deps_and_overrides.md— Custom dependency directories and URL overrides.references/features_and_replay.md— Optional features and lockfile replay commands.
04 同仓库更多 Skills
run-tests
Runs the project unit tests and validation suites.
nimonyplugins
Build and debug Nimony compile-time plugins for code generation and DSL rewrites. Use when replacing Nim macros with Nimony plugins, writing or reviewing template, for-loop, module, type, or import plugins, or diagnosing NIF traversal and generated output.
nim-testing
Write and run deterministic Nim tests, including isolated test files, expected-exception checks, multi-configuration builds, and sanitizer integration. Use when setting up a Nim test suite, testing failure behavior, running tests across debug/release/danger modes, or adding AddressSanitizer support.
nim-style-guide
Write clear, consistent Nim code in a simple stdlib-aligned style, covering imports, naming, proc vs func vs template choices, local variables, constructors, formatting, and control flow. Use when writing new Nim code or reviewing a Nim module for readability, consistency, and low-noise style decisions.
nim-ownership-hooks
Implement and review Nim ARC/ORC ownership hooks for types that manually manage resources, including move-only, deep-copy, refcounted, and copy-on-write patterns. Use when a Nim type owns pointers, buffers, file descriptors, or custom heap memory and you need correct `=destroy`, `=copy`, `=dup`, `=sink`, or move semantics.
nim-mcp-tools
Use for Nim symbol navigation, diagnostics, and type resolution. MANDATORY: Use specialized MCP tools (nimFindSymbols, nimFindReferences, nimListSymbols, nimCheckFile, nimCheckProject, nimFindTypeDefinition) first; fall back to grep only on error or user confirmation.