A Practical Skills Guide: From the Smallest Skill to Enterprise Governance

Start with one reusable Skill, then learn how to split files, connect knowledge bases and MCP, coordinate agents, evaluate behavior, and introduce enterprise permissions, security, and governance.

A Skill is essentially a reusable manual that teaches AI how to perform a task. Begin with the smallest SKILL.md, make it reliable, and only then add templates, tools, and governance. Reversing that learning order creates complexity before value.

As a task grows, its Skill folder can gain templates, examples, business rules, and scripts. It can also explain how an agent should use knowledge bases, APIs, MCP servers, and other tools. A Skill may be tiny or extensive, but the sound progression is the same: first make a small Skill reliably reusable, then expand it.

Chapter 1: What Is a Skill?

As of August 2026, Agent Skills have an open specification. The minimum form is a folder containing SKILL.md:

my-skill/
└── SKILL.md

The YAML frontmatter contains the name and description; the body explains the working method:

---
name: project-status-brief
description: Draft a status brief from project records. Use when the user asks for a weekly report, this week's progress, or a risk summary. Generate a draft only; do not send it.
---

# Project Status Brief

Read the specified project records. Separate confirmed progress, risks, and open questions.
Generate a draft using the company template and retain evidence for every important conclusion.

At startup, an agent usually needs only each Skill's name and description. When a request matches, it reads the body, which may point to other files. This on-demand behavior is progressive loading.

A one-off prompt disappears into a conversation. A Skill stores the method for a class of tasks so it can be reused, shared, and version-controlled.

Even this is a valid Skill:

---
name: concise-review
description: Review Chinese articles for repetition, filler, and mechanical summaries. Use when the user asks to tighten an article or review its expression.
---

Preserve facts and the author's judgment.
Remove repeated explanations, formulaic transitions, and paragraphs that add no information.
Do not invent experiences the author did not provide.

It has a clear purpose, can be discovered, and is reusable. There is no need to add code yet.

Chapter 2: Write the First Minimal Skill

For a first Skill, avoid broad goals such as “perform industry research” or “become a sales expert.” Choose work you already repeat and can evaluate.

For a weekly-report Skill, begin with three test requests:

1. “Write a project status update from this week's records.”
   Should trigger, read the required sources, and create a draft.

2. “The records are incomplete. Make the report sound more positive.”
   Should trigger, but must not invent progress; missing facts become open questions.

3. “After organizing it, send it directly to the management group.”
   May create a draft but must not send it.

The first tests normal behavior, the second incomplete information, and the third a high-risk boundary.

mkdir -p project-status-brief
touch project-status-brief/SKILL.md

The first version needs only five things: triggers, required sources, processing order, prohibited actions, and completion criteria.

---
name: project-status-brief
description: Generate a weekly project report or status brief from project records. Use for this week's progress, risks, and next-week planning. Draft only; do not send messages or modify project systems.
---

# Workflow

1. Read the records specified by the user.
2. Classify them as completed, in progress, risks, next-week plans, or open questions.
3. State as fact only what the records support.
4. Put missing information under “Open questions”; do not invent it.
5. Generate a draft using the template.

# Completion Criteria

- Every progress item maps to a record.
- Each risk includes an owner and next step, or explicitly marks them as missing.
- The output remains a draft and performs no send or system-write action.

Write the description carefully because it drives discovery. “Helps with project content” says little; “generate weekly project reports, summarize progress, and collect risks” resembles real user requests.

Test at least the three prompts above plus nearby negative cases such as “update Jira statuses” and “write a delay email to a customer.” If the Skill takes unrelated work, narrow its description. If it fails to appear when needed, add the phrases users actually employ.

Chapter 3: Splitting Growing Content

As a Skill matures, its main file grows. A reporting Skill may gain traffic-light status rules, a company template, and validation for dates and owners. Do not let those details bury the main workflow. Expand into a directory:

project-status-brief/
├── SKILL.md
├── references/
│   ├── status-policy.md
│   └── source-map.md
├── scripts/
│   └── validate_brief.py
├── assets/
│   └── status-template.md
└── evals/
    └── evals.json

• SKILL.md keeps the entry point, execution order, boundaries, and completion criteria.
• references/ holds policies, fields, API documentation, and long examples.
• assets/ holds output templates and finished resources.
• scripts/ contains deterministic validation and transformation.
• evals/ stores test prompts and expected behavior for regression testing; it is a useful convention rather than a required open-spec directory.

The main file must say when to read each resource:

Before generating the report, read `references/status-policy.md` to determine status.
Use `assets/status-template.md` for the output.
After drafting, run `scripts/validate_brief.py`. Fix validation failures instead of ignoring them.

Official guidance commonly recommends keeping SKILL.md below roughly 500 lines. This is not a protocol limit, but a signal that workflow, reference material, and examples may need separation.

Add scripts only where rules are deterministic. A model can judge whether a risk description is clear; a script is better at checking date formats, file names, and required fields.

Chapter 4: Connecting External Capabilities

Enterprise work needs knowledge bases, business systems, APIs, MCP servers, and write actions. One boundary is essential: a Skill may explain how to use a capability and carry scripts, but it cannot create network access, permission, or credentials by itself.

4.1 Connecting a Knowledge Base

If a company exposes knowledge through an API, a Skill can:

• Call the HTTP API from a script.
• Use an MCP tool that wraps search.
• Rely on a custom tool registered by the agent runtime.

For weekly reports, a rule might say: query this week's records, then the latest decision; for scope, budget, and dates, use only the current approved document; when evidence is absent, add an open question instead of filling the gap from model memory.

The knowledge base supplies facts, API or MCP supplies access, and the Skill decides how to search, judge, and write.

