record your first skill

SKILL.md

---
description: step-by-step guide for capturing your first reusable skill by demonstrating it once. pick a recurring workflow, demo it live, answer 3-8 interview questions, save org-wide. trigger when the user says "i do X every week" or "i wish claude remembered how to do this".
---

# record your first skill

the highest-leverage thing you can do in implexa. take one workflow you already do by hand every week, demonstrate it once, answer a few questions, and now anyone in your org can invoke it by name. demonstration plus interview beats writing a SKILL.md from scratch every time.

## intent

convert a tacit workflow into a structured, conditional, measurable skill via demonstration. the interview step is what makes it a skill instead of a transcript. you are not just recording a recipe, you are teaching the model when to fire it, what to do if a step fails, and what success looks like.

## inputs

- one workflow you do repeatedly (weekly is the sweet spot)
- the tools you normally use, already authenticated (mcp servers, slack, gmail, whatever)
- 10-15 minutes uninterrupted to demo plus answer questions

## procedure

### step 1, pick the right workflow

candidates that work well:
  - **weekly status email**: pull this week's commits, format, send to manager
  - **ticket triage**: bug report comes in, check duplicates, create issue, comment thread
  - **lookup-then-summarize**: account research, candidate sourcing, contract review
  - **scheduled report**: daily standup brief, weekly churn scan, monthly board update

candidates that do not work well:
  - one-off creative work ("write the launch tweet")
  - anything with truly novel decisions every time
  - workflows where the steps change weekly

if the workflow takes more than 15 minutes by hand, split it. shorter skills compose better than mega-skills.

### step 2, start recording

```
/implexa:record-skill
```

a recording indicator goes live. now do the work. narrate decisions out loud ("checking the email first because it has the customer id"). every tool call, every decision, every output gets captured in the demonstration log.

### step 3, end recording

when the workflow is done, call end_demonstration (or just say "done"). the live capture stops.

### step 4, optional free-text addendum

if there is anything you did not say during the demo (edge cases, "by the way if X happens do Y"), use record_demo_freetext to add it. these notes feed the interview.

### step 5, answer the interview

a haiku-class model asks 3-8 questions tuned to what it saw you do. typical questions:
  - what should this skill be named?
  - when should it fire (trigger phrases)?
  - what counts as a successful outcome?
  - what should it do if [tool] returns an error?
  - is there a step where the user should confirm before proceeding?

answer briefly. the model needs signal, not essays.

### step 6, finalize

the agent assembles a 6-component SKILL.md, scrubs anything that looks like a secret or pii, and saves it scoped to your org. you get a confirmation with the slug. anyone in your org can now invoke it.

## decision points

- **the interview asks a question you do not have an answer for**: say "skip" or "leave it open". the agent picks a sensible default. you can refine via /implexa:update-skill later.
- **the demonstration captured a tool call you do not want in the final skill** (api key, personal account): mention it in the free-text addendum or strip it via update_org_skill after save.
- **the workflow has a branch you did not demo** ("if X, do Y; if Z, do W"): demo the most common path, then describe the other branches in free-text. the agent encodes them as decision points.

## output contract

a saved org skill with: a slug, a name, a description, the 6-component body, recorded trigger phrases, the demonstration trace, the interview answers. visible to everyone in your org immediately. shareable cross-org via /implexa:share-this.

## outcome signal

the skill gets used. if the same workflow gets invoked at least once in the 30 days after recording (by you or anyone on your team), it stuck. if it never gets used, it was a workflow that was too one-off or the trigger phrases did not match how people actually search.

## notes

- demonstration beats authoring. a SKILL.md written from scratch always misses the implicit "i would have checked X first" steps. recording catches them automatically.
- the interview is what differentiates implexa from a generic macro recorder. the model is not just replaying clicks, it is asking when to fire and how to recover from failure.
- if you mess up mid-demo, just keep going and mention the mistake in free-text. the interview will route around it.