liveBook · Manning

Agent skill

As explained in Context Engineering

A reusable set of instructions and resources that extends an agent's capabilities for a specialized workflow.

An agent skill is a reusable package of instructions and resources that extends an agent with a specialized workflow. Skills keep procedural knowledge out of the global system prompt, so the agent can discover capabilities without carrying every procedure in its active context. section 2.3 section 2.6

Skills use progressive disclosure. The agent first sees lightweight metadata, then loads the full instruction file when a task matches, and opens bundled resources as the work requires them. The agent harness manages discovery and instruction injection, so accurate descriptions and reliable activation matter. section 2.3 section 7.2.1

A skill is a directory centered on SKILL.md:

  • YAML frontmatter requires a name and description. The name should be short, stable, lowercase, and hyphenated; the description states both the capability and when to use it. section 2.3.1
  • The Markdown body contains the procedure, such as steps, output schemas, validation rules, and examples. section 2.3.1
  • Optional scripts, references, assets, and tests support deterministic operations, conditional background material, reusable templates, and testing. section 2.3.1
Listing 2.2 Content of the SKILL.md file for the git-conventional-commits skill
---
name: git-conventional-commits
description: Generates standardized git commit messages following the
conventional commits spec. Use this when the user asks to commit
changes or "wraps up" a task.
license: MIT
metadata:
  version: "1.0.0"
---

# Git Conventional Commits

## Instructions
When the user asks to commit, follow these steps:
1. Identify the primary change in the code.
2. Categorize the change into one of these types: feat, fix, docs, style,
refactor, perf, test, or chore.
3. Format the message as: `<type>(<scope>): <description>`

## Examples
- feat(auth): add Google OAuth support
- fix(ui): resolve alignment issue on mobile

This SKILL.md combines an activation description with a procedure for producing conventional commit messages. section 2.3.1

To create a skill, write SKILL.md and place its directory where the target harness scans. For example, Claude Code scans .claude/skills/ in a project or ~/.claude/skills/ globally; compatible platforms may use .agents/skills/ or ~/.agents/skills/. Depending on the harness, a user can invoke a skill explicitly with slash syntax or let a matching request activate it. section 2.5.2

Standardizing meeting notes

A project-notetaker skill can trigger on raw meeting notes and instruct the agent to produce a title, attendees, key decisions, and an action-item table with task, owner, and due date. The description selects the workflow; the body supplies the output structure. section 2.5.2

A skill is useful for a repeatable CLI procedure whose consequences matter: it can specify allowed commands, their order, how to interpret output, and when to ask for confirmation. It is not required for an agent to use CLI tools. section 4.3.2

Listing 4.2 Example of a SKILL.md file for a workspace analyzer skill
---
name: workspace-analyzer
description: Inspect a workspace, identify temporary files, and perform
only approved cleanup or organization steps.
---

# Workspace Analyzer

## Instructions
1. Use `find` or the platform equivalent to locate temporary files such as
`.tmp`, `.bak`, and editor backup files.
2. Run `git status --short` before making changes so tracked and untracked
files are easy to distinguish.
3. Present the findings to the user and wait for confirmation before
deleting or moving anything.
4. Delete only the approved files, then rerun the scan to verify the
workspace is clean.
5. When reorganizing files, group them by extension into clearly named
folders and report every move.

The workspace analyzer specifies a scan, approval, cleanup, and verification sequence. section 4.6.2

Instructions express intent; they do not enforce it. For destructive actions, the harness must enforce approval, and deletion should run in a sandboxed working directory. Before relying on a skill, test its triggering accuracy, completeness, safety, and performance on real tasks. File-based packaging also supports versioning and auditing. section 4.6.2 section 11.3.1 section 2.3

How Context Engineering covers it

How deep it goes
Details skill structure, discovery, activation, supporting files, creation, and safety checks.
Examples
Uses commit-message generation, meeting-note formatting, and workspace cleanup to illustrate skills.
What you can do after
Build a custom skill from scratch and install it in a compatible agent's discovery directory.
How it connects
Connects skills to system prompts, progressive disclosure, agent harnesses, and CLI tools.

Also explained in

Compare how 6 books explain agent skill →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Context Engineering. The section links point to the parts of the book it draws on.