ReadingResearchRadarInvestment framework
Sign in / Sign up
← Back to reading
NewsMaterial4 min readDisconfirmAI Editorial

GitHub Developer Advocate Andrea Griffiths: A Three-Layer Separation Method for Building Agent Skills Portable Across Clients

Andrea Griffiths details the file architecture of agent skills: SKILL.md carries reusable task instructions, manifest stores project-specific configurations, and the host environment provides tools and permissions. With a packaging script, a single skill source can generate client adaptation files for Claude Code, Cursor, and GitHub Copilot, enabling 'build once, run on any agent.'

2026-11-13 06:54 GMT+8

How many times this week did you re-explain the same thing to the same agent? And how many times did you have to ask a colleague with deep institutional knowledge to solve a specific problem? In this practical guide published on November 12, 2026, Andrea Griffiths, a developer advocate at GitHub, identifies this repetitive labor as the core pain point that agent skills aim to solve: context should not disappear in chat logs, nor be locked inside one person's head.

An agent skill is a versioned directory centered on a SKILL.md file, describing when and how to complete a repeatable task. Griffiths emphasizes a key boundary: skills describe the instructions for doing things, not the permissions to do them. A skill can describe how to query a database, but it does not grant access to that database. Tools, credentials, and permissions are still provided by the host environment running the skill. This means the skill itself is portable, but portability does not equal plug-and-play—the target environment must already possess the tools and access conditions assumed by the skill.

With this boundary established, Griffiths presents the core method for making skills truly reusable across projects and teams: separating project configuration from skill instructions. In the Data Forge support-desk pipeline example, the forge-init skill first probes source tables and naming conventions, writing the discovered project details into a resolved manifest; subsequent skills read this manifest to obtain the project context they need, rather than guessing independently or hardcoding specific names into their instructions. The manifest describes the project name, metric store, and platform engine, while the skill describes the rules and standards for doing the work. A pattern found in a repository does not automatically equate to a rule that should be preserved, so discovered details must be reviewable, with parts requiring business judgment confirmed or modified by humans.

Sign in / Sign up
ReadingResearchRadarInvestment framework

How multiple skills coordinate is the second key issue. The forge-builder skill coordinates the entire workflow from issue to pull request, calling forge-dbx to query the data platform and forge-lint to apply team standards. forge-dbx provides a unified path for data platform access for all Data Forge skills: it reads the manifest and selects either a Databricks or DuckDB adapter, so each skill does not need to define its own connection and query logic. Griffiths summarizes this design principle in one sentence: when steps change, you modify one skill, and the rest remain untouched.

Cross-client portability is the final link in this methodology. The Data Forge example retains skills//SKILL.md as the sole source file, using a packaging script to generate client-specific adaptation files: .claude-plugin/plugin.json for Claude Code, .cursor-plugin/plugin.json for Cursor, and .github/agents/.agent.md for GitHub Copilot. The script also includes a CI check mode to ensure client files remain synchronized with the source. After installing a skill, Griffiths recommends verifying item by item: whether the client recognizes the skill for the intended task, loads referenced files, can use the required tools, and returns the evidence requested by the skill.

Griffiths also delineates the applicable boundaries of the skill methodology. Skills are suitable for bounded, repeatable work that benefits from reusable judgment—such as checklists, release processes, migrations, and metric pipelines. If a workflow requires stable interfaces, shared state, audit trails, long-running control, or permissions enforced outside the model, it is better suited to building an application. This distinction reminds readers: skills are carriers for capturing judgment, not a panacea for replacing infrastructure.

Her three practical recommendations boil down to: put business context into a single file for all skills to read; give related skills a consistent path for platform access; use instructions to guide work, and checks and manual approval points to verify work. If a check must block a merge or deployment, that requirement should be configured in repository rules, rather than declared within skill instructions.

Finally, Griffiths offers a pragmatic starting point: begin with the task you are tired of explaining repeatedly. Write down what it needs, where it ends, and what a reviewer sees. Then try it with another agent, improving it as you learn what works.

Sources

  • github.blogThe GitHub Blog↗
Continue researching →