An agent skill is a versioned directory built around a SKILL.md file that spells out when and how to perform a repeatable task. The instructions themselves travel across agents, but the environment must still supply the tools, credentials, and permissions to act on them. A skill can describe how to query a database; it cannot grant access to that database.
The examples below come from two demos: Proof Agent, which checks AI-generated code changes against the original request, and Data Forge, which builds data pipelines from cooperating skills.
Scope each skill to a single job
A skill is easiest to reuse when its job, input, and output are explicit. Proof Agent addresses a self-assessment problem: if the same agent reviews its own work, its explanation can color the review. A separate verifier examines the changes and must back its findings with evidence. Its frontmatter names the task and states its purpose:
---
name: proof-agent
description: Adversarial verification of AI-generated work. Spawns an independent verifier to check for false claims, broken code, and security issues.
---
Underlying the design is one rule: self-verification is not verification. A When to Verify section in the SKILL.md defines the invocation conditions, and the remaining instructions specify what the verifier reviews and what evidence belongs in its findings.
Bounded workflows versus applications
Skills suit repeatable work that gains from reusable judgment — a checklist, a release, a migration, or a metric pipeline. When a workflow requires a stable interface, shared state, an audit trail, long-running control, or permissions enforced outside the model, an application is the better choice.
Compose skills and share context between them
A pipeline whose correctness lives in four engineers' heads turns those four engineers into the roadmap; every change waits on their availability. Data Forge models how to write parts of that judgment down. In the support-desk pipeline example, a request for metrics counting incidents created and resolved drives the workflow. The forge-init skill first discovers source tables and naming conventions and records them in a resolved manifest that the other skills read for project context.
The forge-builder skill then carries the work from issue to pull request, calling forge-dbx to query the data platform and forge-lint to apply team standards while the pipeline is designed and built. A person reviews decisions along the way, and the pull request delivers pipeline code, schema changes, and tests. Because each skill owns one responsibility and shares project context rather than rediscovering it, a change to one step leaves the others untouched.
Separate configuration from instructions
Hardcoding each project's names, database, or conventions into skills defeats portability. In the same example, a manifest declares the project, metric store, and platform so skills pick up the right details without carrying them in their instructions:
project:
name: "support-desk"
store_name: "support_metric_store"
platform:
engine: "duckdb"
pipeline_framework: "spark_python"
duckdb_dir: "warehouse"
Discovered details belong apart from team standards. forge-init inspects existing schemas and code patterns, while forge-lint supplies the rules to follow before code is generated — a pattern found in a repository is not automatically a rule worth preserving. Keep discovered details reviewable so people can confirm or adjust them where business judgment is required. A practical portability test: could another team adopt these skills with its own manifest and no rewrites?
One execution path for related skills
forge-dbx gives every Data Forge skill a single way to reach the data platform. It reads the manifest and selects a Databricks or DuckDB adapter, so no skill carries its own connection and query logic. The manifest can choose DuckDB for the local support-desk demo, but it cannot install the DuckDB CLI or grant database access; those stay setup responsibilities of the environment and its user. The manifest picks the engine, and the host provides the access.
Build in checkpoints and human approval
The support-desk workflow runs seven phases, each with a human checkpoint. Before a phase advances, the workflow confirms the previous one finished; before schema changes execute, it requests approval.
Proof Agent applies the same principle to review. A GitHub Actions workflow hands the verifier 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 from the changed files. The Action performs a static review of the diff — it does not execute code or run tests. The demo sets block-on-fail: false so findings stay advisory; by default a FAIL fails the check, blocking the merge where the check is required. Test results and merge requirements belong in the repository's CI checks and rules.
Package per client and confirm the setup
Multi-client support can mean maintaining duplicate copies of one set of instructions. Data Forge treats skills/*/SKILL.md as the source and uses a packaging script to generate client files: .claude-plugin/plugin.json for Claude Code, .cursor-plugin/plugin.json for Cursor, and .github/agents/*.agent.md for GitHub Copilot. The script includes a check mode for CI:
node scripts/package.mjs --check
Clients vary in available models, tools, credentials, and permissions. After installing a skill, confirm the client recognizes it for the intended task, loads its references, can use the required tools, and returns the evidence the skill demands.
Practices to carry forward
- Keep business context in one file. Store project names, schemas, and conventions in a manifest that each skill reads instead of restating them, giving the team a single visible place to update configuration.
- Give related skills one platform path. Share commands and connection logic for queries, jobs, and schema changes so access is easier to follow and behavior is easier to verify in each client.
- Guide with instructions, verify with checks. Let a skill state which standards apply and when to seek approval, add human review where judgment is needed, and catch problems with tests and CI. If a check must block a merge or deployment, configure that in the repository's rules.
Begin with the task you are tired of explaining: record what it needs, where it stops, and what a reviewer sees, then run it on another agent and refine it from what you learn.



