Better code with usage specs

In this tutorial we'll help you install the usage specs for FastAPI, a popular Python API framework.

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>/ .

.tessl
├── framework
└── usage-specs
    └── tessl
        └── pypi-fastapi
            └── 0.116.1
                ├── docs
                └── tile.json

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

Inside the usage spec directory, you’ll find a manifest file called tile.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"
    }
  }
}

Sync usage specs to match your project dependencies

You can use the Tessl CLI or ask an agent to sync usage specs for your project dependencies. For example, create a requirements.txt file containing:

fastapi>=0.116.0
pydantic>=2.5.0

Make sure to install your project dependencies before proceeding to search for usage specs.

pip install -r requirements.txt

Then run the following command to install your dependencies:

Tessl CLI

tessl registry sync

Agent

Tessl 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)

Installing usage specs after cloning a new project

When you clone a repo for the first time (or after making changes to your dependency manifest), you’ll want to install the usage specs declared in tessl.json to ensure the correct versions are set up locally.

Run:

tessl registry install

Tessl will install all usage specs defined in tessl.json into your local environment.

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 (quick start guide here), in addition to the above behaviour, the usage specs are used 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.