| 1 | --- |
| 2 | title: Agent skills |
| 3 | description: How agents use skills, the foundational skills every agent starts with, and your workspace's skill library in the open SKILL.md format - write, import, save from a session, attach, version, keep in a repository, and turn off. |
| 4 | --- |
| 5 | |
| 6 | Ask an agent for a PDF and you get a PDF. A **skill** tells an agent how to |
| 7 | do one kind of work well, with the tools it already has. Every agent starts |
| 8 | with g1t's **foundational skills** (documents, research, data, code, |
| 9 | communication, and files and media), and your workspace adds its own in |
| 10 | the **skill library**: how you cut a release, your brand voice, how you |
| 11 | triage a bug. |
| 12 | |
| 13 | Skills never add a tool or a permission. A skill names the tools it uses, |
| 14 | and the agent uses them with the access of the person who asked, narrowed |
| 15 | to what everyone in the conversation may see |
| 16 | ([what agents can do for whom](/guides/agent-access/)). Where a tool isn't |
| 17 | available, such as code tools in a channel whose members can't all read |
| 18 | code, the agent is told that part of the skill doesn't work there. A skill |
| 19 | can't change who the agent acts for or set aside its rules. |
| 20 | |
| 21 | ## How agents use skills |
| 22 | |
| 23 | Skills load as they are needed, so a hundred of them cost a line each, not |
| 24 | their whole text, on every reply: |
| 25 | |
| 26 | 1. On every reply and every [session](/guides/agent-sessions/) step, the |
| 27 | agent's instructions list each skill it has, by its name and when to use |
| 28 | it. |
| 29 | 2. When a request matches a skill, the agent reads it with the `use_skill` |
| 30 | tool before it starts, then follows it. |
| 31 | 3. A skill that points to one of its files, such as |
| 32 | `resources/template.md`, is read the same way: `use_skill` with `name` |
| 33 | and `file`. |
| 34 | |
| 35 | Reading a skill counts as one of the reply's tool calls. An agent without |
| 36 | any tools (its first hello) has no skills listed. |
| 37 | |
| 38 | Each foundational skill also says, part by part, what isn't possible yet. |
| 39 | The agent is told the same, so when you ask for something that is coming it |
| 40 | says so and offers what it can do instead. |
| 41 | |
| 42 | ## See an agent's skills |
| 43 | |
| 44 | 1. Open **Agents** in the dock and choose an agent. |
| 45 | 2. Open its **Skills** tab. |
| 46 | |
| 47 | **Foundational, from g1t** shows each foundational skill: a check on each |
| 48 | part that works today with the tools that part uses, and **Coming** on each |
| 49 | part that doesn't yet. **Read the playbook** shows exactly what the agent |
| 50 | reads when it uses the skill. |
| 51 | |
| 52 | **From your library** lists the library's skills that reach the agent: |
| 53 | attached to it, to a team it is on, or to every agent, with the version it |
| 54 | uses. **Update to v4** appears when a newer version is out and you may move |
| 55 | it there. |
| 56 | |
| 57 | ## The foundational skills |
| 58 | |
| 59 | The foundational skills are versioned together (version `2026.10` now) and |
| 60 | updated with g1t's releases. Each is written out in the same SKILL.md format |
| 61 | as your own (open it under **Agents → Skills**), and owners turn each off |
| 62 | per agent. |
| 63 | |
| 64 | ### Documents |
| 65 | |
| 66 | | Part | Status | How | |
| 67 | | --- | --- | --- | |
| 68 | | Write and edit docs in Artifacts | Live | `create_artifact`, `edit_artifact`, `read_artifact`. Markdown with tables, task lists, callouts and Mermaid charts. | |
| 69 | | Make PDFs | Live | `make_file` with format `pdf`, from Markdown, attached to a doc. | |
| 70 | | Word documents | Live | `make_file` with format `docx`, from Markdown, attached to a doc. | |
| 71 | | Spreadsheets | Live | `make_file` with format `xlsx` (one or more sheets) or `csv` (one sheet). | |
| 72 | | Slide decks | Coming | Comes with slides in Artifacts. Until then, the agent offers an outline as a doc or a PDF. | |
| 73 | |
| 74 | ### Research |
| 75 | |
| 76 | | Part | Status | How | |
| 77 | | --- | --- | --- | |
| 78 | | Reports with sources | Live | From the workspace's docs, code and chat (`search_artifacts`, `read_artifact`, `search_code`, `read_file`, `search_messages`, `read_thread`), each source linked; long reports as a doc with a Sources section. | |
| 79 | | Search the web | Coming | Comes with web access, set per team. | |
| 80 | | Browse and read pages | Coming | Comes with web access, set per team. | |
| 81 | |
| 82 | ### Data |
| 83 | |
| 84 | | Part | Status | How | |
| 85 | | --- | --- | --- | |
| 86 | | Analyze files and tables | Live | CSV, JSON and log files in repositories (`read_file`) and tables in docs (`read_artifact`). The model works the numbers itself, without running code, so it says what it totalled and calls large results estimates. | |
| 87 | | Charts in docs | Live | Bar, line and pie charts drawn from Mermaid in a doc. | |
| 88 | | Spreadsheets of results | Live | `make_file` with format `xlsx` or `csv`. | |
| 89 | | Dashboards | Coming | Comes with dashboards in Artifacts. | |
| 90 | | Query databases and forks | Coming | Comes with workspace datasets and database connections. | |
| 91 | |
| 92 | ### Code |
| 93 | |
| 94 | | Part | Status | How | |
| 95 | | --- | --- | --- | |
| 96 | | Read and explain code | Live | `list_repositories`, `search_code`, `read_file`, `recent_activity`, in repositories everyone in the conversation can read. | |
| 97 | | Review pull requests | Live | `get_pull`, `review_pull`, `comment`. Reviews are advisory: people still give the approvals a merge needs. | |
| 98 | | Open pull requests | Live | `draft_issue`: the agent drafts the issue, a person files it, and assigning it to `@g1t` makes the pull request on a runner, with checks and revisions. | |
| 99 | | Run code on its runner | Coming | Comes with agents on runners. | |
| 100 | | Write and run tests itself | Coming | Comes with agents on runners. `@g1t` runs tests on issues assigned to it today. | |
| 101 | |
| 102 | ### Communication |
| 103 | |
| 104 | | Part | Status | How | |
| 105 | | --- | --- | --- | |
| 106 | | Draft emails and messages | Live | Written ready to send, in a code block or a doc. Agents don't send email; you do. | |
| 107 | | Summarize threads | Live | `read_thread`, `search_messages`: what was decided, what is open, and who owns each next step, with links. | |
| 108 | | Find times and book meetings | Coming | Comes with calendar integrations. | |
| 109 | |
| 110 | ### Files and media |
| 111 | |
| 112 | | Part | Status | How | |
| 113 | | --- | --- | --- | |
| 114 | | Convert between formats | Live | Markdown, text and tables to PDF, Word, Excel, CSV or Markdown with `make_file`, including files read from a repository or a doc. | |
| 115 | | Diagrams | Live | Flowcharts, sequences and timelines from Mermaid in a doc. | |
| 116 | | Read scans and images | Coming | Comes with image input for agents. | |
| 117 | | Create and edit images | Coming | Comes with image models. | |
| 118 | |
| 119 | ## Files agents make |
| 120 | |
| 121 | `make_file` writes the file itself, inside g1t, and keeps it with a doc in |
| 122 | Artifacts: |
| 123 | |
| 124 | - **Without a doc named**, it makes a new doc that holds the content (or, |
| 125 | for a spreadsheet, a preview of its first rows) and attaches the file. |
| 126 | The doc goes where `create_artifact` would put it: shared with the |
| 127 | conversation in a direct message or private channel, the General space in |
| 128 | a public channel. |
| 129 | - **With a doc named**, it attaches the file to that doc. The person who |
| 130 | asked must be able to edit it. |
| 131 | |
| 132 | Either way, the doc gets a link to the file, and the agent answers with the |
| 133 | file's link. Files are served from the usercontent address |
| 134 | (`g1tusercontent.com` on g1t.sh), like files you put in a doc yourself. |
| 135 | When not everyone in the conversation can open the doc, the agent sends |
| 136 | the link to the person who asked, in their direct message with it, and says |
| 137 | only that it made something. |
| 138 | |
| 139 | | Format | From | Notes | |
| 140 | | --- | --- | --- | |
| 141 | | `pdf` | Markdown | US Letter, numbered pages, links you can click. Headings, paragraphs, bold, italic, code, lists, quotes, code blocks and tables. Standard fonts, so text is Latin script: accents are kept, other scripts are not. At most 300 pages. | |
| 142 | | `docx` | Markdown | The same blocks as a Word document, with real headings and tables. | |
| 143 | | `xlsx` | Rows | Up to 10 sheets, 5,000 rows and 50 columns each. The first row is the header, in bold and frozen. Numbers stay numbers; codes with a leading zero stay text. | |
| 144 | | `csv` | Rows | One sheet, UTF-8. | |
| 145 | | `md` | Markdown | The Markdown as written. | |
| 146 | |
| 147 | A file is at most 25 MB. Mermaid charts and images show in the doc but not |
| 148 | in a PDF or Word file, where a chart's source is kept as code. |
| 149 | |
| 150 | ## The skill library |
| 151 | |
| 152 | Your workspace's own skills are under **Agents → Skills**. The library |
| 153 | lists drafts waiting for review first, then every skill with its version |
| 154 | and where it is attached, then g1t's foundational skills, which you can |
| 155 | open to read as SKILL.md. |
| 156 | |
| 157 | A skill does nothing until it is attached. Open it and choose **Attach**: |
| 158 | |
| 159 | | Attach to | Who gets it | Who can attach it there | |
| 160 | | --- | --- | --- | |
| 161 | | Every agent in the workspace | Every agent, `@g1t` included | Owners | |
| 162 | | A team | Every agent on the team: added to it, or whose home team it is | Owners, and the team's maintainers | |
| 163 | | One agent | That agent | Owners | |
| 164 | |
| 165 | An agent gets each skill once. When a skill reaches it in more than one |
| 166 | way, the attachment closest to it decides the version: the agent's own, |
| 167 | then its teams', then the workspace's. |
| 168 | |
| 169 | ### Who can do what |
| 170 | |
| 171 | | | Members | Team maintainers | Owners | |
| 172 | | --- | --- | --- | --- | |
| 173 | | See the library and every skill | Yes | Yes | Yes | |
| 174 | | Save a finished session as a draft | Yes | Yes | Yes | |
| 175 | | Write and import skills, publish drafts | No | Yes | Yes | |
| 176 | | Edit or delete a skill | No | The ones they wrote, used only by their teams | Any | |
| 177 | | Attach, detach and move versions | No | On the teams they maintain | Anywhere | |
| 178 | | Turn a skill off for one agent | No | No | Yes | |
| 179 | | Link a repository | No | No | Yes | |
| 180 | |
| 181 | Every change is in the workspace's audit log under `agents/skills/<name>`. |
| 182 | |
| 183 | ## The skill format |
| 184 | |
| 185 | A skill is a folder in the open SKILL.md format, the same one other agent |
| 186 | tools read, so a skill written elsewhere imports as it is: |
| 187 | |
| 188 | ```text |
| 189 | release-notes/ |
| 190 | ├── SKILL.md |
| 191 | ├── resources/ |
| 192 | │ └── template.md |
| 193 | └── scripts/ |
| 194 | └── collect.py |
| 195 | ``` |
| 196 | |
| 197 | `SKILL.md` starts with YAML front-matter, then the instructions in |
| 198 | Markdown: |
| 199 | |
| 200 | ```markdown |
| 201 | --- |
| 202 | name: release-notes |
| 203 | description: Use when someone asks for release notes or a changelog for a version. |
| 204 | tools: [recent_activity, get_pull, create_artifact, make_file] |
| 205 | --- |
| 206 | |
| 207 | # Release notes |
| 208 | |
| 209 | 1. Read the pull requests merged since the last tag (`recent_activity`). |
| 210 | 2. Group them by area: Added, Changed, Fixed. |
| 211 | 3. Write the notes as a doc, linking each pull request. Use resources/template.md. |
| 212 | ``` |
| 213 | |
| 214 | | Key | Required | What it is | |
| 215 | | --- | --- | --- | |
| 216 | | `name` | Yes | Lowercase letters, digits and single hyphens, at most 64 characters. Agents ask for the skill by it. The foundational skills' names (`documents`, `research`, `data`, `code`, `communication`, `files`) are taken. | |
| 217 | | `description` | Yes | When to use it, at most 1,024 characters. Agents read it on every reply to choose the skill, so start with "Use when". | |
| 218 | | `tools` | No | g1t's own key: the agent tools the skill uses, as a list or separated by commas. Only tools agents have are accepted (see below). Naming a tool never gives it to an agent. | |
| 219 | | `requires_computer` | No | g1t's own key: `true` for a skill that needs the agent's own computer. A skill with files in `scripts/` needs one whatever it says. | |
| 220 | | Anything else | No | `license`, `metadata`, `allowed-tools` and other keys are kept as written and change nothing. | |
| 221 | |
| 222 | Other files go in `resources/` (templates and references the instructions |
| 223 | point to; `references/` and `assets/` work too) and `scripts/`. |
| 224 | |
| 225 | The tools a skill can name: `list_repositories`, `search_code`, |
| 226 | `read_file`, `list_issues`, `get_issue`, `get_pull`, `recent_activity`, |
| 227 | `draft_issue`, `comment`, `review_pull`, `search_artifacts`, |
| 228 | `read_artifact`, `list_spaces`, `stale_artifacts`, `create_artifact`, |
| 229 | `edit_artifact`, `share_artifact`, `make_file`, `search_messages`, |
| 230 | `read_thread`, `workspace_roster`, `ask_colleague`, `hand_off`, |
| 231 | `start_session`, `post_update`, `use_subagent`, `bring_in`, `use_skill`, |
| 232 | `remember` and `forget`. |
| 233 | |
| 234 | | Limit | | |
| 235 | | --- | --- | |
| 236 | | One skill's folder | 1 MB, every file together, and at most 200 files | |
| 237 | | Skills from the library per agent | 100. Past that, the agent gets its own attachments first, then its teams', then the workspace's, and its Skills tab says how many it is missing. | |
| 238 | | Skills in a workspace's library | 1,000 | |
| 239 | | An upload | 2 MB | |
| 240 | |
| 241 | ### Scripts and the agent's computer |
| 242 | |
| 243 | Scripts run only on an agent's own computer, which is coming. Until then a |
| 244 | skill that needs one is marked **Needs a computer · Coming**: its scripts |
| 245 | are kept with it and never run, and agents follow the parts of it that |
| 246 | don't need them and never say they ran a script. They can still read a |
| 247 | script's text with `use_skill`. |
| 248 | |
| 249 | ## Write a skill |
| 250 | |
| 251 | You need to be an owner or a team maintainer. |
| 252 | |
| 253 | 1. Open **Agents → Skills** and choose **Write a skill**. |
| 254 | 2. Give it a **name** and say **when to use it** in one sentence. |
| 255 | 3. Write the **instructions** in Markdown, in the second person: the steps, |
| 256 | what to read first, the checks before it's done. **Preview** shows them |
| 257 | rendered. |
| 258 | 4. Tick the **tools it uses**, and add **files** to `resources/` or |
| 259 | `scripts/`. |
| 260 | 5. Choose **Add to the library**, then **Attach** it where it belongs. |
| 261 | |
| 262 | g1t writes the SKILL.md for you. **Show SKILL.md as written** on the |
| 263 | skill's page shows it. |
| 264 | |
| 265 | ## Versions |
| 266 | |
| 267 | Every save is a new version, listed under **Versions** on the skill's page |
| 268 | with who made it, where it came from and an optional note. Choose one to |
| 269 | read it as it was. |
| 270 | |
| 271 | Each attachment pins the version its agents use, so an edit never reaches |
| 272 | an agent you didn't mean it to: |
| 273 | |
| 274 | - When you save, **Use the new version wherever I can change it** (on by |
| 275 | default) moves the attachments you may change. The others keep their |
| 276 | version. |
| 277 | - An attachment on an older version shows **Update to v4** on the skill's |
| 278 | page and on the agent's Skills tab. Choosing it moves that attachment, |
| 279 | for every agent it reaches. |
| 280 | |
| 281 | Saving with nothing changed doesn't make a version. |
| 282 | |
| 283 | ## Import a skill |
| 284 | |
| 285 | You need to be an owner or a team maintainer. Open **Agents → Skills** and |
| 286 | choose **Import**. |
| 287 | |
| 288 | - **Upload** a `SKILL.md`, or a zip of the skill's folder. A zip holding one |
| 289 | folder (as zipping a folder makes it) is read as that folder. |
| 290 | - **From a repository**: a repository you can read (`workspace/name`), the |
| 291 | folder holding `SKILL.md`, and a branch, tag or commit (the default |
| 292 | branch when empty). It is read once, and the commit is kept with the |
| 293 | version. |
| 294 | |
| 295 | A skill whose name the library already has is refused, unless you tick |
| 296 | **If the library has a skill with its name, make this its new version**. |
| 297 | |
| 298 | ## Save a session as a skill |
| 299 | |
| 300 | When an agent finishes a [session](/guides/agent-sessions/) the way you'd |
| 301 | want it done again: |
| 302 | |
| 303 | 1. Open the session and choose **Save as skill**. |
| 304 | 2. The agent drafts a skill from the transcript: its steps, what it read |
| 305 | first and the checks it made, without names of people, secrets or |
| 306 | one-off details. The draft is billed as the agent's work, like a short |
| 307 | session step. |
| 308 | 3. The draft waits under **Drafts to review** in the library. No agent uses |
| 309 | it, and it can't be attached. |
| 310 | 4. An owner or team maintainer opens it, chooses **Review and publish**, |
| 311 | changes what's wrong, and chooses **Publish**. |
| 312 | |
| 313 | Anyone who can see the session can save it. Whoever saved a draft, owners |
| 314 | and team maintainers can discard it. |
| 315 | |
| 316 | ## Keep skills in a repository |
| 317 | |
| 318 | The library is the place you write skills. Optionally, it can follow a |
| 319 | repository, so skills go through the same pull requests and reviews as |
| 320 | code: |
| 321 | |
| 322 | 1. Open **Agents → Skills**. Under **Keep skills in a repository**, enter |
| 323 | the repository as `workspace/name` and choose **Link repository**. |
| 324 | Owners only. |
| 325 | 2. Each folder in `.g1t/skills/<name>/` on its default branch becomes the |
| 326 | skill `<name>`. The folder's name and the `name` in its `SKILL.md` must |
| 327 | match. |
| 328 | 3. Every push to the default branch that changes a folder publishes a new |
| 329 | version of that skill and moves all its attachments: the repository's |
| 330 | review is the review. **Read it again** reads it on demand. |
| 331 | |
| 332 | A skill from the repository is marked **From the repository** and is |
| 333 | changed there, not in the editor. A folder whose name the library already |
| 334 | uses for a skill written here is skipped and listed under the panel, as is |
| 335 | a folder that isn't a valid skill. When a folder is removed from the |
| 336 | repository, its skill stays in the library and can be edited here again. |
| 337 | **Stop following** does the same for every skill. |
| 338 | |
| 339 | Writing edits made in the library back to the repository as a commit is |
| 340 | coming. |
| 341 | |
| 342 | ## Turn a skill off |
| 343 | |
| 344 | Owners can turn any skill off for one agent, foundational or from the |
| 345 | library, for example Communication for an agent that only reviews code. |
| 346 | |
| 347 | 1. Open the agent's **Skills** tab. |
| 348 | 2. Switch the skill off. |
| 349 | |
| 350 | Turning a skill off takes it out of the agent's instructions. It doesn't |
| 351 | take tools away: tools come from what the agent is and where it is asked, |
| 352 | not from skills. The change is a new version of the agent, listed on its |
| 353 | **Profile** tab with the others. A library skill stays attached; to remove |
| 354 | it everywhere, detach it on its page. |
| 355 | |
| 356 | Members see each skill as **On** or **Off**. |
| 357 | |
| 358 | ## Web access |
| 359 | |
| 360 | Research on the open web comes with web access, set per team: the open web, |
| 361 | approved sites only, or off. It is coming; until then no agent reads the |
| 362 | web. |
| 363 | |
| 364 | ## Coming |
| 365 | |
| 366 | | What | Status | |
| 367 | | --- | --- | |
| 368 | | Skills from the [Marketplace](/guides/marketplace/): an extension's skills, added in one step | Coming | |
| 369 | | Running a skill's scripts on the agent's own computer | Coming | |
| 370 | | Writing library edits back to the linked repository | Coming | |