AGENT SKILL

studio-typescript

Use when building, checking, linting, formatting, or configuring a TypeScript project with @jterrazz/typescript, such as build/dev/start/mutation, a failing `typescript check` pass, the kind and platform of `studio.config.ts`, its presets and tool settings, the derived editor files, the baseline (`.studio/baseline.json`), writing a rule with `@jterrazz/typescript/rules`.

适用职业内容创作者
使用场景写作与文案
License 许可
MIT
最近更新
2026-11-10
Stars
★ 0
Forks
0

01 前言 Front Matter

name
studio-typescript
description
Use when building, checking, linting, formatting, or configuring a TypeScript project with @jterrazz/typescript, such as build/dev/start/mutation, a failing `typescript check` pass, the kind and platform of `studio.config.ts`, its presets and tool settings, the derived editor files, the baseline (`.studio/baseline.json`), writing a rule with `@jterrazz/typescript/rules`.

03 SKILL.md 正文

@jterrazz/typescript

One devDependency that builds, checks, lints and formats a project. The manual is the package's docs/, read from the install (node_modules/@jterrazz/typescript/docs/) or from this repository when the toolchain itself is the change. This page decides what to run and which page to open; the page owns the rule.

What to run

Gesture When
typescript fix before every commit: lint fixes, formatting, .gitignore, spellings, empty directories
typescript check the gate: every pass in parallel, then the drift report; a tree already proven green answers from .artifacts/proven/ and runs nothing, --cold runs it (docs/reference/quality-checks.md, A tree proven green)
typescript test the make test recipe: the project's test script over the test files the change reaches by the last mutation record, every file where it cannot tell (docs/reference/quality-checks.md, The test files a change reaches), answered from its proof like check
typescript build what the manifest publishes into dist/: ESM + types, CJS where a target is .cjs
typescript mutation Stryker over a sandbox copy; fails on a mutant a test runs and lets live (the module tests over the change, then the whole suite over what they let live and the changed lines; domain at zero survivors, glue at its bar; the text of a file typescript.mutation.presentation declares never mutated; --since, --mutate, --report html for the HTML report a person browses; its test runners sized from the machine, TYPESCRIPT_CAPACITY to give it one); a survivor to answer: docs/guides/triage-a-survivor.md
typescript doctor first read after a bump: installed tools against the declared ranges, then every setting beside the file it comes from
typescript baseline a bump lands red: record today's counts, exact; fix lowers one that fell
typescript docs-layout a repository with no npm project: the manual's shape, alone
typescript gate-lock before an install or a pack: refuses while a running gate holds the checkout, naming its pid
typescript rehearse before a tag: the gate on Linux, in Docker, on a fresh clone of the branch, as the runner runs it (docs/reference/commands.md)

typescript <command> --help prints a command's flags and runs nothing; a flag it does not read, or one given twice, is refused before anything is written (docs/reference/commands.md).

A project declares its kind (library, api, cli, website, mobile) and its platform (node, bun, react, next, astro, expo) in studio.config.ts, defineConfig({ kind, platform }); the profile, the tsconfig preset and every law follow. A monorepo is no kind: its root package.json lists workspaces, is private, and its studio.config.ts holds the repository's settings and no kind, or is absent; each member declares its own. oxlint.config.ts, oxfmt.config.ts and tsconfig.json are derived (the first two hand their own import.meta.url to oxlintConfig / oxfmtConfig), and typescript fix writes them; every tool setting lives in studio.config.ts, and no knip.json, tsdown.config.ts or stryker.config.* is kept. A repository root also owes a Makefile of six gestures and a docs/ manual its CLAUDE.md routes to. The whole wiring, from an empty folder to a green run, is docs/start/getting-started.md.

What a failing pass means

Every pass that ran prints a RUN header and one verdict with its seconds; a pass that did not apply prints nothing. The run's last line names the first failing pass and its first finding, and .artifacts/gate/verdict.json holds every pass's status for a reader that should not parse the log, for check, fix and mutation alike (docs/reference/quality-checks.md, The verdict file). Each rule id below is explained in docs/reference/quality-checks.md, under the pass's own section. On a GitHub runner the run prints a line per pass, each finding as rule and place, found, fix and read, and an annotation each (docs/reference/quality-checks.md, On a GitHub runner).

