# Skills — Reusable AI Agent Knowledge

This directory contains **tool-agnostic skill files** that encode domain knowledge, API patterns, and operational runbooks for AI coding agents. Skills are version-controlled and shared across the team.

## Directory Structure

```
skills/
├── README.md              ← this file
├── cloudcost/
│   ├── SKILL.md           ← Cloud Cost Query Gateway API + analysis templates
│   └── OPERATOR.md        ← Token/grant management + troubleshooting runbook
└── superset/
    └── SKILL.md           ← Superset REST API operations
```

Each skill is a directory containing a `SKILL.md` (markdown with optional YAML frontmatter). Some skills include additional files like `OPERATOR.md` for ops runbooks.

## How to Use with Different AI CLI Tools

### Claude Code

Claude Code natively discovers skills from `.claude/skills/`. Use **symlinks** to point there:

```bash
# one-time setup (already done for superset)
mkdir -p .claude/skills/superset
ln -sf ../../../skills/superset/SKILL.md .claude/skills/superset/SKILL.md
```

After linking, the skill is available as a slash command (`/superset`) and Claude will auto-invoke it when relevant.

> **Note**: `.claude/` is gitignored. The symlink setup is a local operation each developer performs once.

### OpenAI Codex

Reference the skill file in your prompt or agent configuration:

```yaml
# agents/openai.yaml or similar config
instructions:
  - file: skills/superset/SKILL.md
```

Or include it in your system prompt directly:

```bash
codex --instructions "$(cat skills/superset/SKILL.md)"
```

### Cursor / Windsurf

Add the skill as a project rule or context file:

- **Cursor**: Add to `.cursor/rules/` or reference in `.cursorrules`
- **Windsurf**: Add to `.windsurfrules` or project context

```bash
# Cursor example
mkdir -p .cursor/rules
ln -sf ../../skills/superset/SKILL.md .cursor/rules/superset.md
```

### Generic (any LLM agent)

Simply include the skill content in your system prompt or context:

```bash
cat skills/superset/SKILL.md
```

## Writing New Skills

1. Create a directory: `skills/<skill-name>/`
2. Write `SKILL.md` with:
   - YAML frontmatter (`name`, `description`) — optional but recommended
   - Markdown body with operational knowledge, code templates, and gotchas
3. Set up symlinks for your preferred CLI tool (see above)
4. Commit to git

### Guidelines

- Keep `SKILL.md` under 500 lines — split into supporting files if needed
- Focus on **operational knowledge** that prevents repeated mistakes
- Include working code templates (copy-paste ready)
- Document gotchas and failure modes prominently
- Keep skills tool-agnostic in content; tool-specific integration is handled by symlinks/config