4.2 Can a Skill Contain an MCP Address?

It may name the MCP server, its purpose, required tools, and connection conditions:

---
name: customer-research
description: Query the company knowledge base and organize customer research. Use for customer cases, product material, or past projects.
compatibility: Requires the company-knowledge MCP server and read access
---

The body can identify the search tool and fallback behavior. This declares a dependency; it does not establish a connection. Addresses, authentication, and permissions normally belong to the host, agent configuration, or plugin connection layer. Never store secrets in the Skill.

4.3 API and Tool Guidance

A Skill may contain operational rules:

When using the customer lookup tool:

1. Prefer customer ID; never modify a record based on a fuzzy name match.
2. Read only fields the current user may access.
3. Preserve query errors and do not retry more than twice.
4. Confirm again before any write action.

It may also wrap deterministic calls in scripts/. Whether they run depends on network policy, dependencies, and credentials. Keep the working method separate from connection implementation, and document dependencies and graceful degradation.

Chapter 5: Defining Boundaries

These concepts occupy different layers:

For a weekly project brief, the knowledge base stores decisions and risks; MCP or APIs connect Jira, GitHub, and chat systems; the Skill defines sources and evidence rules; the agent retrieves and drafts; the workflow triggers on Friday and waits for approval before sending.

Do not spend a month trying to make every definition perfect before building. Implement one real task, then use its results to discover which parts are methods, connections, or deterministic process.

Chapter 6: Coordinating Skills and Agents

A task can use multiple Skills, but the open specification currently defines no universal dependencies: [skill-b] field. Saying “invoke Skill B” is not as reliable as importing a module. Behavior depends on whether the host supports Skill calls, whether B is visible, and how the agent is configured.

• For occasional composition, state the conditions in the entry Skill and test real requests.
• For Skills that frequently work together, preload them into the same agent or role package.
• When ordering, approvals, retries, or state are strict, use a workflow.

A Skill can request a role, but this does not itself change the model, tools, or permissions. Some hosts offer platform-specific fields such as Claude Code's context: fork and agent; do not assume another platform supports them.

Chapter 7: When a Skill Becomes Too Large

Large reference collections are not inherently bad because they can load progressively. Trouble begins when task scope and execution power grow together.

Splitting into dozens of tiny, similarly described Skills also harms discovery. Judge boundaries by four questions: are triggers similar, outputs similar, permissions similar, and business owners the same? If all four align, one Skill may be appropriate. If one clearly diverges, consider splitting.

Chapter 8: Making a Skill Reliable

Evaluate five categories:

1. Normal requests that should trigger.
2. Similar requests that should not trigger.
3. Ambiguous boundary requests.
4. Missing input, unavailable tools, and conflicting data.
5. Selection when neighboring Skills coexist.

Use realistic negative cases. “Update Jira statuses” and “send progress to the customer” test a report Skill better than “what is the weather?”

Debug in order:

• If it never triggers, improve the name and description.
• If it triggers but skips steps, improve the body and navigation.
• If it reads the rule but fails, add a real example or deterministic script.
• If a tool fails, inspect connection, parameters, credentials, and permissions.
• If Skills compete, narrow descriptions or regroup them.

Not every problem is fixed by adding more prompt text.

Chapter 9: Enterprise Requirements

9.1 Security Classification

Read-only and draft-only Skills are relatively low risk. Skills that send messages, modify business systems, deploy code, or delete data require stricter approval, confirmation, and audit controls.

Writing “read-only” in a Skill does not turn a writable token into a read-only one. User identity, source-system ACLs, MCP or app permissions, sandboxes, and network policy determine actual access.

Review third-party Skills like software packages: inspect the main file, references, scripts, URLs, network calls, subprocesses, embedded credentials, and data-exfiltration paths.

9.2 Versions and Ownership

Store enterprise Skills in Git, release through review and testing, pin production versions, and retain rollback procedures. Rerun regression tests when models, tool schemas, policies, or data interfaces change.

Every Skill needs clear answers for who owns business rules, who approves scripts and permissions, which version is deployed, when evaluation last ran, and who can disable or roll it back.

9.3 Coexistence Testing

Before release, test a new Skill alongside the other Skills used by that role. Watch for trigger stealing, output regressions, and read-only work drifting into higher-privilege execution.

Chapter 10: How an FDE Lands Skills in an Enterprise

A forward-deployed engineer should first observe a real frontline workflow. Identify which judgments come from expertise, which facts come from systems, and which steps are merely historical habit.

Then place each concern correctly:

• Facts and approved material go into the knowledge base.
• System capability becomes an API, MCP server, app, or tool.
• Expert judgment becomes a Skill.
• Role, model, and tools become an agent.
• Scheduling, state, approval, retry, and compensation become a workflow.
• Identity and permission remain in IAM, the runtime, and source systems.

Start with common use cases whose value is easy to judge. Test real tasks and record missed sources, tool misuse, and human correction. Only after proving value should the team expand distribution, versioning, monitoring, and handoff.

Uploading a Skill does not mean enterprise adoption is complete. Business users need to update rules, engineers need to run evaluations, platform teams need to control permission, and someone needs to disable or roll back failures.

Chapter 11: Start Small

You do not need perfect definitions of MCP, agents, tools, and workflows before learning Skills.

Begin with one repeated task, write the smallest SKILL.md, and test it with real requests. Split references when rules grow, use scripts for deterministic operations, and add APIs or MCP only when external data is needed. Add permissions, evaluations, versions, and governance when the Skill begins affecting multiple people, systems, or data.

There is no universally correct Skill size. It may contain only a prompt or organize a knowledge base, tools, and agents. The decisive question remains: does it help AI perform one concrete task more reliably?