GitHub explains agent skills: reusable SKILL.md files that any agent can run

GitHub published a guide to agent skills on its blog on 12 November 2026, written by Andrea Griffiths. It describes skills as reusable, reviewable instructions for repeatable engineering work, and uses two example projects, Proof Agent and Data Forge, to show how to structure them.

What happened

In its GitHub Blog post on agent skills, GitHub defines a skill as a folder under version control, built around a SKILL.md file that says when and how to perform a task. The post says it grew out of a GitHub Universe 2026 session on the same topic, given with a data engineering manager from Procore.

The central point is a boundary. Instructions can move between agents, but the environment running them must still supply tools, credentials and permissions. GitHub's example: a skill can explain how to query a database, but it does not grant access to it.

Key details

• One job per skill. GitHub recommends a clear task, input and output. Its Proof Agent skill checks AI-generated changes against the original request using a separate verifier, because an agent that reviews its own work may be swayed by its own reasoning. The stated rule is "self-verification is not verification."
• Invocation guidance lives in the skill. Proof Agent's SKILL.md has a "When to Verify" section, with the remaining instructions covering what the verifier reviews and what evidence it must include.
• Several skills can form a workflow. In the Data Forge support-desk example, a request for metrics counting incidents created and resolved starts the process.
• Project details go in a manifest, not in the skills. The forge-init skill discovers source tables and naming conventions and writes them to a resolved manifest that the other skills read.
• Team standards stay separate. forge-lint supplies the rules; discovered patterns are not automatically rules, so people should confirm or change them where business judgment matters.
• Shared execution path. forge-dbx reads the manifest and picks a Databricks or DuckDB adapter, so other skills do not each carry their own connection logic.
• Human review stays in the loop. forge-builder coordinates work from the issue to a pull request containing pipeline code, schema changes and tests, with a person reviewing proposed decisions along the way.

Try it

The post shows the frontmatter for Proof Agent and the manifest for the support-desk demo:

---
name: proof-agent
description: Adversarial verification of AI-generated work. Spawns an independent verifier to check for false claims, broken code, and security issues.
---

project:
  name: "support-desk"
  store_name: "support_metric_store"
platform:
  engine: "duckdb"
  pipeline_framework: "spark_python"
  duckdb_dir: "warehouse"

GitHub's portability check: could another team use the same skills with its own manifest without rewriting them?

When a skill is the wrong tool

GitHub says skills suit bounded, repeatable work that benefits from reusable judgment, such as a checklist, release, migration or metric pipeline. If a workflow needs a stable interface, shared state, an audit trail, long-running control, or permissions enforced outside the model, it recommends building an application instead.

The manifest has the same limit. It can select DuckDB for the local demo, but it cannot install the DuckDB CLI or grant database access; those remain setup tasks for the environment and its user.

Why it matters

The guide is a company post, so its design advice is GitHub's own recommendation rather than an independent evaluation. The patterns are still concrete: split responsibilities across small skills, keep project-specific values in a reviewable manifest, and verify work with an agent other than the one that produced it. For related thinking on structuring what an agent sees, see AWS's four layers of context engineering in Deep Insight.