> For the complete documentation index, see [llms.txt](https://docs.tessl.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tessl.io/introduction-to-tessl/improve-your-first-skill.md). # Improve your first skill > **Takeaway:** You will scan your real skills with Skill Inventory, bring them into a workspace, find a skill that needs work, improve it, and publish a new version your team can install. This is the end-to-end loop you will repeat with Tessl: see what context you have, find what is weak, make it better, and ship it. A few terms show up along the way, namely skills, plugins, workspaces, reviews, and evals. You can follow every step without reading ahead; each term links to a fuller explanation in Core concepts if you want the detail. As a quick orientation: a plugin is the content you package, a workspace is the team space that owns it, and a project ties Tessl to a single repository. Before you start, make sure you have completed **Set up Tessl**: an account, the CLI installed and authenticated, and a project initialized. You will also need the [GitHub CLI](https://cli.github.com/) authenticated, since the inventory step reads your repositories through your existing GitHub access. ## Step 1: Scan your skills Most teams have no clear picture of how many skills they have, who owns them, or how many are near-duplicates. Skill Inventory gives you that map. Run: ```bash tessl inventory import ``` If your organization or workspace settings set a security policy to block, skills that meet the conditions you specified are not indexed. The inventory screen still lists them, so you can see which skills have issues even when a policy stops them from being indexed. Tessl asks which GitHub org to scan and which workspace to store the results in, then collects every `skill.md` and manifest file across that org's repositories and uploads a snapshot. If you do not have a workspace yet, you can create one right from this prompt. It reads context files only, never your source code, and it never clones a repo. Each run is diffed against the last, so you build a living view of what is new, unchanged, and removed over time. ![Choosing a GitHub org and workspace during tessl inventory import](/files/7ZBzl9Qc4bkSHBuqkKpq) To scan only specific repositories, scope the run: ```bash tessl inventory import --repo repo-a --repo repo-b ``` ## Step 2: Review your inventory Open the workspace you chose to read the results: how many skills you have, where they live, and who last touched them. This is what the inventory gives you at this stage: a clear count of your skills, where duplication is concentrated, and who is responsible for each one. It does not produce review or security scores on its own. Those come from indexing, which is a separate step. You may notice that some skills in the workspace already carry review and security scores. Tessl automatically indexes public and third-party skills, so those show scores as soon as they appear in your workspace. Your own skills imported via `tessl inventory import` do not have scores at this point. To get review and security scores on your own skills, you connect the [GitHub App](/distribute/rollout-to-your-repositories/connect-tessl-to-github.md) and index them. Connecting the app is the first step, not the whole thing: 1. Connect the GitHub App to your GitHub organization and authorize it on the repositories you want Tessl to see. 2. Enable private indexing for the inventory. 3. Approve the first-party skills Tessl discovered so it knows which ones to index. Skills stay pending until you approve them, so installing the app on its own does not produce scores. 4. Check the scores. Once a skill is indexed it carries review and security scores. Indexing also makes a skill searchable, so teammates can find it. The GitHub App keeps scores current as skills change over time and sets up indexing across the repositories you connect, so you do not have to run a review on each skill individually. ![Workspace inventory view with skill scores](/files/PUdU6AvPH5GSOK83fH72) ## Step 3: Find a skill that needs work A skill can be flagged for two different reasons, and a single skill can hit both at once. They are worth telling apart, because each has its own fix. The first is a **low review score**. A review measures the quality of the skill itself: how clear and actionable its instructions are, and how well its description tells an agent when to use it. This is the kind of problem you fix by improving the skill. The second is a **security finding**. Tessl scans skills and plugins for risky or malicious patterns in their content and behavior, such as prompt injection hidden in the instructions, hardcoded secrets, suspicious download URLs, or obfuscated text, and warns you about anything critical or high severity. This is about safety rather than quality, so it is separate from the review score. For this walkthrough, pick a skill from your inventory that looks like it needs attention. If you have indexed your organization, the inventory shows a score for each indexed skill; read down the Score column and choose one that looks low. You can also narrow the table by type, security, severity, or repository to focus your search. If you have not set up indexing yet, look for a skill that is stale, duplicated across several repositories, or that you know is weak. You can also check any individual skill's score at any time by running the review command in the next step. Skills that a security policy stopped from being indexed stay listed in the inventory, so they surface here too. These are good candidates to look at early: review and remediate the ones worth keeping, and retire the ones you no longer need. Because `tessl inventory import` never clones your repositories, the review command in the next step needs a local copy of the skill. Check out the repository that contains the skill you picked and change into it before you run the review. ## Step 4: Improve it Run a review to see the detailed breakdown: ```bash tessl review run ./ --workspace engteam ``` The review runs server-side against your workspace and returns three scores: validation (structure and formatting), implementation (the quality of the instructions), and activation (how well the description triggers the skill at the right time). Each comes with specific suggestions. To apply those suggestions automatically, run a fix: ```bash tessl review fix ./ --workspace engteam ``` `tessl review fix` runs an improve-and-review loop, applying changes and re-reviewing until the score is high enough or it reaches its iteration limit, improving the skill in place. Run a review once more to confirm the score went up. Aim for 70% or higher before you publish. A security finding is handled differently, because it is about safety, not quality. Tessl never blocks you; it warns you before installing a skill or plugin with critical or high severity findings so you can decide whether to proceed. If it is your own skill, fix the flagged content, for example by removing a hardcoded secret or a suspicious URL. If it is someone else's, treat a serious finding as a reason not to install, since it can signal a compromised skill. You can read more in Core concepts. ## Step 5: Publish a new version Once the skill passes review, publish it to your workspace and bump the version in one step: ```bash tessl skill publish ./ --workspace engteam --bump patch ``` Use `patch`, `minor`, or `major` depending on the size of the change. Skills publish as **private** by default, so only members of your workspace can install them, and a review runs automatically on publish. Teammates pick up your new version by installing it: ```bash tessl install engteam/ ``` That is the full loop. You scanned your estate, found a skill to improve, checked its quality, improved it against best practices, and shipped a better version to your team. ## Where to go next * Improve skills in more depth, including evaluating them against real tasks, in the Tutorials section. * Roll context out across your repositories automatically with the [repository integration](/distribute/rollout-to-your-repositories.md). * Understand the building blocks you just used in Core concepts. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.tessl.io/introduction-to-tessl/improve-your-first-skill.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.