Microsoft defines a custom skill for a declarative agent as a directory containing a required SKILL.md instruction file and optional resources and scripts. The agent loads the package when the task requires it. This progressive disclosure can keep context focused and make repeated work more consistent.
The technical package is new, but the management problem is familiar. A procedure used by several people needs an owner, controlled inputs, quality criteria and change history. When a skill includes executable scripts or authoritative reference files, it also becomes a small software and knowledge product.
Choose the right level of reuse
Use a personal prompt when the task is one-off, exploratory or depends mainly on the user’s current judgment. Use an agent instruction when the rule applies to nearly every interaction with that agent. Use a skill when a recognizable task repeats, benefits from a stable sequence or assets, and should be loaded only when needed.
A separate workflow or application is more appropriate when the process must follow deterministic steps, maintain transaction state, enforce approvals or guarantee an integration result. A skill can guide work, transform files and use sandboxed scripts, but it should not be asked to impersonate a transactional system.
Create a skill when three conditions are present:
- The task repeats across users or cases.
- A stable owner can define what good looks like.
- Packaging instructions, resources or scripts materially improves reliability.
If the underlying policy changes weekly or every case needs unstructured expert judgment, first improve the process rather than encoding its ambiguity.
Define the eight-field skill contract
Before writing SKILL.md, agree the operating contract.
1. Purpose
Name the single business outcome. “Support finance” is too broad. “Prepare a quarterly business review from the approved input workbook” is testable.
2. Trigger
Describe the requests that should activate the skill and nearby requests that should not. Poor boundaries cause the wrong procedure to enter context.
3. Inputs
List accepted formats, required fields, source authority, freshness and sensitivity. State what happens when information is missing or contradictory.
4. Output contract
Define structure, audience, required citations or calculations, file format and acceptance criteria. Include what the skill must never infer.
5. Permitted capabilities
Record required resources, scripts, connectors and tools. Microsoft’s current custom-skill documentation states that skill scripts run in a sandbox without runtime network access or package installation. The agent may use enabled external capabilities through orchestration, but the skill design must not assume unsupported script behavior.
6. Tests
Maintain representative, boundary and adversarial cases with expected properties. Tests should cover selection of the skill as well as the quality of its output.
7. Ownership and version
Name the process owner and technical custodian. Record version, change reason, approver and compatible agents. Current platform reuse limitations make this record especially important when similar packages exist in several agents.
8. Review and retirement
Set a review date, usage signal and retirement condition. Reference files, policies and templates become stale even when the instructions do not change.
A worked example: quarterly business review
A finance team repeatedly turns an approved workbook into a management presentation. Individuals use different prompts, KPI definitions and slide structures, so reviewers spend time reconciling format rather than discussing performance.
The team creates a skill with one purpose: prepare a draft quarterly business review. It includes KPI definitions, the approved slide template, instructions for variance commentary and a tested script that produces charts from the workbook. The output contract requires source-sheet references and marks missing values instead of estimating them.
The test set contains a normal quarter, a workbook with a missing region, a negative value that is valid, a renamed worksheet and a malicious instruction placed inside a free-text comment. Acceptance checks chart totals, missing-data handling, citation to the input and correct refusal to follow embedded instructions.
Finance owns definitions and the template. The agent team owns packaging, tests and release. A new revenue definition changes the skill version and triggers regression tests before deployment. That is a controlled operating procedure, not a clever prompt saved in a shared document.
Use a five-stage lifecycle
Design
Observe the real work, choose a narrow boundary and complete the contract. Remove conflicting source material before packaging it.
Test
Evaluate activation, output and failure behavior. Include sensitive content, malformed inputs and instructions embedded in source files. Inspect any script and confirm its sandbox dependencies.
Release
Review the complete package, not only SKILL.md. Record the version and approved agent. Preview testing is necessary but not sufficient for a business release.
Observe
Track usage, successful completion, correction effort, inappropriate activation and source freshness. User satisfaction alone can hide factual or procedural defects.
Revise or retire
Change one controlled version at a time, rerun the regression set and communicate material behavior changes. Retire duplicate skills and obsolete resources rather than allowing silent variants to multiply.
Avoid the department-handbook skill
A common failure is one large skill containing every instruction, policy and template for a function. Its trigger becomes vague, ownership fragments and any update has a wide blast radius. Split skills when the outcome, data sensitivity, owner, permission or release cadence differs.
The opposite failure is excessive fragmentation. If users cannot predict which of ten nearly identical skills applies, the library has moved complexity rather than removed it. Maintain a catalogue with purpose, owner, status and supported agent, and test routing across adjacent skills.
Skills can turn expert practice into scalable capability. They can also distribute an outdated rule at machine speed. Amplified Pi helps organizations select the useful procedures, build the package and establish the evidence and ownership needed for reliable reuse.