AivexaNewsSearch
AI news for builders and product teamsChecked every hour

Build once, run on any agent: A practical guide to agent skills

Collected Nov 12, 2026

GitHub has published a practical guide to building agent skills, drawn from a GitHub Universe 2026 session titled "Build once, run on any agent: A practical guide to agent skills." The post is written by Andrea, a Senior Developer Advocate at GitHub, and covers work presented live with Shishir Tewari, Senior Manager of Data Engineering at Procore. The central definition: an agent skill is a versioned directory centered on a SKILL.md file that describes when and how to perform a repeatable task.

The guide draws an important boundary early. Skills hold instructions, not access. A skill can describe how to query a database, but it does not grant access to that database — the environment still has to supply the tools, credentials and permissions needed to carry the instructions out. For developers, that means a skill is portable across agents only in the sense of the written procedure; the host runtime determines what can actually be executed.

On authoring, the recommendation is to define one clear job with a known input and output, plus an explicit statement of when the skill applies. The post's example, Proof Agent, tackles a familiar failure mode: an agent reviewing its own output may let its own explanation bias the review. Proof Agent instead spawns a separate verifier that inspects changes and produces evidence. Its frontmatter gives the skill a name and description — adversarial verification of AI-generated work that checks for false claims, broken code and security issues — and the SKILL.md body carries a section on when to invoke it, followed by what the verifier reviews and what evidence findings must include. The stated rule is that self-verification is not verification.

For larger workflows, the guide uses Data Forge, a set of cooperating skills for a support-desk metrics pipeline that counts incidents created and resolved. The premise is organizational: when the judgment that makes a pipeline correct lives in four people's heads, each change depends on their availability. Data Forge splits that knowledge into skills with defined responsibilities sharing project context. An initialization skill, forge-init, discovers source tables and naming conventions and writes them to a resolved manifest; a builder skill, forge-builder, coordinates the work from issue through to a pull request; forge-dbx queries the data platform; and forge-lint applies team standards while the pipeline is designed and built. A human reviews proposed decisions along the way, and the pull request carries pipeline code, schema changes and tests. Because each skill owns one responsibility, a change to a step touches one skill rather than all of them.

The guide is also candid about fit. Skills suit bounded, repeatable work that benefits from reusable judgment — a checklist, a release, a migration, a metric pipeline. Workflows requiring a stable interface, shared state, an audit trail, long-running control or permissions enforced outside the model are better served by an application. That dividing line is useful: skills encode procedure, while applications encode policy and state.

Configuration is deliberately kept out of the skills themselves. A manifest holds project name, metric store name, platform engine and pipeline framework so the same skills can serve another team without rewriting. In the demo the manifest selects DuckDB locally with a spark_python pipeline framework, and forge-dbx reads the manifest to pick a Databricks or DuckDB adapter, giving every skill one shared path to queries, jobs and schema changes instead of separate connection logic. The manifest chooses the engine; the host still provides the CLI and database access. The guide also warns against treating observed repository patterns as rules — discovered details should be reviewable and separable from team standards, so people can confirm or change them where business judgment is required. A portability test is offered: could another team run these skills against its own manifest unmodified?

Control points are built into the workflow. The support-desk pipeline has seven phases, each with a human checkpoint, and the workflow verifies the prior phase is complete before advancing and requests approval before schema changes run. In the Proof Agent setup, a GitHub Actions workflow supplies the verifier with the original request and the code changes but withholds the coding agent's own assessment; the verifier returns PASS, FAIL or PARTIAL and must cite evidence in the changed files. The action performs a static review of the diff and neither executes code nor runs tests. In the demo, block-on-fail is set to false so findings are advisory; by default a FAIL fails the check and blocks a merge where the check is required. The intent is to keep test results and merge requirements in the repository's own CI checks and rules rather than in the skill.

For multi-client support, Data Forge keeps skills/*/SKILL.md as the source of truth and uses a packaging script to generate client-specific files: .claude-plugin/plugin.json for Claude Code, .cursor-plugin/plugin.json for Cursor and .github/agents/*.agent.md for GitHub Copilot. The script has a check mode suited to CI, run as node scripts/package.mjs --check. Because clients differ in available models, tools, credentials and permissions, the guide advises verifying after install that the client recognizes the skill for the intended task, loads its references, can use the required tools and returns the evidence the skill asks for.

The closing practices are three: keep business context in one manifest file rather than duplicating names, schemas and conventions across skills; give related skills one consistent execution path to the platform; and let instructions guide the work while checks verify it, with human review at judgment-heavy decisions and merge-blocking requirements configured in repository rules. The suggested starting point is the task you are tired of explaining — write down what it needs, where it stops and what a reviewer sees, then try it with another agent and refine it.

Why it matters: Teams running coding agents on more than one client now have a concrete pattern — a single SKILL.md source, a generated per-client package and a shared manifest — for avoiding duplicated, drifting instructions. The separation of instructions from credentials and permissions, and the insistence that a verifier independent of the author do the checking, are directly actionable for anyone wiring agents into pull request review or data pipelines. In practice, my reading is that the heaviest lift is not writing skills but building the manifest, packaging script and CI checks around them, which is where most of the maintenance cost will land.

Read at GitHub Blog · AI & ML

Based on reporting from the original publisher. Visit the source for full context and later updates.

Publisher excerpt

Agent skills capture repeatable engineering work in files teams can review and reuse, while tools, project context, and permissions remain specific to the host that runs them. The post Build once, run on any agent: A practical guide to agent skills appeared first on The GitHub Blog .