eve-skill-distillation

Eve Skill Distillation

Use this workflow to turn repeated patterns into reusable skills.

When to distill

• A workflow has repeated across two or more jobs.
• Knowledge would benefit other agents working on the same project.
• A failure mode keeps recurring and the fix should be encoded.

Workflow: Orchestrate, Don't Serialize

When distilling involves multiple skills (creating several, updating a batch, or a mix), use an orchestrator pattern rather than doing everything sequentially. This protects your context budget and parallelizes independent work.

Step 1: Capture patterns (orchestrator)

Identify all the patterns worth distilling from recent work. For each one:

• Name the repeated steps, commands, or failure modes.
• Decide: update an existing skill, or create a new one?
• Choose the target repo/pack first - is this likely to be
  • ./private-skills/ or similar for repo-specific development workflows that are not going to be imported into other projects (private)
  • ./private-eve-dev-skills/ when working in the eve-horizon repo and the skills relate to internal development of the platform itself (private)
  • ../eve-skillpacks/eve-se/ for Eve platform work (deploy, auth, manifests, pipelines)
  • ../eve-skillpacks/eve-work/ for general knowledge work (docs, orchestration, distillation)
  • ../eve-skillpacks/eve-design/ for architecture and design thinking

Step 2: Plan work items (orchestrator)

Create a tracked work item for each skill to create or update. Each work item description must be self-contained — a worker with no prior context should be able to execute it.

Include in each work item:

• The target file path (e.g., eve-se/eve-auth-and-secrets/SKILL.md)
• Whether this is a create or update
• The pattern being captured: what the skill should teach
• Any source material the worker should read (existing skills, reference docs, conversation history)
• The authoring rules (see "Skill Authoring Rules" below)

If there are housekeeping updates (README, ARCHITECTURE.md), add those as a final work item blocked until all skill work items complete.

Step 3: Dispatch workers (parallel)

Spawn one worker per skill work item. Launch them all at once.

Each worker prompt must be self-contained. The worker has no access to the orchestrator's conversation. Include:

• The target file path to create or edit
• The pattern to capture, described in enough detail to write from
• The authoring rules below
• Existing file content to preserve (for updates)

Step 4: Collect and finalize (orchestrator)

Wait for all workers to complete. Then:

• Update pack README and ARCHITECTURE.md listings if skills were added or removed.
• Verify each new/updated skill follows the authoring rules.

Single-skill shortcut

If there's only one skill to distill, skip the orchestrator pattern and do it directly. The overhead of dispatching a single worker isn't worth it.

Skill Authoring Rules

Every worker (or direct author) must follow these:

• Frontmatter: YAML with name and description only.
• Voice: Imperative form throughout. ("Run the command", not "You should run the command".)
• Conciseness: Keep SKILL.md under 5,000 words. Move long details into references/.
• Teach thinking, not just steps: Skills should help agents understand why, not just what. Include the reasoning behind workflows so agents can adapt when conditions change.
• Structure for skimming: Use headers, short paragraphs, and code blocks. Agents scan before they read.
• Agent-agnostic language: Describe what to do, not which tool to call. Say "edit the file" not "use the Edit tool". Say "spawn a background worker" not "launch a Task sub-agent".

Recursive distillation

• Repeat this loop after each significant job.
• Merge overlapping skills instead of duplicating them.
• Keep skills current as platform behavior evolves.
• When a skill's instructions no longer match reality, update or retire it.