> ## Documentation Index > Fetch the complete documentation index at: https://docs.orkestral.pro/llms.txt > Use this file to discover all available pages before exploring further. # Skills > Reusable capabilities and knowledge you give your agents. A skill is a short, reusable playbook your agents can read on demand. Think of it as a focused how-to: a debugging method, a testing discipline, a deploy procedure, or any repeatable technique you want your team to apply instead of rediscovering it every time. Skills live per workspace, they are written in Markdown, and the agents find them by name and pull in the full content only when a task calls for it. This page explains what a skill is, the skills Orkestral ships with, how to add more from GitHub, and exactly how your agents use them while they work. Every workspace starts with proven engineering playbooks: systematic debugging, TDD, safe refactoring, security review, and more. Browse the marketplace to install community skills pulled live from canonical GitHub repositories. Create instruction skills in a full document editor. The content is injected into the prompt when the skill is used. Agents discover skills via `skill_list`, read them via `skill_view`, and can save new ones they learn. ## What a skill is A skill has a small, clear shape: * **Name**: a short imperative title, like "Systematic Debugging" or "Add a z-api WhatsApp webhook". The name is also the document title. * **Description**: one line that says when to use the skill. This is what an agent reads first to decide if the skill is relevant. * **Content**: the Markdown body, the actual step-by-step playbook with steps, pitfalls, and how to verify. This is the part that gets injected into the agent prompt when the skill is applied. * **Kind**: skills come in three kinds (see below). The Skills page focuses on `instruction` skills. Skills are stored per workspace. Switching workspaces shows a different set of skills, so each project keeps its own playbooks and conventions. ### The three kinds A Markdown playbook injected into the agent prompt. This is the skill you write and edit on the Skills page. A capability the agent can call. Created on the Skills page alongside instruction skills. A connection to an external Model Context Protocol server. MCP skills are managed on the MCPs page, not here. On the Skills page you can create **Instruction** and **Tool** skills. MCP skills exist as a kind, but they come from the MCPs page because they wrap a server connection, not a written playbook. ## How skills reach your agents The design goal is to keep the prompt small. Agents never get every skill body dumped into context. Instead they see a lightweight index and pull the full text only when needed. The agent is told that skills exist and is nudged to check them before non-trivial work. It sees names and one-line descriptions, not full bodies. When a task looks non-trivial, the agent calls `skill_list` to see the reusable skills available in the workspace (name plus description). If a skill looks relevant, the agent calls `skill_view` with the name or slug and receives the full step-by-step content. Usage is tracked so popular skills surface. The agent follows the playbook for the task at hand instead of improvising. The orchestrator expects evidence that `skill_list`/`skill_view` were consulted when applicable. Because the body loads only when read, you can write long, detailed playbooks without bloating every run. Depth is free until the skill is actually used. ## Bundled skills Every workspace is seeded with a library of proven engineering playbooks, adapted from established agent-skill collections. They arrive as `instruction` skills and are protected, so an agent cannot overwrite them by accident. They show up the moment a workspace exists, so your team has real content from day one. Four-phase root cause method: investigate, find the pattern, form and test a single hypothesis, then implement one fix. The iron law is no fixes without root cause investigation first. The RED-GREEN-REFACTOR cycle: write a failing test, watch it fail, write minimal code to pass, then refactor. No production code without a failing test first. Bite-sized tasks of two to five minutes each, with exact file paths, complete copy-pasteable code, commands, and verification steps. Make implementation obvious. Throwaway experiments to validate an idea before committing to a real build: decompose into feasibility questions, build something observable, then record a verdict. Understand existing architecture and patterns before building, so you reuse what exists and avoid mid-implementation surprises. Run a plan with a fresh subagent per task plus a two-stage review: spec compliance first, then code quality. Systematic review across correctness, architecture, quality, security, testing, and performance, with clear must-fix versus nice-to-have criteria. Tests first, one change at a time, verify after each step. If behavior changes, it is not refactoring. Atomic commits, clear branch names, and useful PR descriptions so history reads like a narrative and reviews go smoothly. Layered testing for REST and GraphQL: happy path, auth, error cases, contracts, then edge cases. Read the changelog, understand breaking changes, upgrade in a branch, run the full suite, and keep a rollback plan ready. Profile before optimizing, measure a baseline, fix one bottleneck at a time, then verify the improvement and that behavior is unchanged. Spot common vulnerabilities: injection, XSS, auth and authorization flaws, hardcoded secrets, and unsafe dependencies. Seeding is idempotent and matches by name (case-insensitive). If a bundled skill with the same name already exists in the workspace, it is not duplicated. ## Open the Skills page Click **Skills** in your workspace. The page has two tabs at the top right: Your workspace skills as a grid of cards. Each card shows the skill name, a two-line description, its kind badge, and its slug. Use the search box to filter by name, slug, or description. Click a card to open and edit it. MCP skills are hidden here because they live on the MCPs page. The marketplace browser for skills. This is where you install skills pulled live from GitHub. Installing a skill copies its content into your workspace as an instruction skill. ## Create a skill On the **Mine** tab, click **New skill**. Enter a name (at least two characters) and choose the type: **Instruction** or **Tool**. The name is the document title, so write it as a short imperative phrase. Click **Create skill**. The skill opens in a full-width document editor, the same style as the Knowledge Base. Fill in the description (one line on when to use it) and the body. A divider labels the body as the content that is injected into the prompt. Write concise steps, pitfalls, and how to verify. When you have unsaved changes, an indicator appears in the action bar. Click **Save** to persist them. Do not put one-off facts in a skill. Skills are repeatable procedures. For project facts and reference material, use the Knowledge Base instead. Never put secrets in a skill body. ### Edit or delete Open any skill card to edit its name, description, and content in place. The action bar shows the kind badge and slug, a save button that activates only when there are unsaved changes, and a delete button. Deleting asks for confirmation first. ## Add skills from GitHub The marketplace pulls skills live from canonical GitHub repositories that follow the Agent Skills pattern (folders containing a `SKILL.md` file with `name` and `description` in the frontmatter). There is no separate public registry, so Orkestral reads the source repositories directly. On the Skills page, switch to the **Marketplace** tab. Skills appear with their name, description, category, and author. They are fetched from the source repositories and cached for about 30 minutes, so the list reflects what is published upstream. Install a skill to copy it into your workspace. It lands as an `instruction` skill, using the body of the `SKILL.md` as its content. Once installed, open it on the **Mine** tab and edit it like any other skill to fit your project. They are pulled from canonical Agent Skills repositories on GitHub, including the official `anthropics/skills` examples. Each `SKILL.md` is parsed for its `name` and `description` frontmatter, and the Markdown body becomes the installable content. The fetch is best-effort with a short timeout and a 30-minute cache. If it fails, the marketplace falls back to the last cached list or an empty list. Your existing workspace skills are never affected. Skills installed from the user or marketplace are protected from agent edits. Agents can read and apply them, but cannot rewrite them. Only skills an agent created itself can be improved by an agent. ## How agents create and improve skills Skills are not just a one-way library you fill in. Agents curate their own. When an agent discovers a non-obvious technique, fix, or repeatable procedure, it can save a new skill so future tasks benefit. After learning something reusable, an agent saves a concise playbook (steps, pitfalls, verification). The new skill auto-attaches to the whole team so everyone benefits. An agent can append to or replace an agent-created skill when it learns something better. Skills you or the marketplace installed are protected and cannot be changed this way. Agent-saved skills are kept concise on purpose (capped at roughly 8000 characters). The intent is a tight playbook, not a file dump. One-off facts belong in the Knowledge Base, not in a skill. ## Skills versus the Knowledge Base Both give your agents context, but they answer different questions. | | Skills | Knowledge Base | | --------- | ----------------------------------- | ------------------------------------ | | Shape | Procedure: how to do something | Fact: what is true about the project | | Example | "Systematic Debugging" steps | "Our auth tokens expire after 24h" | | When used | Agent applies it during a task | Agent looks it up for context | | Best for | Repeatable techniques and playbooks | Project facts, decisions, references | If you find yourself writing "always do X this way" for a recurring task, that is a skill. If you are recording "X is the case in this project", that is a Knowledge Base page. ## What to do next See how the orchestrator and specialists pick up skills during a run. Use the Knowledge Base for the facts that complement your skills. Manage MCP connections, the third kind of skill, on the MCPs page. Watch skills get applied as agents work through issues and epics.