Agent Skills in Claude Agent SDK Applications

## Overview

Agent Skills extend Claude with specialized capabilities packaged as `SKILL.md`
files that Claude invokes autonomously when relevant. In the Agent SDK, skills are
filesystem artifacts discovered through setting sources; there is no programmatic
API for registering them.

## How discovery works

Skills load from filesystem locations governed by `settingSources` (TypeScript) /
`setting_sources` (Python). With default `query()` options, the SDK loads `user`
and `project` sources, so skills in `~/.claude/skills/`, `<cwd>/.claude/skills/`,
and `.claude/skills/` in parent directories up to the repo root are available. If
you set `settingSources` explicitly, include `'user'` or `'project'` to keep
discovery.

## Enable and filter skills

Use the `skills` option to control which skills are available. Omit it to enable
discovered skills (matching CLI behavior), pass `"all"` for every discovered
skill, a list of names to enable only those, or `[]` to disable all.

```typescript
for await (const message of query({
  prompt: "Help me process this PDF document",
  options: {
    cwd: "/path/to/project",
    settingSources: ["user", "project"],
    skills: "all",
    allowedTools: ["Read", "Write", "Bash"],
  },
})) { /* ... */ }
```

Enable specific skills by name (matching the `name` in SKILL.md or the directory
name; use `plugin:skill` for plugin skills):

```typescript
const options = { skills: ["pdf", "docx"] };
```

When you set `skills`, the SDK adds the Skill tool to `allowedTools` automatically.
If you also pass an explicit `tools` list, include `"Skill"`.

## Tool access

The `allowed-tools` frontmatter in SKILL.md is honored only by the CLI, not the
SDK. Control tool access through the main `allowedTools` option; without a
`canUseTool` callback, anything not listed is denied. Pair with
`permissionMode: "dontAsk"` to deny anything outside the allow list.

## Troubleshooting

- **Skills not found**: confirm `settingSources` includes `user`/`project` (an
  empty array disables discovery), and that `cwd` points at or below the directory
  containing `.claude/skills/`.
- **Skill not used**: confirm its name is in the `skills` list (an empty list
  disables all) and that its description is specific.
- Verify on disk with `ls .claude/skills/*/SKILL.md`.

## Source

- Agent Skills in the SDK: https://code.claude.com/docs/en/agent-sdk/skills