All posts
2 min readby Romiel Inolino

GitHub's guide to agent skills: one SKILL.md per job, project details in a separate manifest, and self-verification is not verification

AI agentsagent skillsGitHub CopilotClaude CodeAI engineering

If you keep re-explaining the same task to an AI agent, GitHub's new guide says that task should be a skill file.

What happened

GitHub published a practical guide to agent skills, based on a GitHub Universe 2026 session with Procore. A skill is a versioned directory centered on a SKILL.md file that describes when and how to do a repeatable task. GitHub is clear about the limit: a skill can describe how to query a database, but it does not grant access to that database. Tools, credentials and permissions still come from the agent that runs it.

The guide's examples carry the lessons. Proof Agent uses a separate verifier to check AI generated changes, on the rule that self-verification is not verification. Data Forge splits a data pipeline into skills with one job each, all reading project details from one shared manifest instead of hardcoding them. A person reviews proposed decisions along the way.

In the Data Forge example, GitHub keeps the SKILL.md files as the source and uses a packaging script to generate versions for Claude Code, Cursor and GitHub Copilot, with a check mode for CI. GitHub's docs say Copilot reads project skills from .github/skills, .claude/skills or .agents/skills. The guide also says when not to use a skill: if a workflow needs a stable interface, shared state, an audit trail, long running control or permissions enforced outside the model, build an application.

My take

This maps cleanly onto automation work for clients. The process knowledge, how this client names deals, which fields matter, when to ask a human, is usually in one person's head. Writing it down as a skill makes it reviewable and portable across agents.

Three rules I would take from it:

  1. One skill, one job. A lead qualification skill should not also write the follow up email.
  2. Client specifics go in a config file, not in the instructions, so the same skill works for the next client.
  3. Never let the agent grade its own work. Use a second check or a test.

And respect the boundary GitHub draws. Anything that moves money or needs an audit trail belongs in a real workflow tool like n8n, with the skill guiding the judgment calls inside it.

More posts