Package Skills

Your specs import a third-party library and the generated code uses its API in a way that's subtly wrong or out of date. Skills give Codex version-specific package context. Python projects can generate skills from PyPI metadata; TypeScript projects materialize deterministic skills from installed direct npm dependencies.

jaunt build runs a best-effort pre-build step that generates a skill for each external library your project imports. Skills are not prompt text: Jaunt seeds them into the Codex workspace under .agents/skills/, where codex exec discovers them natively.

There are three related skill workflows in Jaunt:

• automatic PyPI skill generation during jaunt build
• automatic npm skill materialization for TypeScript generation
• explicit user-managed skill authoring through jaunt skill build <name>

PyPI generation and explicit user-managed authoring run through the Codex engine. TypeScript npm skills are rendered locally from installed package metadata and README text, so preparing them adds no model call.

Python packages

On every jaunt build:

• Scans paths.source_roots for Python imports (import ... and from ... import ...).
• Filters out:
  • stdlib modules
  • project-internal top-level modules
  • relative imports (from .foo import ...)
• Resolves the remaining imports to installed PyPI distributions + versions (from your current environment).
• Ensures there is exactly one skill per distribution at:
  • <project_root>/.agents/skills/<dist-normalized>/SKILL.md
• Fetches the README for the exact <dist>==<version> from PyPI, then uses the Codex "skills generator" to produce SKILL.md.
• Seeds the resulting skills (together with Jaunt's builtin skills) into the Codex workspace at .agents/skills/, where the builder discovers and reads them as needed.

If any piece fails (resolution, PyPI fetch, generation, write), Jaunt prints a warning and continues building without those missing skills.

TypeScript packages

Before TypeScript generation, Jaunt reads each owning package's direct runtime dependencies, peerDependencies, and optionalDependencies. For each installed package it writes a versioned skill such as .agents/skills/npm-zod/SKILL.md, using only the installed manifest and README. Transitive packages, lockfile-only entries, and devDependencies are ignored.

Only files carrying Jaunt's npm provenance fields are updated or removed. A user-authored SKILL.md at the same path is skipped. Missing packages and filesystem errors are warnings; they do not fail the build. The generated skill tells Codex to use public package exports and leaves the owning compiler and tests as the verdict.

Where Skills Are Stored

Skills are stored inside your project:

<project_root>/
  .agents/
    skills/
      requests/
        SKILL.md
      pydantic/
        SKILL.md
      npm-zod/
        SKILL.md

The directory name is the distribution name normalized like PyPI (lowercased; -, _, . treated consistently).

Safe Overwrites (When Jaunt Regenerates)

Jaunt will only overwrite a skill file if it was previously generated by Jaunt and the installed version changed.

• Generated files start with a header like:
  • <!-- jaunt:skill=pypi dist=<dist> version=<version> -->
• If a file has no header, it is treated as user-managed and is never overwritten.

How Skills Reach The Builder

Before each generation call, Jaunt copies the enabled builtin skills plus your project's .agents/skills/ directories into the Codex workspace under .agents/skills/. Project skills override builtins of the same name. The build prompt then simply tells Codex that relevant skills are available there — Codex reads the ones it needs. Note that skill content is not part of module freshness: editing a SKILL.md does not mark already-built modules stale, so rebuild with jaunt build --force (or change the spec) to pick up skill edits.

Builtin Skills

Independent of PyPI auto-generation, Jaunt ships a curated set of builtin skills and seeds them by default:

[skills]
auto = true                 # prepare package skills for the active target
builtin = true              # seed Jaunt's bundled builtin skills
builtin_skills = [          # the default set (override to trim/extend)
  "asyncpg", "dbos", "descope", "fastmcp", "openai", "pydantic", "pydantic-ai",
  "pytest", "ruff", "spacy", "starlette", "ty", "uv",
]

Disable package-specific skills per build with jaunt build --no-auto-skills, or disable bundled skills with --no-builtin-skills.

Security Note (Prompt Injection Hygiene)

Package READMEs are treated as untrusted input. Python's skill generator is instructed to extract factual usage rather than follow README instructions. npm skill text is bounded and rendered into a fixed template; the generated implementation is still checked by the TypeScript compiler and tests.

Troubleshooting

• Want to see it in action quickly? Try a runnable example:

  • uv run python examples/run_example.py pydantic test

• "It didn't generate a skill": the import might be stdlib or internal, the dist might not be installed, or the README fetch/generation might have failed. Jaunt should emit a warning but still proceed with the build.

• "It didn't create an npm skill": the package must be an installed direct runtime, peer, or optional dependency of a configured TypeScript package owner.

• "Wrong version": skills are keyed to what's installed in the environment running jaunt build. Update your environment, rerun build, and Jaunt should refresh generated skills.

• "I want to edit a checked-in skill directly": use jaunt skill build <name> on a user-managed skill directory under .agents/skills/<name>/.

Next: Limitations.