Encode engineering knowledge in reusable skills

Learning objective

Encode organization-specific engineering knowledge in a reusable coding-agent skill. Decide what belongs in the skill, structure it for on-demand use, and validate that it guides agents correctly. This lesson does not cover how to choose among every coding-agent customization mechanism.

Core idea

Treat a skill as a versioned, on-demand runbook for an agent. It converts knowledge that engineers repeatedly explain—such as service scaffolding, database migration, or release preparation—into a package that an agent can discover and follow.

A useful skill has four layers:

1. Trigger: Metadata says what the skill does and when to use it.
2. Procedure: Instructions define decisions, steps, and failure handling.
3. Evidence: References, examples, and templates preserve exact local knowledge.
4. Verification: Scripts or checks show whether the result meets the organization’s standard.

The agent initially sees only each skill’s metadata, loads SKILL.md when the task matches, and reads supporting files as needed. This progressive disclosure keeps unrelated knowledge out of the active context (Google Antigravity Agent Skills).

How it works

Choose one repeatable task

Start from an observed gap, not from all knowledge the organization owns. Good candidates are repeated tasks where a general coding agent lacks local context or makes inconsistent decisions.

Define the task’s inputs, output, decision points, failure cases, and acceptance checks. Keep one skill focused on one capability. Split unrelated work into separate skills so their descriptions do not compete for the same requests.

Make discovery precise

An Agent Skills package is a directory with a SKILL.md file. For a portable skill, its YAML frontmatter contains a lowercase, hyphenated name that matches the directory and a description that states both what the skill does and when to use it. These fields form the discovery interface, so a vague description can prevent activation or cause false activation (Agent Skills specification).

For example, the following metadata names a bounded organizational task:

---
name: create-payments-service
description: >-
  Creates a payments HTTP service from the approved template. Use when adding
  a new service owned by the Payments team.
---

The body should define required inputs, ordered actions, approved choices, stop conditions, validation commands, and the expected report. Explain non-obvious constraints when the reason helps the agent handle an edge case.

Separate judgment, facts, and execution

Keep the main SKILL.md short enough to act as a navigation and execution guide. Put detailed standards in references/, canonical output examples in examples/, and exact templates in assets/. Refer to those files with paths relative to the skill root. The open specification recommends loading these resources only when needed and keeping references shallow (Agent Skills progressive disclosure).

Only a matching task loads SKILL.md, and only a step that needs one reads a supporting file.

Use prose for contextual judgment and an example when the desired shape is easier to demonstrate than describe. Use a script for a deterministic or fragile operation, such as validating a schema. A script reduces variation, but it also becomes executable software that requires testing, dependency documentation, and security review.

Distribute and maintain the skill like code

Place a repository-specific Antigravity skill under .agents/skills/create-payments-service/. Antigravity also supports user-global skills, but organization-specific repository knowledge usually benefits from living with the code it governs. If several repositories need the same capability, publish one reviewed source and distribute a pinned version instead of maintaining copies. Antigravity plugins can package skills with related customizations when a team needs a larger distribution unit (Antigravity plugins).

Keep the skill in source control with an owner and review process. Test at least three behaviors: it activates for relevant requests, stays inactive for unrelated requests, and produces a compliant result for representative edge cases. Also test coexistence with the other skills the agent receives. Official enterprise guidance recommends version control, security review, representative trigger evaluations, and rerunning evaluations before promoting a new version (Skills for enterprise).

Key distinctions and trade-offs

A skill packages how to perform a task. It does not replace these other sources of control:

Too little detail forces the agent to guess; too much consumes context after activation and makes updates harder. Use heuristics when several solutions are valid, and use exact commands or scripts when sequence and consistency are critical.

Architecture / decision scenario

A payments platform team finds that new services repeatedly use the wrong logging fields, omit ownership metadata, and configure retries inconsistently. The platform architect creates create-payments-service, not a broad “payments knowledge” skill.

Its description targets requests to create a Payments-owned service. The main instructions collect the service name and data classification, select one of two approved retry profiles, render the service skeleton, and run the repository checks. A reference file explains the approved logging fields and retry decision table. An asset contains the exact ownership manifest. A tested script validates the generated structure.

The team stores the package in Git, requires platform and security review, and tests positive, negative, and ambiguous activation prompts. It publishes a pinned version to consuming repositories. When the logging standard changes, the owner updates the reference and validator, reruns the evaluation suite, and promotes a new version.

The skill improves reuse because it combines routing, procedure, exact source material, and verification. It does not receive production credentials or gain permission to deploy. Those remain separate controls.

Common exam traps

• Putting the entire engineering handbook in one skill instead of selecting one repeatable task with a clear trigger.
• Writing a description that explains the topic but not when the agent should activate the skill.
• Treating SKILL.md as the only possible file and embedding long references, templates, and scripts directly in it.
• Assuming a skill creates a tool connection or grants permission to use one.
• Treating strong instructions such as “must” as a hard security control.
• Sharing a skill without testing activation, non-activation, output quality, coexistence, and bundled executable code.

What to remember

• Model a skill as a versioned, on-demand runbook for one repeatable task.
• Use precise metadata for discovery and focused instructions for execution.
• Separate contextual judgment, reference knowledge, exact assets, and deterministic scripts.
• Test both activation and task results, then review and version the whole package like code.
• Keep tools, credentials, permissions, and mandatory enforcement outside the skill.

Knowledge check

References

• Google Antigravity, Agent Skills
• Google Antigravity, Plugins
• Google Codelabs, Authoring Google Antigravity Skills
• Agent Skills, Specification
• Anthropic, Skill authoring best practices
• Anthropic, Skills for enterprise