---
name: my-custom-skill
version: 1.0.0
owner: team-name / person
description: >
  Performs a well-defined task related to [domain],
  producing a deterministic and auditable output.
trigger:
  - manual
  - cron
  - condition
inputs:
  required:
    - name: topic
      type: string
      description: Main subject provided by the user
  optional:
    - name: verbosity
      type: enum(low|medium|high)
      default: medium
outputs:
  - type: markdown
  - location: memory / file / external-system
---

# My Custom Skill

## Purpose

This skill is responsible for **one thing only**:
> _[Clearly state the single responsibility]_

It should be used when:
- ✅ The user intent matches **[explicit criteria]**
- ✅ All prerequisites are satisfied
- ❌ It must NOT be used when **[explicit exclusion cases]**

---

## When to Use (Decision Logic)

Trigger this skill **only if ALL conditions are met**:

1. User intent is related to **[topic/domain]**
2. Required inputs are present and valid
3. No higher-priority skill is better suited

Fallback:
- If any condition fails → return control to the orchestrator

---

## Prerequisites

### Required
- Files:
  - `/config/skill-config.yaml`
- Secrets:
  - `API_KEY_X`
- Tools:
  - CLI: `tool-x >= 1.2`
  - Access to: `[system/service]`

### Validation Checklist
- [ ] Config file exists
- [ ] Secrets resolved
- [ ] External dependency reachable

Abort execution if any check fails.

---

## Execution Flow

### Step 0: Pre-flight Validation (MANDATORY)

**Goal:** Fail fast, fail safe.

- Validate inputs schema
- Sanitize user-provided text
- Check permissions / access scope
- Log execution start with correlation ID

Output:
- Validation report (internal)

---

### Step 1: Context Gathering

**Goal:** Build minimal, relevant context.

Actions:
- Load required files
- Query only necessary data
- Ignore unrelated information

Rules:
- No assumptions
- No hallucinations
- Prefer explicit data over inference

Artifacts:
- `context.json`

---

### Step 2: Core Logic Execution

**Goal:** Perform the primary task.

Actions:
- Execute deterministic logic
- If using LLM:
  - Provide strict system instructions
  - Use constrained prompts
  - Avoid open-ended creativity unless explicitly required

Rules:
- One responsibility
- No side effects outside defined scope

Artifacts:
- `result.raw`

---

### Step 3: Post-processing & Output

**Goal:** Produce clean, user-ready output.

Actions:
- Normalize formatting
- Remove internal metadata
- Apply verbosity level
- Validate final output

Output:
- User-facing result
- Storage:
  - Save to `[location]`
  - Notify `[who/what]` if applicable

---

## Error Handling

### Expected Errors
- Missing input → return actionable message
- External dependency unavailable → retry or abort gracefully

### Unexpected Errors
- Log full context
- Return safe, non-technical message to user
- Escalate via monitoring

---

## Observability & Auditing

Log at minimum:
- Skill name & version
- Trigger type
- Inputs (redacted)
- Execution time
- Outcome (success/failure)

Metrics:
- Success rate
- Avg execution time
- Most common failure reason

---

## Common Mistakes

1. Skill doing **too many things**
2. Triggering on vague user intent
3. Missing validation step
4. Overusing LLM where deterministic logic is enough
5. No clear failure path

---

## Example Use Case

**User:**  
> "Generate a summary of database performance issues from last week"

**Skill Output:**  
- Structured markdown summary
- Saved to `/reports/db-summary.md`
- Notification sent to Slack `#db-alerts`

---

## Notes for Future Improvements

- Add caching for repeated inputs
- Introduce dry-run mode
- Expand structured outputs (JSON schema)