Pass It failed because
Config (one file) studio.config.ts declares no valid kind and platform, a derived file says something else (typescript fix), a tool keeps its own config, the manifest does not match the kind, or a src/standard/ computes
TypeScript Check tsc 7 refused a type
Oxlint Check a rule fired that .studio/oxlint-suppressions.json does not hold: fix it, or typescript baseline; a recorded count fell: typescript fix; an oxlint rule is left in .studio/baseline.json (baseline-moved-to-oxlint): typescript baseline; a directive suppresses nothing (Unused oxlint-disable directive, reportUnusedDisableDirectives): delete it; a @ts-ignore or an undescribed @ts-expect-error (typescript/ban-ts-comment)
Oxfmt Check a file is not formatted: typescript fix
Gitignore (artefacts) an artefact is named or committed outside .artifacts/<tool>/
Knip (unused code) a file, export or dependency nothing uses
a preset's label a preset's checks refused, @jterrazz/test's conventions among them; the preset's own manual owns the id
Docs (layout) the repository's docs/ breaks the manual's spine, or holds a generated reference/
Publish (packaging) the exports map promises a file the tarball does not carry, or a shipped file is compiled from test material
Architecture (layer map) an import crosses a layer of a preset (the standard's lint/ direction included), of typescript.architecture or of the project's own .dependency-cruiser.* (architecture/<name>, at its line); a recorded architecture/<name> count grew (typescript baseline) or fell (typescript fix); the map does not load or has nothing to cruise
Astro (check + format) astro check or prettier refused a .astro file
Suppressions (directives) a lint directive is misspelled or unreasoned
Comments (styles, scripts, YAML) a comment of a style sheet, a script, a Makefile, a Dockerfile or a YAML file states no kind: give it one, or delete it by hand, since typescript fix deletes no comment
Markdown (prose) rumdl refused a page (markdown/link-resolves a missing link, MD051 a missing anchor, MD040 a fence with no language: typescript fix), a page cites a path that is gone, a block runs past its limit, a skill's frontmatter is no YAML or lacks its name or description (markdown/skill-frontmatter-reads: quote the value holding : ), or its prose punctuates with a dash (markdown/prose-has-no-dash: rewrite the sentence; an author's text kept as written sits under a root declared { reason, verbatim: true })
Names (tree) a directory is not kebab-case, a name says nothing, names a construct (types.ts), is written in half, a skill holds more than its SKILL.md, a root sits outside the spine undeclared, studio.config.ts does not load, an entry is not named for its subpath, an index publishes nothing, a .bin publishes no bin, a published subpath has no source, the Makefile misses one of the six gestures, or a directory is empty: typescript fix
Secrets (credentials) a committed line looks like a live credential

The drift report closes the run, and refuses nothing: a rule set apart already carries its reason in typescript.oxlint.

Before writing

  • A file is named for its subject in the domain: never types.ts, utils.ts, constants.ts, nor a *.types.ts suffix. An index is an entry the package publishes, named index[.<subpath>][.browser].ts for its subpath, and a bin <command>.bin.ts, named for the command it publishes. .bin marks only a published bin, and a program the package does not publish is named for what it runs (docs/reference/quality-checks.md, The entry grammar).
  • A file holds 300 lines and a function 60; a *.spec.ts is @jterrazz/test's spec-file-within-line-limit, at 400 (docs/reference/lint-presets.md).
  • The default is no comment: a name carries the meaning. A comment that stays opens with its kind (invariant:, hazard:, outside: or value:) or fails jterrazz-typescript/comment-states-its-kind, which you settle by hand, since typescript fix deletes no comment; an exported symbol's hover is one /** ... */ paragraph above it, wrapped with no blank line, which its block tags (@param, @example) may follow on lines of their own. A style sheet's, a script's, a Makefile's, a Dockerfile's and a YAML file's comments are held to the same kinds by the Comments pass. A comment longer than the function it sits on fails jterrazz-typescript/comment-no-longer-than-its-function (docs/reference/lint-presets.md, A comment states its kind).
  • A suppression carries its reason: // oxlint-disable-next-line <rule> -- why, and @ts-expect-error with a description.
  • Every artefact lives under .artifacts/<tool>/; dist/ is the product, not an artefact.
  • What knip cannot trace goes under typescript.knip, each name mapped to its reason.
  • The API is the types: there is no generated reference, and docs/ never holds one.
  • A repository root holds src/, lint/, specs/, docs/, skills/; any other root folder fails Names (tree) unless the ecosystem imposes it (bin/, public/, app/...) or studio.config.ts declares it under typescript.roots with a reason.
  • A lint/ holds at its root the modules that compose it (its entries, its bins, what src/ reads) and three folders: consumer/ and self/ hold declarations alone, and kit/ holds the code that runs them (docs/reference/quality-checks.md, The lint tree).
  • A repository's root Makefile answers make install, build, lint, fix, test and check; a workspace member owes none of them.
  • studio.config.ts holds what the project is, its presets and its exceptions, each with its reason, and nothing derivable: a module loaded by path is built by its name (instrumentation.ts, *.worker.ts, *.global-setup.ts, a *.cli.ts into .artifacts/dev/), and kind and platform defaults are the standard's (docs/reference/building.md, What the manifest does not name).
  • What a package holds a project to reaches it through the preset the project lists under presets in studio.config.ts, after the standard the declaration derives; the project's own layers, roots and name rules go in its typescript section, and a preset's law is set aside only under optOuts, with its reason (docs/reference/configuration.md, Presets).
  • A rule a package writes for its consumers is written with @jterrazz/typescript/rules (docs/reference/rules-kit.md).
  • A local compilerOption is a smell: the preset is where the fix belongs.

The page to read next

Question Page
what the toolchain is, and the map of the manual README.md, then docs/README.md
the four ideas: declaration, settings file, two commands, baseline docs/concepts/ideas.md
wiring a project from an empty folder to a green check, .artifacts/ docs/start/getting-started.md
studio.config.ts, kind and platform, a preset, the merge order, an opt-out, a rule set apart, a tsconfig preset docs/reference/configuration.md
a failing pass, a rule id, the baseline docs/reference/quality-checks.md
a lint rule, a profile, how the config merges, knip docs/reference/lint-presets.md
build, start, dev, tsc, an entry the manifest does not name docs/reference/building.md
a bump landed red docs/guides/adopt-a-stricter-release.md
proving a release on a project before it is published: the tarball install, no install-links docs/guides/install-an-unreleased-build.md
which number moves on a release docs/guides/release.md
writing a rule, a check or its page with the kit docs/reference/rules-kit.md
changing the toolchain itself: its layers, its loop docs/concepts/architecture.md, docs/guides/develop.md
how this toolchain proves itself, and the rules it keeps for its own suite (this repository alone; the install ships without it) docs/guides/test.md

04 同仓库更多 Skills