gusgad/service-agent-by-sap / .agents/skills/agent-skills
agent-skills
VerifiedUse when creating a new skill under .agents/skills/, editing an existing one, or deciding whether a technique deserves to become a skill at all - covers SKILL.md structure, the description field, and how to keep a skill discoverable and token-efficient.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.2 KB |
SKILL.md
View on GitHub---
name: agent-skills
description: Use when creating a new skill under .agents/skills/, editing an existing one, or deciding whether a technique deserves to become a skill at all - covers SKILL.md structure, the description field, and how to keep a skill discoverable and token-efficient.
---
# Agent Skills — Writing and Maintaining Skills
A skill is a reusable reference: a technique, pattern, or tool that a future agent session should be able to find and apply without re-deriving it from scratch. This skill is about authoring *other* skills in `.agents/skills/`.
## When to Create a Skill
**Create one when:**
- The technique wasn't obvious and took real effort to work out
- It will plausibly be needed again, in this repo or elsewhere
- It applies broadly, not to one specific file or one-off situation
- Other contributors (human or agent) would benefit from finding it
**Don't create one for:**
- A one-off fix specific to a single bug
- Something already well documented upstream (framework docs, official guides)
- A project convention that's mechanically enforceable — put that in ESLint config or a CI check, not prose
- A narrative about how a problem was solved once — skills are reusable guides, not incident reports
## Anatomy
```
.agents/skills/
skill-name/
SKILL.md # required — the whole skill, if it fits
reference.md # optional — only for heavy reference material
scripts/ # optional — only for reusable executable tooling
```
Flat, searchable namespace. Most skills in this repo need only `SKILL.md` — reach for a separate file only when something genuinely doesn't belong inline (a 300-line API reference, a script meant to be run rather than read).
## SKILL.md Structure
**Frontmatter — exactly two required fields:**
```yaml
---
name: skill-name-with-hyphens
description: Use when <specific triggering conditions>.
---
```
- `name`: letters, numbers, hyphens only
- `description`: third person, states **only when to use it** — not what it does or how. This is what an agent scans to decide whether to open the file at all.
**Why "when," never "how," in the description:** if the description summarizes the workflow, an agent can act on the summary and skip reading the actual skill — including the parts of the process the summary left out. Keep the description to triggering conditions; put the process in the body where it will actually get read before being followed.
```yaml
# Bad — summarizes the process, invites skipping the body
description: Use for code review - dispatch a reviewer, read findings, fix critical issues
# Good — only the trigger
description: Use when completing a task or before merging, to catch issues before they ship
```
**Body**, roughly in this shape:
```markdown
# Skill Name
## Overview
What is this, in 1-2 sentences. The core principle.
## When to Use
Concrete symptoms/situations that signal this applies (and, if non-obvious, when NOT to).
## Core Pattern / Process
The actual technique. Inline code for short patterns; a linked file for heavy reference.
## Common Mistakes
What goes wrong and the fix, ideally as a table.
```
## Discovery: Make It Findable
A skill nobody finds isn't a skill, it's dead prose.
- **Keywords matter.** Use the words an agent would actually search for: real error messages, symptom names, tool/command names — not just abstract category words.
- **Name by what it does or its core insight**, verb-first or gerund where natural: `systematic-debugging`, not `debugging-techniques`; `writing-plans`, not `plan-creation`.
- **Keep it lean.** SKILL.md content loads into context whenever the skill is used — every unnecessary paragraph is a tax on every future invocation. Cut narrative, cut redundant examples, keep one excellent example instead of three mediocre ones.
- **Cross-reference by name, not by force-loading.** Point at another skill in this repo by its path/name ("see the `verification-before-completion` skill under `superpowers/`") rather than inlining its whole content — that keeps each skill focused and avoids drift when the referenced skill changes.
## Writing Style
- Imperative voice for instructions ("Run the test", not "You should run the test")
- Explain *why* a rule exists, not just that it exists — a rule with a reason survives edge cases better than a bare "MUST"
- One complete, realistic, copy-adaptable example beats three generic templates
- Prefer tables for anything scannable (common mistakes, quick reference); prose for anything sequential
## Before Calling a New Skill Done
- [ ] `name` and `description` are both present and `description` states only *when*, not *how*
- [ ] The body would make sense to someone who has never seen this repo before
- [ ] No dangling references to files that don't actually exist in this skill's directory
- [ ] It's short enough that loading it doesn't dominate the conversation it's used in
- [ ] It was tried once for real, on a real task, before being trusted
## Updating an Existing Skill
Same bar as writing a new one. If a skill turns out to have a gap (an agent following it still got something wrong), that's a signal to tighten the skill itself — add the missing case, don't just fix it in code and leave the skill stale for the next session.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |