agentleFS
robmclartyrobmclarty/trailhead/.claude/skills/add-package/SKILL.md

add-package

Skill0 starsChanged 7 months agoMITView on GitHub

Add a new package to the workspace. Use this whenever you need a new library under packages/ or a new deployable under apps/. Handles naming, tsconfig references, scaffolding, and workspace wiring in one pass so the repo stays uniform.

6 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If you're not sure, it's a package.

    line 30
  2. Distinctive:

    Run the scaffolder: Do not hand-create files.

    line 34
  3. Very specific:

    Run pnpm check: before writing any logic. Confirms the skeleton typechecks, lints, and tests clean.

    line 45
  4. Very specific:

    Implement the thing: Put the public API in src/index.ts.

    line 47

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

add-package

Scaffolds a new workspace package or app from the repo's templates. Running the scaffolder is always preferred over hand-copying an existing package — hand-copying is where drift starts.

When to use this skill

  • The user asks for a new library, utility, CLI, or service
  • You need to factor existing code out of a package that has grown too large
  • Adding third-party code that needs isolation

When NOT to use this skill

  • Adding a single file to an existing package (just add the file)
  • Creating a throwaway experiment (use /tmp or a branch)
  • Extracting a file into its own module inside a package (just move it)

How to decide: package or app?

It is a…When…Goes in…
packagepure-ish code other things import (types, utils, logic)packages/
appyou run it to produce output (CLI, server, script)apps/

If you're not sure, it's a package. Apps that turn out to have reusable cores can later be split.

Steps

  1. Run the scaffolder. Do not hand-create files.
    pnpm scaffold:package <name>   # for packages/
    pnpm scaffold:app <name>       # for apps/
    Names are lowercase, kebab-case, and become @app/<name> (apps) or @app/<name> for public libs. Shared-infra libraries use @repo/<name>.
  2. Check the result. The scaffolder writes package.json, tsconfig.json, src/index.ts (or src/main.ts for apps), a colocated test file, and registers the package in the root tsconfig.json references array.
  3. Run pnpm install at the repo root to wire up the new workspace. The scaffolder prompts you to do this but does not run it for you — surprise installs are annoying.
  4. Run pnpm check before writing any logic. Confirms the skeleton typechecks, lints, and tests clean. If it doesn't, the scaffolder has a bug — fix it rather than patching the output.
  5. Implement the thing. Put the public API in src/index.ts. One export per file inside src/; the index re-exports what's public. Tests colocated as foo.test.ts next to foo.ts.
  6. If you're adding a cross-package dependency, use the workspace protocol:
    "dependencies": {
      "@app/other-lib": "workspace:*"
    }
    Then pnpm install again. Never import across packages with relative paths — the no-cross-package-relative-import ast-grep rule will catch it.

Naming rules

  • Packages: @app/<kebab-case> for application-specific libs, @repo/<kebab-case> for shared infrastructure (configs, build tools)
  • Apps: @app/<kebab-case>
  • Folder names match the unscoped package name (@app/foo-bar lives in packages/foo-bar/)

What the scaffolder creates

For a package:

packages/<name>/
  package.json          (scoped name, workspace deps, no publish)
  tsconfig.json         (extends @repo/config/tsconfig/lib.json)
  src/
    index.ts            (empty public API + one example export)
    index.test.ts       (one passing test, so `pnpm check` is immediately green)

For an app:

apps/<name>/
  package.json          (with a bin entry and start script)
  tsconfig.json         (extends @repo/config/tsconfig/node.json)
  src/
    main.ts             (entry with arg parsing shell)
    main.test.ts        (smoke test)

After scaffolding

If you created a package, consider whether the repo's CLAUDE.md needs updating with a one-line pointer ("what does this package do"). Only add a pointer if the package's role isn't obvious from its name. If you add a package-level CLAUDE.md, keep it to things that apply only when working in that package — anything universal belongs in the root.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.