> 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 ``` 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, who last touched them, and how they score for quality. A workspace is the shared home for your team's private context and these inventory results. This is where the next step starts, because the scores tell you which skills are worth your attention. ![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 with a low review score from your inventory. ## 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 weak skill, 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.