> 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 connect an SCM account, explore your Organization's Context and Findings, improve a local skill, and publish a new version your team can install. This is the end-to-end loop you will repeat with Tessl: see what context your Organization has, find what needs attention, make it better, and ship it. A few terms show up along the way, namely skills, plugins, Organizations, workspaces, reviews, and evals. You can follow every step without reading ahead; each term links to a fuller explanation in [Core concepts](/introduction-to-tessl/core-concepts.md). As a quick orientation: an Organization owns SCM connections and reporting, a workspace controls private publishing, and a project ties Tessl to a single repository. Before you start, make sure you have completed [Set up Tessl](/introduction-to-tessl/set-up-tessl.md): create an account, install and authenticate the CLI, and initialize a project. An Organization admin must connect the SCM account. ## Step 1: Connect an SCM account In the Tessl web app, select your Organization, then open **Settings** and **Integrations**. Under **Source control**, add your provider and authorize the repositories Tessl should scan. See [Connect Tessl to GitHub](/distribute/connect-tessl-to-github.md) for the GitHub flow. Tessl starts an account scan after the SCM connection is created. The connection can succeed before the scan starts or finishes, so use the connection page to check scan status, retry a failed scan, or change its **Scan scope**. ## Step 2: Explore Context Select your Organization, then open **Context** in the sidebar. Context shows the skills and configuration Tessl observed, including their repositories and paths. You can search the collection and filter it by state, score, security result, and other attributes. ![Organization Context showing scanned skills and configuration](https://1171143958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbWzspFdXV0HNujz6gJ9%2Fuploads%2Fgit-blob-6d4bd64482c3c91dbe3941ebbc0c1a160ecf9e4e%2Forganization-context.png?alt=media) After scan analysis succeeds, Tessl starts indexing the repository skills it found. There is no separate private-indexing switch or first-party approval step. Indexing, review, and security scoring are background work with separate failure paths, so a Context item can appear before it has scores, and not every item is guaranteed to receive a score. ## Step 3: Inspect Findings and results Open **Findings** to see issues reported from the latest account scans. Use the filters to narrow the list by category, priority, repository activity, status, or workspace. Select a finding to review its evidence and suggested next step. Some advanced finding details depend on your Organization's plan. ![Organization Findings showing issues reported by Tessl](https://1171143958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXbWzspFdXV0HNujz6gJ9%2Fuploads%2Fgit-blob-863d49446a64d30c2b573817dc6325ca816a4bba%2Forganization-findings.png?alt=media) A skill can need attention for different reasons, and a single skill can have more than one result. 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 with a low review score, a security result, or a Finding such as drift, overlap, or stale content. If the skill has no score yet, you can still review it directly in the next step. Check out the repository that contains the skill 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), description (how well the description triggers the skill at the right time), and content (how well the instructions guide the agent once loaded). 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 connected or uploaded repository context, 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/distribute-plugins-across-multiple-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.