Skills

A skill is one repeatable procedure stored on a single Agent: a name, a description, and the instructions the Agent follows when work of that kind arrives. Where instructions set the standing role an Agent follows everywhere and memory holds durable facts, a skill holds a procedure that only matters for a recognizable class of request. This page covers what a skill holds, where skills come from, what an import copies and what it leaves behind, and how enabling, disabling, and removing work.

What a skill holds

A stored skill has four fields and nothing else.

Skill names are unique within an Agent. Admin rejects a duplicate name at the write boundary, and the runtime keeps one entry per name so a duplicate can never abort a turn. A row that fails validation is skipped for that turn and the rest of the turn proceeds.

The shape is the Agent Skills format: a SKILL.md file whose YAML frontmatter carries name and description, and whose body becomes the instructions. Chickpea’s own authoring guide describes this as one inline skill with exactly name, description, instructions, and enabled.

Where skills come from

Three sources fill an Agent’s Skills tab, described in Admin as the repeatable ways this Agent knows how to help.

• Suggested skills. A reviewed catalog of 20 snapshots, browsable by Featured, Marketing, Writing, Research, Operations, and Engineering. Eight are featured. Each row credits its upstream author and links to the source.
• Skills you write. New skill opens an editor for a name, a description, and instructions you type yourself.
• Imports from GitHub. A pasted repository, GitHub link, or skills.sh link, resolved into candidates you pick from.

Turning a suggestion on copies its current instructions into the Agent as a snapshot. Turning it off removes that copied snapshot. No scripts, references, plugin behavior, or future updates come with it.

Importing from GitHub

Chickpea reads the SKILL.md files at the source and resolves them into candidates with a name, a description, and an immutable source URL each. In Admin nothing is written until you pick from that list. These source forms are accepted.

A direct skill-directory URL is the preferred form, because the service inspects one directory and pins its commit before fetching the file.

A repository scan reads at most 40 skill directories. Resolution spends two GitHub requests plus one raw fetch per scanned skill, and a Cloudflare Worker on the Free plan allows 50 subrequests per invocation, so the cap sits under that ceiling. When a source holds more, the result says the scan was capped and asks you to narrow with owner/repo@skill or a direct directory URL. Directories named test, tests, node_modules, .git, dist, build, __pycache__, and fixtures are skipped, and a candidate missing a name or a description is counted as skipped rather than installed.

What an import leaves behind

• Scripts and assets stay at the source. Chickpea Agent skills do not package executable files. An import through Slack or the management MCP server refuses a directory that carries one: Skill <name> includes executable scripts, which Chickpea Agent skills do not package. No change was made. In Admin the candidate is labeled as having scripts that will not run, and only the SKILL.md text is copied.
• Provenance is not stored. The saved row keeps the four fields, plus a catalog id when the skill came from a suggestion. The commit, the directory path, and the source URL are not written to the Agent. There is no update check and no sync; refreshing a skill means importing it again.
• Access is not granted. Importing a skill does not give the Agent access to the repository it came from. Ongoing repository access is a separate grant on the Repositories tab.

Selected instructions are copied into the Agent as a snapshot and may be sent to its configured model when the skill is used.

Where you do each part

In Slack you hand the Agent the link. The exact source has to appear in your current message; otherwise the import stops with Immediate skill import requires the exact GitHub source in the current requester message. No change was made. One bounded scriptless skill installs immediately and the Agent replies with a receipt saying the skill is active from the next message, with an undo. When the source holds several candidates, the Agent lists them and asks you to post the chosen source URL in a new message. When the pasted reference is a mutable branch, the service pins the inspected commit before it writes anything.

Importing a name that already exists with different content does not overwrite it. The Agent asks you to reply exactly replace <name> from <source URL>, and only that new message authorizes the replacement. An import of content identical to what is installed reports that the skill is already installed and changes nothing.

In Admin, open the Agent, choose the Skills tab, then Import from URL. Paste the source, choose Find skills, tick the candidates you want, and choose Add selected. The picker states whether the repository is public or private and whether it was read anonymously or through the connected GitHub App. Skills added this way are saved with the rest of the Agent. Admin is the only door to a private repository: it looks the source up through the GitHub App installation and mints a read-only token scoped to that one repository. Slack refuses a private source with Slack skill import currently supports public GitHub repositories. Use Admin for a private repository connected through the GitHub App.

Over the management MCP, import_skill installs one exact source, manage_agent_skill enables, disables, or removes one named installed skill, and propose_skill_import routes an import through the frozen review flow instead.

Enabling, disabling, and removing one named skill applies immediately and returns a receipt with an undo. The change reads the Agent’s current state and preserves every other skill. Only an editor of that Agent can make it, under the Agent’s edit policy.

Why it works this way

Skill text is third-party content that ends up in front of a model, so the import path is deliberately narrow. The scan is bounded, a mutable branch is pinned to a commit before anything is written, the copy is a snapshot rather than a live link, and nothing executable comes across. That is also why an import cannot quietly replace a skill you already have: replacement needs a new message that names the skill and the source.

Only enabled skills are materialized for a turn, and each one is validated as it is loaded. A single malformed skill is dropped instead of ending the turn, so an Agent with ten skills keeps working when one of them is wrong.

What is not covered

• Skills never run code. Packaged scripts are not imported, and Chickpea does not execute them. Code execution is the coding sandbox, which is a separate feature and Cloudflare only.
• Skills are not shared between Agents. Like connections, memory, and repositories, a skill stops at the Agent that holds it. Two Agents that need the same procedure import it twice.
• There is no version tracking. Nothing records which commit a skill came from, so nothing can tell you the source has moved on.
• Skills behave the same on both targets. The import resolver and the runtime path are the same code on Cloudflare and on Node.

Next steps

• Agents: the rest of what an Agent is made of, including instructions, memory, and connections.
• How Chickpea works: where a skill sits in one turn, from mention to reply.
• A tour of Admin: the browser app that holds the Skills tab and the GitHub connection.
• Authority and confirmation: how an Agent’s authority is decided, and why what it reads cannot expand it.