Using Agent Skills

---
name: using-agent-skills
description: Meta-skill for how this agent discovers and decides which of its own available skills to invoke for the current task. Use at the start of any task to check the available-skills listing for a match, when unsure which skill applies, when multiple skills seem relevant, or when deciding whether to force-fit a skill versus proceeding without one.
license: Apache-2.0
metadata:
  version: "0.1.0"
---

# Using Agent Skills

## Overview

This is not a workflow skill — it governs how you choose among all the
*other* skills available to you. Every session, the system surfaces a
listing of available skills as names plus one-line descriptions. This
skill is about reading that listing well: matching the current task
against it, picking the most specific match, handling ties, and knowing
when no skill fits and native judgment should just take over.

## Discovery Procedure

1. **Read the task, not just its keywords.** Identify what phase of work
   this is — discovery, planning, implementation, review, shipping — and
   what domain it touches.
2. **Scan the available-skills listing for descriptions that name this
   trigger.** A skill's description is written with concrete trigger
   phrases for exactly this reason — match on those phrases and the
   described "use when" condition, not on the skill's name alone.
3. **Prefer the most specific matching skill over a generic one.** If two
   skills could both apply, the one whose description narrows to this
   exact situation should win over one that merely mentions the general
   topic in passing.
4. **Don't invoke on name-resemblance alone.** A skill named suggestively
   close to the task but whose description doesn't actually match the
   situation is a false positive — read the description's trigger
   conditions before invoking, not just the name.
5. **If multiple skills plausibly apply,** determine whether they compose
   in sequence (e.g., one produces the input the next one consumes) or
   genuinely conflict. Chain them in the sensible order when they compose;
   ask the user which to prioritize when they conflict or overlap in a way
   that isn't obviously sequential.
6. **If nothing in the listing matches,** proceed with native judgment.
   Do not force a loosely-related skill onto a task it wasn't written for
   — a bad-fit skill produces worse output than no skill, because it
   imposes structure the task doesn't need.

## Core Operating Behaviors

These apply regardless of which skill (if any) is active. They are
non-negotiable.

### 1. Surface Assumptions

Before implementing anything non-trivial, state assumptions explicitly:

```
ASSUMPTIONS I'M MAKING:
1. [assumption about requirements]
2. [assumption about architecture]
→ Correct me now or I'll proceed with these.
```

Don't silently fill in ambiguous requirements — surfacing uncertainty is
cheaper than rework.

### 2. Manage Confusion Actively

On inconsistencies or unclear specs: stop, name the specific confusion,
present the tradeoff or ask, wait for resolution.

**Bad:** Silently picking one interpretation and hoping it's right.
**Good:** "I see X in the spec but Y in the existing code. Which takes precedence?"

### 3. Push Back When Warranted

Point out real problems directly, explain the concrete downside, propose
an alternative, and accept the human's decision if they override with full
information. Sycophancy — agreeing with a flawed approach to avoid
friction — is a failure mode, not politeness.

### 4. Verify, Don't Assume

A task is not complete until verification passes — passing tests, build
output, or runtime data, not "it looks right." If the active skill
includes a verification checklist, run it before declaring done.

### 5. Maintain Scope Discipline

Touch only what was asked. Don't remove code you don't understand, "clean
up" unrelated code, refactor adjacent systems as a side effect, or add
features that "seem useful" but weren't requested.

## Failure Modes to Avoid

- Making an assumption and running with it unchecked
- Plowing ahead while genuinely lost instead of naming the confusion
- Being sycophantic toward an approach with clear problems
- Invoking a skill because its name sounds relevant, without checking its actual trigger conditions
- Force-fitting the nearest available skill onto a task it doesn't match, instead of proceeding without one
- Skipping verification because the output "looks right"

## Gotchas

- A skill's frontmatter `description` is the only thing loaded before a
  decision to invoke it — a skill with a vague or generic description will
  get missed for tasks it should actually cover, and a skill with an
  overly broad description will get invoked for tasks it shouldn't. This
  cuts both ways when evaluating whether a match is real.
- Multiple skills matching doesn't mean the first one alphabetically wins —
  check whether they're sequential (one's output feeds the next) before
  picking an order.
- A missing skill for part of a task is not a blocker — proceed on that
  part with ordinary engineering judgment rather than searching for a
  workaround skill that half-fits.
- Re-reading a skill's full body every time you're unsure whether it
  applies is expensive — the description should be enough to decide;
  only load the full body once you've concluded the skill is relevant.

## Real-world grounding

This discovery pattern mirrors the Agent Skills specification (as
documented at agentskills.io) that this whole catalog is built to, and
that you follow for every skill in it: only the frontmatter — name and
description — is loaded into context up front, cheaply, for every skill in
the catalog. The full SKILL.md body is loaded only once a skill has been
selected as relevant to the current task. This is exactly the two-stage
process this meta-skill describes: cheap matching against short
descriptions first, expensive loading of full instructions second. The
spec's progressive disclosure is not just a performance optimization — it
is the mechanism this skill teaches you to use correctly.

## Verification

- [ ] The task's phase and domain were identified before scanning the skill listing
- [ ] The matching skill was picked based on its description's trigger conditions, not its name alone
- [ ] When multiple skills matched, they were either sequenced sensibly or the conflict was surfaced to the user
- [ ] No skill was force-fit onto a task its description doesn't actually cover
- [ ] Assumptions were surfaced, confusion was named (not silently resolved), and verification happened before declaring done