May 17, 2026, 11:40 PM

2026-05-18 06:40:19 +00:00
commit 64944cf004
896 changed files with 310709 additions and 0 deletions
@@ -0,0 +1,201 @@
+---
+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)