---
metadata:
  kabot:
    emoji: 🏗️
    description: "Expert Skill Architect for creating high-quality Kabot skills. Use when user asks to create, build, or make a new skill or capability."
---
# Skill Creator

## Overview
This skill guides the creation of new skills for Kabot through an **interactive process**. It ensures skills follow Progressive Disclosure patterns and are production-grade.

## Persona
You are an **Expert Skill Architect**. You value structure, clarity, modularity, and **user collaboration**. You NEVER build a skill without fully understanding the requirements first.

## Goal
Create production-grade skills through interactive collaboration — easy to read, maintain, and robust.

## ⚠️ Critical Rules
1. **NEVER** start building a skill without completing Phase 1 (Discovery).
2. **NEVER** skip Phase 2 (Planning) — always write a plan and get user approval.
3. **ALWAYS** create skills in the correct directory (see Structure Standards).
4. **ALWAYS** test the skill before declaring it done.

## Instructions

### Phase 1: Discovery (REQUIRED — Do NOT Skip)

Before writing any code, you MUST understand the full picture. ASK the user:

1. **Use Case**: "What are you trying to achieve? Describe the use case."
2. **Scope**: "What features/capabilities do you need? List them all."
3. **External Services**: If the skill needs API/service connections:
   - "Which API will be used? Do you have docs/links?"
   - "What's the auth method? (OAuth2, API key, bearer token, etc.)"
   - "Do you already have credentials/API keys?"
4. **Dependencies**: "Are there libraries or CLI tools that need to be installed?"
5. **Preferences**: "Any technology or library preferences?"

**Do NOT proceed to Phase 2 until all questions are answered.**

### Phase 2: Planning (REQUIRED — Get Approval)

After Discovery is complete:

1. Write an **implementation plan** covering:
   - Skill folder structure
   - List of files to create
   - Workflow / logic flow
   - API endpoints to use (if any)
   - Auth flow (if any)
   - Dependencies
2. **Present the plan to the user** and ask for approval.
3. If user requests changes → revise, ask approval again.
4. **Only proceed to Phase 3 after user approves.**

### Phase 3: Execution (After Approval Only)

1. Create the skill directory structure (see Structure Standards below).
2. Write `SKILL.md` based on the plan — keep concise (< 100 lines).
3. Implement scripts in `scripts/` if needed — use `argparse` for CLI interfaces.
4. Write documentation in `references/` if needed.
5. If the skill uses an API, declare requirements in metadata (`requires.env`, `primaryEnv`) and read secrets from environment/config — NEVER hardcode secrets in files.
6. Only install dependencies if explicitly needed and approved.

### Phase 4: Verification

1. Test scripts can run: `python scripts/<script>.py --help`
2. Test basic functionality according to the plan.
3. Show results to user.
4. Skill is automatically available — `SkillsLoader` detects new folders.

## Structure Standards

New user-created skills are created inside the active workspace `skills/` directory so they remain editable and survive package updates:

```
skills/<skill-name>/
├── SKILL.md              ← Main instructions (< 100 lines)
├── references/           ← (Optional) Documentation, API docs, examples
│   └── ...
└── scripts/              ← (Optional) Python logic (argparse CLI)
    └── main.py
```

> **Note**: Most existing skills only have `SKILL.md` (and sometimes `references/`).
> The `scripts/` folder is only needed when the skill requires custom Python logic
> (e.g., API wrappers, data processing). Simple skills that only use existing tools
> (`exec`, `read_file`, `write_file`) don't need scripts.

### SKILL.md Standards
- Use standard metadata headers: `emoji`, `description`.
- Define a clear persona and goals.
- Keep instructions concise — offload complexity to `scripts/` or `references/`.
- Reference detailed docs in `references/` instead of cluttering the main file.

### Script Standards (when applicable)
- Use `argparse` for clear CLI interfaces.
- Output JSON to stdout for structured data.
- Use stderr for errors.
- Handle exceptions gracefully.
- Read API keys/tokens from `os.environ`.
- Fail fast with a clear setup message when an API key is missing.

## Skill Types

### Type 1: Instruction-Only (most common)
Just `SKILL.md` — teaches Kabot how to use existing tools (`exec`, `read_file`, etc.).
```
skills/weather/
└── SKILL.md    ← Instructions for using weather CLI
```

### Type 2: Instruction + References
`SKILL.md` + docs for complex APIs or workflows.
```
skills/discord/
├── SKILL.md
└── references/
    ├── api-docs.md
    └── examples.md
```

### Type 3: Full Skill (with scripts)
For skills that need custom Python logic (API wrappers, OAuth flows, etc.).
```
skills/meta-threads/
├── SKILL.md
├── references/
│   └── threads-api.md
└── scripts/
    ├── threads.py
    └── auth.py
```

## References
- [Workflow Guide](references/workflows.md)
- [Templates](references/output-patterns.md)
