SideButton

Create Skills for Agentic AI

Author installable skill packs that teach AI coding agents how to operate any web app. Scaffold, validate, and publish in under 30 minutes with the SideButton CLI — free, open-source, and ready to run on Claude Code, OpenAI Codex, Cursor, and every other MCP client.

← Browse all skills How to use agentic AI skills →

What is a skill for agentic AI?

A skill is a versioned directory of domain knowledge that plugs into the SideButton MCP server. It teaches an AI coding agent how a specific web app is structured: the CSS selectors that locate buttons and fields, the data model behind each page, the state transitions between views, and the multi-step workflows the agent should know how to run. Without a skill, the agent guesses. With one, it operates.

Skills are the unit of installable intelligence on the SideButton MCP server. Each lives in its own directory under sidebutton-skill-packs and ships as an npm-style package. sidebutton install <domain> fetches a published skill and registers it with your local server; from that moment any connected MCP client — Claude Code, Codex, Cursor, ChatGPT — can invoke the skill's tools and workflows.

Why create a skill?

Generic coding agents are good at writing code. They are bad at operating unfamiliar web apps — the DOM changes weekly, the data model is opaque, the workflows are undocumented. You discover this the first time you ask Claude Code to file a ticket in Jira or publish a listing in your CMS. The agent fumbles, then gives up.

A skill pack closes that gap. You write it once per app; every AI coding agent using the SideButton MCP server benefits. This is what makes agent-native development practical: agents gain stable, versioned context about the tools your team uses. Publish and your skill is re-usable by anyone in the community — a multiplier on the time you spent documenting.

What's inside a skill pack

_skill.md

Domain knowledge per module: UI selectors, data model, page states, common gotchas. This is what the agent actually reads during reasoning.

_roles/*.md

Role playbooks — what to do, when, and why. Test plans, development guides, and verification criteria for agents operating as SE, QA, PM, or any custom role.

*.yaml workflows

Agentic workflows: browser actions, shell commands, LLM calls chained into reusable pipelines. 40 step types available out of the box.

skill-pack.json

Pack manifest: domain, version, module list, license, and description. Validated by the registry on publish.

How to create and publish a skill

1

Scaffold the skill pack

$ sidebutton init example.com

Generates skill-pack.json, an empty _skill.md template, and the _roles/ directory. One domain per pack — name after the web app's primary domain.

2

Document the web app and add workflows

Write a _skill.md for each module. Include real CSS selectors (or data-testid / ARIA labels), the shape of each entity, the states every page can be in, and every gotcha you had to debug the hard way. Add role playbooks in _roles/ and automation workflows as .yaml files. The more concrete the better — agents are literal readers.

Workflows become MCP tools. Every .yaml at the pack root registers as a run_workflow target. The file's id becomes the tool ID; the inputs: block becomes the typed argument schema. An agent sees it automatically on the next tools/list refresh.

# example/summarize_article.yaml
id: example_summarize_article
title: Summarize Article
description: Fetch a URL and return a bullet summary in a given style.
inputs:
  url:
    type: string
    description: Article URL to summarize
  style:
    type: string
    description: 'tldr | executive | detailed'

steps:
  - id: fetch
    action: browser.navigate
    with:
      url: "{{ inputs.url }}"

  - id: read
    action: browser.snapshot
    with:
      selector: article, main

  - id: summarize
    action: llm.generate
    with:
      prompt: |
        Summarize the following article in {{ inputs.style }} style.
        Return 3-6 bullet points.

        {{ steps.read.output }}

output: "{{ steps.summarize.output }}"

Forty step types are available: browser primitives (navigate, snapshot, click, type), control flow (loop.for, if, retry), LLM (llm.generate, llm.classify, llm.decide), shell, terminal, and workflow composition.

3

Validate

$ sidebutton validate

Checks the manifest, verifies every referenced _skill.md exists, parses YAML workflows, warns on missing roles, and flags broken selectors if you ship a test fixture.

Preview locally before publishing. Install your in-progress pack with sidebutton install ./your-skill-dir, then open the dashboard at http://localhost:9876 to verify modules, roles, and workflows rendered correctly. The Workflows tab lists every registered tool with its parameter form — run each once with realistic inputs before you publish. The same registry is visible to any connected MCP client via list_workflows().

4

Publish

$ sidebutton publish

Validates again, packages, and publishes. Public packs ship to the community registry — no approval queue, no fee — and show up at /skills for anyone to sidebutton install <your-domain>. Private packs stay within your account; sidebutton publish --private requires a logged-in session and is only installable by you and your team.

Skill authoring guidelines

  • One domain per pack — name your pack after the domain: github.com, linear.app, jira.atlassian.com.
  • Document real selectors — use the app's actual CSS selectors, data-testid attributes, or ARIA labels. Synthetic selectors age faster than the real ones.
  • Keep modules focused — one module per page or feature area. Agents load modules on demand; smaller modules means cheaper context.
  • Include automations — add YAML workflows for common operations (CRUD, navigation, data extraction). Workflows are what make the skill useful beyond documentation.
  • Test with a real agent — verify end-to-end with Claude Code or Codex before publishing. What parses locally may still confuse an agent at inference time.
  • Choose public or private — public packs ship to the community registry and are installable by anyone; private packs stay within your account and require login to publish and install. Set the visibility in skill-pack.json.
  • No credentials or API keys in any pack — public or private. Skills ship domain knowledge (selectors, data models, workflows), not secrets. Inject secrets at runtime via environment variables instead.

After you publish

Published skills become first-class entries in the SideButton skills registry. Each gets a detail page with its modules, role playbooks, and workflows fully rendered — shareable, searchable, and indexable by Google. Anyone running SideButton can install your skill with a single command; their coding agent picks it up on the next session.

Updates ship the same way as the initial publish: bump the version in skill-pack.json and run sidebutton publish again. Installed clients can choose to pin a version or track latest. Because skills are versioned directories, diffs are reviewable and rollbacks are trivial — the normal git flow, applied to agent context.

Frequently asked questions

What is agentic AI and how does a skill pack fit in?

Agentic AI refers to AI systems that take multi-step actions on their own — plan, call tools, reflect, iterate — instead of only answering prompts. Skill packs give an agentic AI the domain knowledge needed to act inside a specific web app: selectors, data model, page states, and proven workflows. Without a skill pack the agent guesses; with one it operates.

Do I need to run my own MCP server to create a skill?

No. sidebutton init works offline — it scaffolds files only. You need a running SideButton MCP server when you want to test the skill against a real coding agent like Claude Code or OpenAI Codex. Run sidebutton to start it on localhost.

Is publishing free? What about private skill packs?

Public packs are published to the community registry free of charge — no approval queue, no fee. SideButton also supports private packs for internal-only skills; private publishing requires a logged-in account and keeps the pack visible only to you and your team. The SideButton MCP server itself is open-source (Apache 2.0), so the public loop — author, publish, install, run — is zero-cost either way.

How do I test my skill before publishing?

Run sidebutton validate to check the manifest, selectors, and YAML workflows. Then install it locally with sidebutton install ./your-skill-dir and register SideButton with your coding agent (see the Claude Code or Codex setup guide). Drive the skill through real prompts before publishing to catch edge cases that only show up in live sessions.

Who owns a published skill?

You retain copyright on everything you author. Publishing grants the SideButton community a license to redistribute the pack — by default Apache 2.0, but you can declare a different open-source license in skill-pack.json. Packs with proprietary or non-commercial licenses are not accepted in the public registry.

Related