项目项目脚手架
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 安全
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Node.js · Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
接受`<slug> [--scope @your-org] [--ts-only|--py-only|--both] [--dry-run]`形式的`$ARGUMENTS`。如果缺少`<slug>`,请通过`AskUserQuestion`询问。验证它是 kebab-case (`^[a-z][a-z0-9-]*$`);否则拒绝并出现明显错误。从`<slug>` (`s/-/_/g`) 派生出`<snake_pkg>`。
在 cwd 上运行 `Glob`。如果目录为空(或仅包含 `.git/`、`LICENSE`、`README.md`),则继续使用新的脚手架。如果`packages/ts/`或`packages/py/`已经存在,请勿覆盖。遍历`references/reference-structure.md`中的布局并报告丢失的文件 - 只写入丢失的文件,保留现有的
按此顺序,从 `references/templates/`: `root-README.md` → `README.md` `root-SPEC.md` → `SPEC.md`(有意为存根 - 用户填充行为;结构是该技能提供的)`root-LICENSE` → `LICENSE`(如果已经存在则跳过)
对于 TypeScript(当`--both` 或 `--ts-only` 时):源 · 目标 `packages-ts/package.json` · `packages/ts/package.json` `packages-ts/tsconfig.json` · `packages/ts/tsconfig.json` `packages-ts/Makefile` · `packages/ts/Makefile`
源 · 目标 `tests-parity/fixtures.json` · `tests/parity/fixtures.json` `examples/README.md` · `examples/README.md` `examples/sdk-README.md` · `examples/sdk/README.md` `examples/api-README.md` · `examples/api/README.md`
写入后,运行冒烟检查:第一次运行将在奇偶校验测试中失败(固定装置文件是存根),并且可能在冒烟测试中失败(公共表面为空)。这是预料之中的——该技能产生一个结构上完整的存储库,而不是行为上完整的存储库。清楚地报告故障,以便
发出一个简短的摘要:已解决的占位符(`<slug>`、`<snake_pkg>`、`<scope>`)。写入的文件(计数,按树分组)。文件被跳过,因为它们已经存在。烟雾结果(`make ci-install`退出,`make ci`退出,
# Polyglot Project Scaffold (TS + Python twins)
Generate the canonical layout for a polyglot library that ships as two
language twins — TypeScript (`packages/ts/`) and Python (`packages/py/`) —
governed by a single behavioral spec and proven by a shared cross-language
parity fixture.
The shape is intentionally open-source-friendly: no internal organization
scopes, no agent-runtime paths, no plan-tree dependencies. Every file
written is something a downstream user can publish to npm + PyPI or fork
into their own repo.
## When to use this skill
- Starting a new library and you want it to have **TypeScript + Python**
surfaces from day one with parity enforced by tests, not vibes.
- Porting a single-language library to a twin (e.g. you have the TS but
want the Python twin) and want the cross-language scaffolding —
`SPEC.md`, parity fixtures, `examples/{sdk,api}/`, root `Makefile` —
in place before the port.
- Auditing or normalizing an existing two-language repo: comparing the
current state against `references/reference-structure.md` and writing
the missing load-bearing files.
Skip when:
- The work needs more than two languages, or a non-library shape (CLI,
service, multi-package monorepo). Use a different skill for those.
- The repo is already a polyglot SDK with full client/transport/
middleware/retry layering — that's the SDK paradigms canon, not a
library scaffold. Use `sdk-paradigms-scaffold` instead.
- You have a feature/story/task plan tree and want plan-driven
implementation — use `implement-polyglot-project-plan` (sibling skill,
not part of this open-source pattern).
## Reference structure
The canonical layout this skill produces:
```
<repo-root>/
├── README.md # repo intro + per-language quick start
├── SPEC.md # canonical behavior — both ports MUST conform
├── LICENSE # MIT (or user-supplied)
├── Makefile # root orchestrator: ci, ci-ts, ci-py, clean
├── package.json # npm workspace marker (workspaces: ["packages/ts"])
├── pyproject.toml # Python layout marker (no build, points at packages/py)
├── .gitignore # Node + Python + IDE/OS + env ignores
├── .agent.md # LLM entry reference (root index)
├── .agent.json # machine-readable counterpart of .agent.md
├── .agents/
│ └── parity.md # twin drift catalog + intentional asymmetries
├── packages/
│ ├── ts/
│ │ ├── package.json # the publishable npm package
│ │ ├── tsconfig.json # strict TS config
│ │ ├── Makefile # help/install/ci-install/test/lint/build/pack/clean/distclean/ci
│ │ ├── .agent.md # per-package LLM skill file
│ │ ├── src/
│ │ │ └── index.ts # public surface — re-exports only
│ │ └── test/
│ │ ├── smoke.test.ts # the package loads + exports the surface
│ │ └── parity.test.ts # consumes ../../tests/parity/fixtures.json
│ └── py/
│ ├── pyproject.toml # the publishable PyPI package
│ ├── Makefile # uv-aware; falls back to pip+pytest on bare runners
│ ├── README.md # 1-line pointer to the TS twin
│ ├── .agent.md # per-package LLM skill file
│ ├── <snake_pkg>/
│ │ ├── __init__.py # public surface — re-exports only
│ │ └── py.typed # PEP 561 marker
│ └── tests/
│ ├── __init__.py
│ ├── _helpers.py # env-isolation utilities for tests
│ ├── test_smoke.py # the package loads + exports the surface
│ └── test_parity.py # consumes ../../tests/parity/fixtures.json
├── tests/
│ └── parity/
│ └── fixtures.json # shared cross-language behavior fixtures
└── examples/
├── README.md
├── sdk/
│ ├── README.md # programmatic embedding scenarios
│ └── 01-<scenario>.md # side-by-side TS + Python code per scenario
└── api/
├── README.md # per-function contract reference
└── 01-<entry>.md # signature, inputs, errors per entry
```
See `references/reference-structure.md` for the field-by-field inventory.
## Placeholders
Templates use these placeholders. Resolve every one before writing:
| Placeholder | Meaning | Example |
| ---------------- | ------------------------------------------------------ | ----------------------------- |
| `<slug>` | Kebab-case package name (used for npm + PyPI names) | `my-lib` |
| `<snake_pkg>` | Python module directory / import name | `my_lib` |
| `<scope>` | Optional npm scope (drop for a flat name) | `@your-org` or empty |
| `<repo-name>` | Top-level repo folder name | `my-lib` |
| `<author>` | Author name in package metadata | `Jane Doe` |
| `<subject>` | One-phrase domain descriptor for README/SPEC intros | `concise tagline of behavior` |
| `<surface-list>` | Comma-separated public symbols (used in `.agent.md`) | `doThing, doOtherThing, ...` |
Conventions:
- `<slug>` and the npm name match directly. With a scope, the npm name is
`<scope>/<slug>` (e.g. `@your-org/<slug>`). Without a scope, both
npm and PyPI publish as `<slug>`.
- `<snake_pkg>` is the Python import name — always derive it from `<slug>`
by replacing dashes with underscores.
- The user can freely change these post-scaffold; this skill picks
defaults so the repo boots immediately.
## Workflow
### Step 1 — Resolve scaffold parameters
1. Accept `$ARGUMENTS` of the form `<slug> [--scope @your-org] [--ts-only|--py-only|--both] [--dry-run]`.
2. If `<slug>` is missing, ask via `AskUserQuestion`. Validate it is
kebab-case (`^[a-z][a-z0-9-]*$`); reject otherwise with a clear
error.
3. Derive `<snake_pkg>` from `<slug>` (`s/-/_/g`).
4. Resolve `<scope>`: explicit `--scope` flag wins; otherwise leave
empty (publishes as flat `<slug>`).
5. Default to `--both` packages. Honor `--ts-only` / `--py-only` to
skip the other tree.
6. Confirm with the user before writing: print the resolved
placeholders + the file list this run will write.
### Step 2 — Inspect the working directory
1. Run `Glob` on the cwd. If the directory is empty (or contains only
`.git/`, `LICENSE`, `README.md`), proceed to a fresh scaffold.
2. If `packages/ts/` or `packages/py/` already exist, do **not** overwrite.
Walk the layout in `references/reference-structure.md` and report
missing files — write **only** the missing ones, leaving existing
files untouched.
3. If the repo is clearly not a polyglot library candidate (has its own
`src/`, monorepo manifest, foreign workspace shape), stop and ask.
### Step 3 — Write root files
In this order, from `references/templates/`:
1. `root-README.md` → `README.md`
2. `root-SPEC.md` → `SPEC.md` (intentionally a stub — the user fills the
behavior; the structure is what this skill provides)
3. `root-LICENSE` → `LICENSE` (skip if already present)
4. `root-Makefile` → `Makefile`
5. `root-package.json` → `package.json`
6. `root-pyproject.toml` → `pyproject.toml`
7. `root-gitignore` → `.gitignore`
8. `root-agent.md` → `.agent.md`
9. `root-agent.json` → `.agent.json`
10. `root-agents-parity.md` → `.agents/parity.md`
If `--ts-only`, the root `package.json` is still written (it's the
workspace marker). If `--py-only`, write a minimal `package.json` with
empty `workspaces` so the root remains valid; the user can drop it
later.
### Step 4 — Write per-package files
For TypeScript (when `--both` or `--ts-only`):
| Source | Target |
| ------------------------------------------ | --------------------------------------- |
| `packages-ts/package.json` | `packages/ts/package.json` |
| `packages-ts/tsconfig.json` | `packages/ts/tsconfig.json` |
| `packages-ts/Makefile` | `packages/ts/Makefile` |
| `packages-ts/agent.md` | `packages/ts/.agent.md` |
| `packages-ts/src-index.ts` | `packages/ts/src/index.ts` |
| `packages-ts/test-smoke.test.ts` | `packages/ts/test/smoke.test.ts` |
| `packages-ts/test-parity.test.ts` | `packages/ts/test/parity.test.ts` |
For Python (when `--both` or `--py-only`):
| Source | Target |
| -------------------------------------------- | --------------------------------------------------- |
| `packages-py/pyproject.toml` | `packages/py/pyproject.toml` |
| `packages-py/Makefile` | `packages/py/Makefile` |
| `packages-py/README.md` | `packages/py/README.md` |
| `packages-py/agent.md` | `packages/py/.agent.md` |
| `packages-py/snake_pkg-__init__.py` | `packages/py/<snake_pkg>/__init__.py` |
| `packages-py/snake_pkg-py.typed` | `packages/py/<snake_pkg>/py.typed` (empty file) |
| `packages-py/tests-__init__.py` | `packages/py/tests/__init__.py` (empty file) |
| `packages-py/tests-_helpers.py` | `packages/py/tests/_helpers.py` |
| `packages-py/tests-test_smoke.py` | `packages/py/tests/test_smoke.py` |
| `packages-py/tests-test_parity.py` | `packages/py/tests/test_parity.py` |
### Step 5 — Write parity + examples scaffolding
| Source | Target |
| -------------------------------------------- | --------------------------------------- |
| `tests-parity/fixtures.json` | `tests/parity/fixtures.json` |
| `examples/README.md` | `examples/README.md` |
| `examples/sdk-README.md` | `examples/sdk/README.md` |
| `examples/api-README.md` | `examples/api/README.md` |
The `examples/sdk/01-<scenario>.md` and `examples/api/01-<entry>.md`
files are deliberately not auto-generated — they describe **specific
behavior** of the user's library, which this skill does not know.
The `examples/{sdk,api}/README.md` files include a "How to add a new
example" section the user follows.
### Step 6 — Verify the scaffold boots
After writing, run a smoke check:
```bash
make ci-install
make ci
```
The first run will fail at the parity test (the fixtures file is a
stub) and may fail at the smoke test (the public surface is empty).
That is expected — the skill produces a structurally complete repo,
not a behaviorally complete one. Report the failure clearly so the
user knows what to fill in next:
1. Edit `SPEC.md` to define the behavior contract.
2. Implement the public surface in `packages/ts/src/index.ts` and
`packages/py/<snake_pkg>/__init__.py` (or sub-modules they
re-export).
3. Replace the placeholder fixture in `tests/parity/fixtures.json`
with cases that exercise the surface in both languages.
4. Add scenario files under `examples/sdk/` and `examples/api/`.
### Step 7 — Report
Emit a short summary:
- Resolved placeholders (`<slug>`, `<snake_pkg>`, `<scope>`).
- Files written (count, grouped by tree).
- Files skipped because they already existed.
- Smoke result (`make ci-install` exit, `make ci` exit, with the
expected stub-failure note if applicable).
- Next-step checklist (the four-step "fill in" list from Step 6).
## Hard rules
- **Never write organization-specific or host-machine-absolute paths
into a scaffolded file.** This skill is open-source. Use relative
paths and generic scope placeholders. Do not embed `/Users/...`
paths anywhere in template output.
- **Never overwrite an existing file** without confirming first. The
scaffold is additive — if `pyproject.toml` already exists, leave
it alone and report the skip.
- **Never collapse the twin layout** even if the user only wants one
language today. Write the full root scaffold so the second twin can
be added later without restructuring.
- **Never invent the SPEC.** The skill writes a `SPEC.md` stub that
documents the *structure* of a spec (function inventory table,
algorithm section, drift table). Concrete behavior is the user's
job — do not put fake behavior in there.
- **Never skip parity-test wiring.** Even with empty fixtures, both
`parity.test.ts` and `test_parity.py` must be written so adding a
fixture entry later is the only required step to expand parity
coverage.
- **Do not push, publish, tag, or open PRs** unless the user
explicitly asks.
## Inputs and arguments
- `$ARGUMENTS` shape: `<slug> [--scope @your-org] [--ts-only|--py-only|--both] [--dry-run]`
- `--scope` — optional npm scope. Without it, the npm name is the bare
`<slug>`.
- `--ts-only` / `--py-only` — write only one language tree. Default
is both. The root scaffold (`Makefile`, `package.json`,
`pyproject.toml`, `SPEC.md`, etc.) is always written.
- `--dry-run` — print the resolved placeholders and the source →
target file map without calling `Write`. Useful to confirm the
layout before committing to a scaffold.
## Examples
All examples below use `<your-slug>` as the placeholder for whatever
kebab-case name the user picks. Substitute it in real invocations.
**Bootstrap a fresh polyglot library, both languages, no scope:**
```
/ployglot-project-scafford <your-slug>
```
Writes the full layout. `package.json` declares the npm name as
`<your-slug>`. `pyproject.toml` declares the PyPI name as
`<your-slug>`. Python module derives by replacing dashes with
underscores.
**Bootstrap with an npm scope:**
```
/ployglot-project-scafford <your-slug> --scope @your-org
```
`package.json` becomes `@your-org/<your-slug>`; PyPI name stays the
unscoped `<your-slug>` (PyPI has no scopes).
**Add the Python twin to an existing TS-only repo:**
```
/ployglot-project-scafford <your-slug> --py-only
```
Skill detects the existing `packages/ts/` and only writes the
`packages/py/` tree, the Python-side entries in `tests/parity/`, and
the Python columns in `examples/`. Existing root files are left alone.
**Preview before writing:**
```
/ployglot-project-scafford <your-slug> --dry-run
```
Prints the source → target map for ~25 files and the resolved
placeholder values, without touching the disk.
## See also
- `references/reference-structure.md` — field-by-field inventory of the
layout (what each file is for, why it exists).
- `references/templates/README.md` — the source → target-path map and
placeholder substitution rules.
- Sibling skills: `sdk-paradigms` (canon for richer SDK shapes than a
pure library), `ployglot-agentmd-usages` (regenerates `.agent.md`
index after the surface evolves).
---
> Source: [carlosmarte/skills](https://github.com/carlosmarte/skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
按说明文件中的顺序排列。
何时使用该技能
参考结构
占位符
步骤 1 — 解析脚手架参数
第 2 步 — 检查工作目录
文件/命令 -> packages/ts/ · packages/py/ · SPEC.md · examples/{sdk,api}/ · Makefile · references/reference-structure.md · sdk-paradigms-scaffold · implement-polyglot-project-plan
内容校验值 -> 754e096c70d7
当前原文的自动摘译,尚未人工审校。
何时使用该技能
启动一个新库,您希望它从第一天起就具有 TypeScript + Python 表面,并且通过测试而不是振动来强制执行奇偶校验。将单语言库移植到孪生库(例如,您有 TS 但想要 Python 孪生库)并需要跨语言脚手架 —
SPEC.md、奇偶校验装置、examples/{sdk,api}/、根Makefile—参考结构
该技能产生的规范布局:请参阅
references/reference-structure.md了解逐场清单。占位符
模板使用这些占位符。在编写之前解析每一项:占位符·含义·示例
<slug>·Kebab-case包名称(用于npm + PyPI名称)·my-lib``<snake_pkg>·Python模块目录/导入名称·my_lib``<scope>·可选的npm范围(为平面名称而删除)·@your-org或空