Writing Agent Skills: A Practical Guide to Authoring and Engineering Skill Packages

1. Redefining the Problem: A Skill Is Not a Prompt, It Is a Packaged Capability

In agent frameworks, a skill is an extension unit that bundles the knowledge, procedures, reference material, and executable code needed for a class of tasks, so the agent can load and invoke it autonomously when the situation calls for it. Most agent frameworks already support extension points of this kind in one form or another, so before you start writing, it helps to correct three common misconceptions.

Misconception 1: a skill is just a block of text. Text is indeed the most common entry point, but the real value comes from the directory structure behind it: executable scripts, reference documents, template skeletons, sample data, and configuration examples can all ship with the skill. The agent can discover these files, traverse them, and read them on demand — which means deterministic operations go to code execution while judgment and trade-offs stay with the model. Most frameworks also let a skill declare additional configuration, such as a tool allowlist, model selection, or hooks triggered on certain lifecycle events.

Misconception 2: more skills is better. Context window space is a scarce resource for an agent. Skill metadata typically stays resident in context, while the body is loaded on demand. A growing skill count therefore raises fixed overhead directly and worsens “selection ambiguity” — when two skills have blurry description boundaries, trigger accuracy drops noticeably.

Misconception 3: a skill is an extension of prompt engineering. A more accurate framing: a skill is the intersection of knowledge engineering and process engineering. It decomposes “how an expert does this” into three layers:

• Metadata layer: name and description. Resident in context. Its only job is to let the agent decide “should I use myself right now?”
• Body layer: the workflow loaded on demand, answering “how do I do this step by step?”
• Resource layer: scripts, templates, and reference material, read on demand, answering “what do the details look like?”

Once you understand these three layers, the rest of the authoring techniques have something to attach to.

2. The First Principle: Do Not State the Obvious

Mainstream agents already have reasonably solid coding fundamentals, and they can understand your codebase through retrieval tools. So if a skill mostly restates general best practices — “name variables meaningfully,” “write tests before committing,” “handle exceptions properly” — it will barely change model behavior and will only consume context.

An effective skill supplies incremental information: information the model is likely to get wrong without reading it, or information that visibly changes behavior once read.

A typical positive example is a frontend design skill. Its goal is not to teach the model how to write CSS, but to suppress the “standard answer aesthetic” in the model’s default output: the same generic sans-serif pairing everywhere, linear gradient backgrounds that run from brand color to pale tones, and the catch-all layout of rounded cards with soft shadows. Such a skill should contain:

1. A negative list: explicitly enumerate forbidden patterns — far more effective than abstractly asking for “good design sense”;
2. Alternative strategies: concrete font stacks, color constraints, and spacing systems, so the model has an executable substitute path;
3. Verifiable criteria: for example, “no gradient backgrounds anywhere on the page” and “heading-to-body font size ratio of at least 1.5,” so output can be checked quickly by script or by a human.

To decide whether a piece of information is worth writing down, ask three questions:

• If you leave it out, will the model most likely get it wrong?
• If you write it in, will the model’s behavior change observably?
• Can this constraint be verified?

If the answer to at least two of the three is “no,” delete it.

3. Directory Organization: Write Skills as Executable Assets

The value density of a skill depends heavily on its directory design. A usable skeleton:

skill-name/
├── SKILL.md              # entry point: metadata + workflow description
├── references/           # long-form reference material, read on demand
│   ├── api-conventions.md
│   └── error-codes.md
├── templates/            # templates and skeleton code
│   └── service-skeleton/
├── scripts/              # deterministic work delegated to code
│   ├── validate.py
│   └── migrate.py
└── assets/               # sample data, icons, configuration examples

Example metadata for an entry file (field names vary; follow your framework’s documentation):

---
name: db-schema-review
description: Use when the user submits a database table structure change, an index
             adjustment, or a data migration script. Produces a structured review
             with high-risk changes and incompatibilities flagged.
allowed-tools: Read, Grep, Glob, Bash
---

Three organizing principles:

Progressive disclosure. Keep only the decision flow and an index in the entry file, move detailed specifications out to references/, and state explicitly in the body “when you encounter situation X, read file Y.” This way the model pays the context cost only when it genuinely needs to.

Push determinism down. Any work that yields a single correct answer through code — format validation, batch renaming, dependency checks, data transformation, report generation — should be a script, with the invocation command given directly in the body. This buys four things: reproducible results, very low token cost, script code that can have unit tests, and execution that is naturally auditable.

Examples over rules. One high-quality end-to-end example (sample input → intermediate artifact → final output) is often more effective than ten lines of rule text, because it conveys format, granularity, and trade-off criteria at the same time.

4. Writing the Description: The Only Basis on Which a Skill Gets Selected

However good the body is, the skill will never load if the description cannot be matched. Key points:

• Write trigger conditions, not a feature list. Use the “use when…” pattern and enumerate the real phrasings a user might actually say;
• Concrete nouns beat abstract nouns. “Table structure change, index adjustment, migration script” is easier to match accurately than “database-related work”;
• State negative boundaries. For example, “relational database changes only; not applicable to cache layer or message queue configuration.” Boundary statements significantly reduce false triggers;
• Control overlap. Periodically review all skill descriptions; excessive synonymy causes selection jitter.

5. Lifecycle Hooks: Turning “Hope the Model Does It” into “It Always Happens”

Hooks can automatically run validation or formatting logic on specific events, such as after a file write completes or before a command executes. Their real value is eliminating probability: reminding the model in the body to “remember to run the formatter” never hits 100%, while binding the behavior to a hook makes it deterministic.

But the blast radius of a hook extends beyond a single session, so use care:

• Idempotency: repeated triggers of the same event must not accumulate side effects;
• Failure degradation: a failed hook should be logged and allowed through, never silently block the main flow;
• Timeout control: avoid a hook slowing down every interaction;
• Least privilege: request only the capabilities the validation needs; forbid credential reads or outbound network calls inside hooks;
• Gradual rollout: validate high-risk hooks on a restricted directory and a small user group first, observe for a while, then roll out fully.

6. When to Share: A Clear Decision Line

Once a skill is written, evaluate it along five dimensions before sharing:

1. Reusability: does it still hold across teams and projects? If it depends tightly on one repository’s private directory structure, it is not ready for direct sharing and should be abstracted first;
2. Abstraction level: does it contain internal domain names, intranet addresses, internal system names, accounts, or secrets? All of these must be replaced with placeholders or injected from environment variables;
3. Maintainability: is there a clear owner and a version number? An unmaintained shared skill quickly becomes a liability;
4. Measurable benefit: can you state what it saves — review time, defect rate, context overhead?
5. Compliance: has the sample data and log snippets shipped with the package been de-identified, and is the license clear?

For distribution, a team can use a shared repository with per-directory management; across teams, versioned artifact distribution over object storage or package-manager releases works. Whichever route you take, use semantic versioning and specifically flag behavior changes in the changelog — for a skill, an adjustment to workflow steps is usually far more disruptive than a parameter rename.

7. Evaluation and Operations: A Skill You Don’t Measure Can’t Iterate

A skill is a product, not a document, and it has to be operated like one.

Build a regression set. Collect 20–50 tasks from real usage, covering three kinds of samples: typical cases, boundary cases, and easily confused cases (to check whether the skill fires when it shouldn’t).

Track three metrics.

Metric	What it means	How to improve
Trigger accuracy	Does it fire when it should and stay quiet when it shouldn’t?	Rewrite the description, add negative boundaries
Task success rate	Does the output meet expectations?	Add examples, externalize specifications, script the work
Context overhead	Load size of metadata plus body	Trim the body, apply progressive disclosure

Let production data drive. Use logs and monitoring to observe the real invocation distribution, and focus on two anomalies: skills with zero invocations over a long period (description no longer matches, or the need has disappeared), and skills with abnormally high invocation counts (possibly over-triggered, or absorbing work that should have been scripted). Human adoption rate and human edit rate are the two most direct signals of skill quality.

8. Security Baseline

• Follow least privilege: a skill requests only the tools required for its own responsibility;
• Never hardcode credentials in a skill package; inject everything at runtime through the environment;
• Treat external input as untrusted content: material pulled in from web pages, documents, or third-party data may contain prompt injection and must not be executed directly as instructions;
• High-risk operations (deletion, bulk modification, production changes, external publishing) require human confirmation;
• Pin dependency versions, make provenance explicit, and avoid introducing unaudited executable code;
• Keep complete execution logs for later retrospection and accountability.

9. Pre-Delivery Checklist

1. Does the entry file’s description contain explicit trigger conditions and negative boundaries?
2. Does the body keep only incremental information, with all “obvious” general advice removed?
3. Has deterministic work been pushed down into scripts, and is it testable?
4. Is long-form reference material externalized, with the reading trigger stated in the body?
5. Is there at least one high-quality end-to-end example?
6. Are there any hardcoded paths, internal domains, accounts, or secrets?
7. Are permission declarations minimal, and do high-risk operations have a confirmation step?
8. Is there a regression set, and has a baseline evaluation been run against it?
9. Is there an owner, a version number, and a changelog?
10. After launch, is there monitoring for invocation volume, success rate, and human edit rate?

10. Conclusion

The value of a skill lies not in its number but in converting the tacit experience that “only veterans know” inside an organization into engineering assets that are distributable, versionable, and measurable. The build path is usually: validate value against one real, high-frequency pain point; let evaluation data drive iteration; and only then consider sharing and scale.

In practice, skills rarely stand alone. They need to work with general engineering capabilities — code hosting and review workflows, CI pipelines, logging and monitoring with alerting, and versioned artifact distribution over object storage — to form a complete loop. The skill captures methodology; the platform guarantees permissions, observability, and version consistency. Baidu AI Cloud’s work on intelligent coding and developer productivity is one example of this “methodology plus platform governance” combination, which is the key step in moving agent capability from an individual technique to team productivity.