| name | system/author-skill |
| description | This skill should be used when authoring a new skill in the tmuxllm skill library. Triggers include explicit requests like "create a skill for X" or "turn this workflow into a skill," and implicit cases where the root agent observes a workflow being done manually and recognizes it as a candidate for capture. Operates in two modes — from a description of intended behavior, or from a JSONL trace of a session that demonstrates the procedure. |
| capabilities | ["shell"] |
system/author-skill
Author a new skill in the tmuxllm skill library. Take either a description of the desired procedure or a session trace demonstrating it. Produce a working SKILL.md (plus optional bundled scripts) that runs successfully on at least one real example before being committed to the library.
This is the bootstrap skill — the skill that authors other skills. Apply it carefully, with human review at the commit step. v0 is intentionally manual: human-in-the-loop at every refinement boundary, no automation of the accept/reject decision.
When to apply
Apply when one of these holds:
- The user explicitly requests a new skill ("make a skill for our weekly ops report")
- The user describes a recurring workflow they want captured ("I keep doing X manually, can you turn that into something reusable?")
- An execution trace from a recent session contains a procedure worth capturing, and the user has indicated interest in skill extraction
Do not apply silently — never author a skill without explicit user awareness that authoring is happening. Skill authoring is a privileged operation that mutates the library; treat it like committing code, not like answering a question.
Inputs
Required:
name: the skill's library path (e.g. email/send-via-mutt, editorial/ars-style-article). Must be unique in the library; lowercase, hyphens, slash-separated.- One of:
description: prose specification of what the skill should dotrace: path to a JSONL session log demonstrating the procedure
Optional:
template: path to an existing skill to use as starting structuretarget: where in the library to write (defaults to $XDG_DATA_HOME/tmuxllm/skills/<name>/)
Procedure
Step 1 — Verify the name doesn't collide
Check the library for an existing skill at the target path:
test -d "$XDG_DATA_HOME/tmuxllm/skills/<name>" && echo "EXISTS"
If it exists, do not proceed. Either pick a new name, or apply system/refine-skill instead (a different skill, not yet authored — for v0, just stop and ask the user how to proceed).
Step 2 — Draft the skill
For description-driven authoring: read the description, identify the inputs (what varies across invocations), the outputs (files, side-effects, return values), and the procedure (the steps in order). Produce a SKILL.md following the structure in the template (below).
For trace-driven authoring: read the JSONL trace. Identify:
- The shell commands that ran successfully (skip dead ends, retries that didn't matter, exploratory calls)
- The variables across runs — values that changed because they were inputs, not because the procedure differed
- The outputs that were the actual deliverables vs. intermediate scratch
- Any decision points where judgment was applied (where the LLM made a choice based on observed state)
Produce a SKILL.md that captures the pattern, not the literal trace. This is the hard step. Expect to get it wrong on the first pass.
Step 3 — Write the candidate to a staging location
Write to $XDG_STATE_HOME/tmuxllm/skill-staging/<name>/ first, not directly to the library. The library is treated as a committed artifact; staging is where drafts live.
mkdir -p "$XDG_STATE_HOME/tmuxllm/skill-staging/<name>"
Step 4 — Test the skill on one real example
This is the load-bearing step. A skill that hasn't successfully run is not a skill — it's a draft.
Identify a concrete example the skill should handle. For description-driven authoring, ask the user for one. For trace-driven authoring, use the original trace's inputs.
Run the staged skill against this example. Capture:
- Exit code (or LLM completion status if the skill includes judgment steps)
- Output files / side effects
- Discrepancies between expected and actual
If it fails: go to Step 5. If it succeeds: go to Step 6.
Step 5 — Refine
Show the user:
- The current SKILL.md
- The failure mode (what was expected, what happened)
- A proposed revision
Ask: refine and retry, or abandon? If refine, apply the revision in staging and return to Step 4. If abandon, leave the staging artifact in place for inspection and stop.
Do not loop more than 3 times automatically. After 3 refinement cycles without success, surface to the user that the skill is harder than expected and ask whether to continue, simplify the scope, or abandon.
Step 6 — Commit to the library
Only after at least one successful run on a real example:
mv "$XDG_STATE_HOME/tmuxllm/skill-staging/<name>" \
"$XDG_DATA_HOME/tmuxllm/skills/<name>"
Append an entry to the skill library log at $XDG_STATE_HOME/tmuxllm/skill-history.jsonl:
{"event": "skill_authored", "name": "<name>", "ts": "...", "source": "description|trace", "first_run_succeeded": true}
If the user has the library under git (recommended), offer to commit:
cd "$XDG_DATA_HOME/tmuxllm/skills" && git add "<name>" && git commit -m "Author skill: <name>"
Ask before committing — never commit silently.
SKILL.md structure to produce
Keep the produced SKILL.md brutally simple in v0. The structure to target:
---
name: <library/path>
description: <when to apply, third-person, ~50 words>
inputs:
- <named input>
invariants:
- <a property the skill claims to maintain>
verify:
- <how to check the invariant after running>
---
# <Skill Title>
<One-paragraph operational description.>
## Procedure
1. <step>
2. <step>
3. <step>
## Failure modes
- <known failure>: <what to >
Do not add decision blocks, complex schemas, or judgment-composition machinery in v0. Those are roadmap. The skill format above is sufficient for the first 10 skills authored. Earn the additions when actual skills hit limits the simple format can't express.
Invariants this skill maintains
- A skill is only added to the library if it has run successfully at least once on a real example
- The library is never modified silently — every commit is logged in
skill-history.jsonl and (optionally) version-controlled in git
- Staged drafts that fail are left in
skill-staging/ for inspection, not deleted
- The skill name is unique in the library namespace
Verification
After authoring, verify by:
- The new skill appears in
find $XDG_DATA_HOME/tmuxllm/skills -name SKILL.md
- The skill's description is non-empty and the frontmatter parses as YAML
- A subsequent invocation of the skill (on the same example) succeeds — the first commit must be reproducible
Failure modes
Trace abstraction is wrong. The most common failure: the candidate skill captured incidental details from the trace as if they were essential. Symptom: skill works on the original example but breaks on a slightly different input. Repair: re-author with the user pointing out which parts were incidental.
Description is underspecified. Description-driven authoring produces a skill that's too vague. Symptom: the LLM running the skill makes too many judgment calls, results vary widely. Repair: have the user provide a concrete example, switch to trace-driven mode.
The procedure isn't actually deterministic. The skill assumes a fixed sequence but the real procedure has branches the trace didn't capture. Symptom: skill fails on inputs that hit untraced branches. Repair: explicitly add the branch as a decision point in the skill, or split into two skills.
Verification is too weak. The skill "succeeded" but actually didn't do what was wanted. Symptom: invariant check passed but human review reveals the output is wrong. Repair: strengthen invariants. This is the silent-failure case — assume it will happen and treat the first 5 invocations of any new skill as supervised.
The skill belongs to a tool that isn't installed. Symptom: skill fails because mutt, gcal, etc. aren't on the system. Repair: out of scope for this skill — the root agent should apply system/install-cli-tool separately before authoring tool-dependent skills, or the skill itself should declare a dependency the runtime checks before invoking.
What this skill does NOT do (yet)
- Automatic skill extraction without human review (roadmap)
- Decision-block authoring with verifiers (roadmap)
- Multi-skill workflow synthesis (roadmap)
- Skill repair after API drift (separate skill:
system/repair-skill)
- Skill deprecation or removal (separate skill:
system/deprecate-skill)
These will be authored as separate skills if and when the need is clear from real usage. Do not extend this skill to cover them.
References
references/skill-format.md — full SKILL.md format specification with examplesreferences/trace-reading.md — heuristics for extracting procedures from JSONL tracesreferences/templates/ — starter templates for common skill archetypes (shell-tool, rest-api, code-generation)
