Better code with usage specs

Searching and installing a new usage spec

First, make sure you’ve run tessl init and set up your agent (see the Quick start guide for details).

Once your agent is ready, you can ask it to search and install usage specs from the Spec Registry. For example, to install a usage spec for FastAPI, prompt Claude Code with:

Search for the fastapi usage spec in the Spec Registry and install it.

This installs [email protected] locally by adding it under .tessl/usage-specs/tessl/<package-name>@<spec-version>/

That directory is linked to KNOWLEDGE.md, which in turn links to AGENTS.md.

Inside the usage spec directory, you’ll find a manifest file called spec.json that contains metadata about the spec, including the package version:

{
  "name": "tessl/pypi-fastapi",
  "version": "0.116.1",
  "docs": "docs/index.md",
  "describes": "pkg:pypi/[email protected]",
  "summary": "FastAPI framework, high performance, easy to learn, fast to code, ready for production"
}

Tessl also tracks installed specs in tessl.json at the root of your project:

{
  "dependencies": {
    "tessl/pypi-fastapi": {
      "version": "0.116.1"
    }
  }
}

Installing usage specs for all dependencies

You can ask an agent to install usage specs directly from your package manifest. In this example, create a requirements.txt file with the following:

fastapi>=0.116.0
pydantic>=2.5.0

Then prompt your agent, for example with Claude Code:

Install usage specs for the dependencies listed in requirements.txt.

Claude Code will search the Spec Registry for matching usage specs and add them to your project automatically. After installation, your tessl.json will look like this:

{
  "dependencies": {
    "tessl/pypi-fastapi": {
      "version": "0.116.1"
    },
    "tessl/pypi-pydantic": {
      "version": "2.11.7"
    }
  }
}

And your KNOWLEDGE.md will be updated with an index of installed dependencies:

# Knowledge Index

## Dependencies

Consult the relevant documentation when using any of the dependencies listed below:

### [email protected]

FastAPI framework, high performance, easy to learn, fast to code, ready for production

[docs](.tessl/usage-specs/tessl/pypi-fastapi/0.116.1/docs/index.md)

### [email protected]

Data validation using Python type hints

[docs](.tessl/usage-specs/tessl/pypi-pydantic/2.11.7/docs/index.md)

Updating your usage specs

You can sync all your usage specs in tessl.json to ensure you have the latest versions installed.

For example, update tessl.json to include an old version of a usage spec:

{
  "dependencies": {
    "tessl/pypi-fastapi": {
      "version": "0.116.1"
    },
    "tessl/pypi-pydantic": {
      "version": "2.11.7"
    },
    "tessl/pypi-supabase": {
      "version": "1.2.0"
    }
  }
}

Then run:

tessl registry sync

Tessl will check for updates to your usage specs and ask if you want to install them.

Once accepted, your tessl.json will be updated. For example:

{
  "dependencies": {
    "tessl/pypi-fastapi": {
      "version": "0.116.1"
    },
    "tessl/pypi-pydantic": {
      "version": "2.11.7"
    },
    "tessl/pypi-supabase": {
      "version": "2.18.1"
    }
  }
}

Using a usage spec with your agent

When you start a project with tessl init, the prompts guide your agent to read from KNOWLEDGE.md. This ensures the agent loads usage specs into memory and relies on accurate documentation for your dependencies instead of guessing APIs or missing details.

For example, with Claude Code you can ask:

Build a hello world app using fastapi using specs.

The agent will read the FastAPI usage spec from KNOWLEDGE.md and use it as context when generating code.

Using a usage spec with the Tessl Framework

If you’re working with the Tessl Framework, your agent read the docs once, and the Tessl Framework uses it as well when editing specs and generating code.

For example, with Claude Code and the Tessl Framework you can run:

Build a hello world app using fastapi using specs.

You can see that Claude Code reads the KNOWLEDGE.md file first and then passes that information as context to the creation of the spec. Tessl uses all the usage specs linked to KNOWLEDGE.md when editing specs or generating code.