effective-agent-skills – skill Agent & Tự động hóa cho agent AI

Agent Skills: A Complete Guide

When to Use

• Use when creating, editing, reviewing, or debugging an agent SKILL.md file.
• Use when you need quality guidance for triggers, examples, limitations, and safety notes.

A consolidated reference on what agent skills are, why they exist, how they work, and how to write effective ones.

---

1. What agent skills are

An Agent Skill is a folder containing a SKILL.md file (YAML frontmatter + markdown instructions), plus optional subfolders for scripts, references, and assets that the agent loads on demand.

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code (CLIs, validators, helpers)
├── references/       # Optional: detailed docs loaded only when needed
└── assets/           # Optional: templates, fonts, static files

Skills are an open standard (agentskills.io), originally created by Anthropic and adopted by OpenAI Codex, Cursor, Gemini CLI, Microsoft Agent Framework, Google ADK, and 40+ other agent products. The format is portable, but discovery paths, tool names, invocation controls and permissions require testing in each target host.

---

2. Why this abstraction exists

Base LLMs are generalists. Real work requires procedural knowledge, organizational context, and repeatable workflows. Every prior alternative had a failure mode:

| Approach | Problem |

|---|---|

| Stuff it into the system prompt | Always loaded → context bloat at scale |

| Re-paste instructions each session | No version control, no consistency |

| Fine-tuning | Slow, expensive, opaque, vendor-locked |

| MCP servers alone | Give the agent tools but no workflows for using them |

Skills solve four problems at once:

• Context efficiency — instructions load only when relevant
• Repeatability — multi-step procedures become auditable workflows
• Composability — multiple skills combine at runtime per task
• Portability — same files work across vendors and surfaces

Mental model: skills are to LLMs what man pages, runbooks, and team handbooks are to engineers — reference material loaded into working memory only when the task demands it.

---

3. How they work — progressive disclosure

The architectural core. Three-stage loading:

Level 1 — Discovery (~100 tokens per skill, always in context):

Only name + description from frontmatter are injected into the system prompt at startup. Agent knows the skill exists and when it applies. You can install dozens of skills with negligible overhead.

Level 2 — Activation (<5,000 tokens, loaded on match):

When the user's request matches a skill's description, the agent reads the full SKILL.md body into context.

Level 3 — Execution (bounded by host resources, on demand):

The agent reads referenced files (references/foo.md) or runs scripts (scripts/validate.py) only as needed. Scripts can execute without their source being loaded into context at all.

Bundled files avoid eager token loading, but size, trust, runtime and packaging limits still apply. Read/review scripts before granting execution; loading on demand is not a security guarantee.

---

4. SKILL.md anatomy

---
name: skill-name
description: What this skill does AND when to use it. Include trigger phrases the user will say.
---

# Skill Name

## Quick start
[Minimal working example]

## Workflow
[Step-by-step procedure with checklists]

## Output format
[What the user/agent should expect back]

## Advanced
[Link to references/ for rarely-needed detail]

Frontmatter constraints:

• name uses lowercase letters, digits and hyphens, 1–64 chars, matches its parent directory, and has no leading/trailing or consecutive hyphens
• Avoid < and > in frontmatter (they can inject into the system prompt)
• Invalid YAML silently prevents loading

Optional standard fields:

• Invocation controls such as disable-model-invocation are host-specific extensions, not guaranteed core-spec fields. Check the target host’s current documentation and actual discovery behavior before relying on manual-only activation.

---

5. Two design philosophies

Skills tend to fall into one of two patterns. Both are valid; they solve different problems.

Pattern A — Capability primitives (tool wrappers)

The skill is a thin wrapper over a deterministic CLI or script. Logic lives in code. SKILL.md teaches the agent how to invoke it.

• Adds: new capabilities (search, email, browser, API access)
• Reliability via: shell tools, not prompts
• Typical length: 30–80 lines, mostly command examples
• Use when: the bottleneck is "the agent can't do X"

Pattern B — Process primitives (cognitive disciplines)

The skill encodes a methodology the agent should follow. Pure prompt engineering — no scripts needed.

• Adds: structured workflows (TDD, code review, design alignment, debugging loops)
• Reliability via: explicit procedure, checklists, validation loops
• Use when: the bottleneck is "the agent's output quality or process is bad"

A mature setup uses both. Pattern A gives the agent better tools. Pattern B gives it better methods for using them.

---

6. How to write effective skills — do this

Description as routing contract

The description is the only thing the agent sees before deciding to load the skill. If a skill does not trigger, inspect the description alongside installation, discovery, host settings and model routing; no universal failure percentage is established.

Include three elements:

1. What the skill does (one phrase)

2. When to use it (trigger phrases, situations)

3. Differentiator vs related skills (prevents routing conflicts)

Pattern: "X via Y. Use for [situations]. [Differentiator: no Z required / faster than W / handles edge case V]."

Never summarize the full workflow in the description. If the description contains a step-by-step summary of *how* the skill works, the agent tends to follow that summary and skip loading the body. Describe *what* and *when*, never *how*. The description answers "should I open this skill now?" — not "what are the steps?"

Keep SKILL.md lean

• Beyond a certain length, you're usually encoding logic that should be in a script or referenced file

Bash-first, prose-second

Concrete command examples with inline comments beat prose explanations. The agent pattern-matches on syntax. Show, don't describe.

Push determinism into code

Anything fragile, repetitive, or where variation is a bug → script. Use markdown only for tasks requiring judgment.

Match strictness to task fragility (degrees of freedom)

Scale instruction rigidity to how costly a wrong move is:

• Loose natural-language heuristics when many approaches are valid (e.g. code review).
• Pseudocode or templates when there's a preferred pattern but variation is acceptable (e.g. report format).
• Exact scripts and strict step lists when the workflow is fragile, error-prone, or consistency-critical (e.g. migrations, document patching).

Build validation loops

The single biggest output quality improvement: state a verify → fix → re-verify loop explicitly.

• Document skills: visual QA pass before delivery
• Code skills: tests pass + zero type errors before completion
• Data skills: schema validation before output

State-check before action

Don't assume setup is done. Instruct the agent to verify state, then branch:

First check if X is configured: [command]
If not, walk the user through setup: [steps]

Just-in-time loading with explicit pointers

Tell the agent exactly when to read each referenced file:

For standard cases, follow the steps below.
For [specific edge case], read references/edge-cases.md first.

Keep references one level deep

Link referenced files directly from SKILL.md. Never build chains (SKILL.md → advanced.md → details.md → actual.md) — the agent may preview nested files only partially and miss critical instructions. Add a table of contents to any reference file longer than 100 lines.

Document output formats

If your script returns structured data, show the agent what it looks like. Enables reliable downstream parsing.

Defer to --help for completeness

List the 80% common operations in SKILL.md. Tell the agent to run tool --help for the rest. Keeps SKILL.md small without losing functionality.

Compose primitives, don't bundle workflows

One skill = one capability or one discipline. Resist bundling concerns into "the X workflow." Multiple small skills combine at runtime; one large skill is rigid.

Cite established principles when applicable

If your skill encodes a known engineering methodology (TDD, DDD, red-green-refactor), name the source. Gives the agent a coherent model to align with and gives users a way to verify the design.

Persistent artifacts for cross-session memory

Skills can write to repo-level files (CONTEXT.md, ADRs, decision logs) that future agent sessi

… (nội dung đầy đủ có trong gói tải về)