Paweł Domański
202 lines
3.6 KiB
Markdown
202 lines
3.6 KiB
Markdown
---
|
|
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)
|