Managing Skills as Software Dependencies

Select and govern skills like dependencies

Prefer first-party skills for vendor-specific systems, pin versions, and audit every adopted package for instructions, scripts, dependencies, permissions, and data access. A skill is executable supply-chain input, not harmless documentation.

Apply different trust defaults: first-party vendor skills may be trusted but still pinned; organization-curated skills need internal PR review; community skills require a full audit and aggressive version pinning. Popularity, marketplace rank, or a polished README is not evidence of maintenance or safety.

The scale makes manual intuition impossible: the source reports public marketplaces had crossed 40,000 listings by early 2026. Treat that as context for a selection process, not a quality signal. The catalog needs source class, maintainer, last review, pinned version, permissions, overlap status, and evaluation evidence before a skill can be enabled.

Selection should produce an adoption record: source and version, owner, supported runtime, permission scope, overlapping skills, eval-suite link, and rollback path. If two skills claim the same request, resolve the boundary before installation rather than relying on the model to improvise.

Watch for quality smells:

• The body is above roughly 5,000 tokens or keeps accumulating edge-case sections.
• Two domain teams could plausibly own it, or the description joins unrelated jobs with “and.”
• The team cannot write three concrete eval cases.
• The description begins with “a helpful skill for” instead of naming triggers, inputs, output, and when not to use.
• Deterministic logic is expressed as repeated warnings rather than scripts or gates.
• It duplicates an MCP connector, hard-codes paths or secrets, or has no referenced resource despite a long body.

Ownership follows the business rule. Product and platform teams own the format, evaluation harness, observability, and release process; the domain team that changes the underlying policy owns the skill's content and approves its releases. Each skill needs exactly one accountable owner, even when several teams contribute.

The practical build and deployment contract

A minimal SKILL.md should expose name, a verb-led description with use and do-not-use cues, version, license, optional allowed-tools, and author metadata. Its body should define when to use, when not to use, the ordered workflow, referenced edge cases, examples, output format, and anti-patterns. Frontmatter is an interface: validate it in CI and treat every permission addition as a security change.

---
name: refund-duplicate-charge
description: Investigate duplicate charges for a known order and draft a resolution. Use for billed-twice requests. Do NOT use for declined cards, delivery status, or executing refunds.
version: 1.0.0
allowed-tools: [lookup_order, check_duplicate_charge]
metadata:
  owner: payments-operations
---
 
# Refund duplicate charge
## When to use
- The user identifies or can provide an order with two suspected charges.
## When NOT to use
- A payment was declined, delivery is late, or the user asks only for refund status.
## Workflow
1. Resolve the order ID; ask if it is missing.
2. Retrieve the order and suspected charges.
3. Check duplicate-charge eligibility using the referenced market policy.
4. Return an evidence-backed draft; never execute a refund in this tier.
## Output format
- Order, evidence, eligibility, proposed next step, and unresolved questions.

Read the example as a contract. The description owns routing; allowed-tools prevents accidental write access; the workflow explains order and stopping behavior; the output shape makes an eval possible. Policy detail still belongs in references/, and deterministic normalization still belongs in scripts/. A vague instruction such as “handle refunds helpfully” offers none of these controls.

Use predictable names: snake_case for the directory, kebab-case and preferably a gerund for the skill name; avoid utils, helper, tools, vendor prefixes, and internal jargon. Description limits vary by runtime, so keep it concrete and economical: one job, trigger phrases, inputs, expected output, and negative boundary.

The source's practical bounds are at most 200 characters for an API description and 1,024 characters in YAML, with many authors aiming for roughly 50 words. Treat the runtime's real schema as authoritative, validate the limit automatically, and never gain brevity by deleting the negative boundary.

Before deployment, require this checklist:

• Frontmatter lint passes; no hard-coded paths, secrets, or untrusted dependencies.
• Deterministic scripts have unit tests; skill evals run in CI with a minimum pass threshold.
• Description was reviewed by someone other than the author.
• Positive, negative, execution, regression, and 5–15-skill token-load cases pass.
• Permission and security scans are clean; action paths have approval, idempotency, and rollback evidence.
• Cross-tool install paths and activation behavior are tested for every supported runtime.
• Organization-level registry/admin provisioning and owner/on-call records are updated.

Good quality principles keep the package small: run the task manually before encoding it; explain why a rule exists instead of stacking ALWAYS; make every instruction verifiable; bundle repeated deterministic work; and split whenever “one skill, one job” no longer holds. The deployment artifact is a signed release record linking the pinned package, coverage matrix, approvals, runtime matrix, rollback version, and monitoring dashboard.