From a73167488bd8fa00df46b2ec0e9115b80a9adbde Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 10 Mar 2026 02:06:04 +0000
Subject: [PATCH 1/3] Add skills directory with Ansible task to deploy to
 ~/.agents/skills

Creates a skills/ directory in the dotfiles repo and an Ansible task that
dynamically finds all skill files and symlinks them into ~/.agents/skills/.

https://claude.ai/code/session_01BhBiF3EqTSMfFCWNGpx6B8
---
 ansible/dotfiles.yml     |  6 ++++++
 ansible/tasks/skills.yml | 22 ++++++++++++++++++++++
 skills/.gitkeep          |  0
 3 files changed, 28 insertions(+)
 create mode 100644 ansible/tasks/skills.yml
 create mode 100644 skills/.gitkeep

diff --git a/ansible/dotfiles.yml b/ansible/dotfiles.yml
index 9f1ba78a..60024241 100644
--- a/ansible/dotfiles.yml
+++ b/ansible/dotfiles.yml
@@ -58,6 +58,12 @@
         - tmux
         - setup
 
+    - name: Include skills deployment tasks
+      include_tasks: tasks/skills.yml
+      tags:
+        - skills
+        - setup
+
     - name: Include dotfile linking tasks
       include_tasks: tasks/link_files.yml
       tags:
diff --git a/ansible/tasks/skills.yml b/ansible/tasks/skills.yml
new file mode 100644
index 00000000..1b3ee768
--- /dev/null
+++ b/ansible/tasks/skills.yml
@@ -0,0 +1,22 @@
+---
+- name: Create user agents skills directory
+  ansible.builtin.file:
+    path: "{{ ansible_user_dir }}/.agents/skills"
+    state: directory
+    mode: "0755"
+
+- name: Find skill files
+  ansible.builtin.find:
+    paths: "{{ dotfiles_dir }}/skills"
+    file_type: file
+    excludes:
+      - ".gitkeep"
+  register: skill_files
+
+- name: Link skill files to user agents directory
+  ansible.builtin.file:
+    src: "{{ item.path }}"
+    dest: "{{ ansible_user_dir }}/.agents/skills/{{ item.path | basename }}"
+    state: link
+    force: true
+  loop: "{{ skill_files.files }}"
diff --git a/skills/.gitkeep b/skills/.gitkeep
new file mode 100644
index 00000000..e69de29b

From eed90ae1e5b42c0918d3bb66e7eecb1d744d4c73 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 10 Mar 2026 02:07:49 +0000
Subject: [PATCH 2/3] Add explain skill for two-part file analysis

Produces an intuitive overview and a detailed technical breakdown
for a given file.

https://claude.ai/code/session_01BhBiF3EqTSMfFCWNGpx6B8
---
 skills/explain.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)
 create mode 100644 skills/explain.md

diff --git a/skills/explain.md b/skills/explain.md
new file mode 100644
index 00000000..0f556b0a
--- /dev/null
+++ b/skills/explain.md
@@ -0,0 +1,39 @@
+---
+name: explain
+description: "Produce a two-part explanation of a given file: an intuitive overview followed by a detailed technical breakdown."
+---
+
+# Explain
+
+Generate a two-part report on a given file.
+
+## When to Use
+
+- Understanding an unfamiliar file in a codebase
+- Onboarding onto a project and need to build mental models quickly
+- Reviewing code where you need both the "why" and the "how"
+
+## Instructions
+
+Given a file path, read the file and produce a report with exactly two sections:
+
+### Part 1 — Intuitive Explanation
+
+Explain what this file does as if describing it to a colleague who understands software but has no context on this project. Cover:
+
+- What problem it solves or what role it plays
+- How it fits into the broader system
+- The key idea or mental model needed to understand it
+
+Avoid jargon where possible. Use analogy if it genuinely clarifies.
+
+### Part 2 — Technical Explanation
+
+Walk through the implementation with precision. Cover:
+
+- Structure: key functions, classes, or sections and how they relate
+- Data flow: what comes in, what goes out, what gets transformed
+- Dependencies: what it relies on and what relies on it
+- Notable decisions: non-obvious implementation choices, trade-offs, or constraints
+
+Reference specific line numbers and identifiers. Do not restate Part 1 in technical language — add new information.

From 4b3e1468b52a9c5efe3948635bec43ccd8ad866e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 10 Mar 2026 02:08:48 +0000
Subject: [PATCH 3/3] Improve explain skill description for reliable triggering

Apply agentskills.io guidance: use imperative phrasing, cover
implicit user intents, and be explicit about when to activate.

https://claude.ai/code/session_01BhBiF3EqTSMfFCWNGpx6B8
---
 skills/explain.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/skills/explain.md b/skills/explain.md
index 0f556b0a..1cefbef1 100644
--- a/skills/explain.md
+++ b/skills/explain.md
@@ -1,6 +1,13 @@
 ---
 name: explain
-description: "Produce a two-part explanation of a given file: an intuitive overview followed by a detailed technical breakdown."
+description: >
+  Use this skill when the user wants to understand a file — whether they ask
+  to "explain," "walk me through," "what does this do," or simply point at a
+  file and ask about it. Produces a two-part report: an intuitive overview of
+  what the file does and why, followed by a precise technical breakdown of how
+  it works. Useful for onboarding, code review, or building context on
+  unfamiliar code, even if the user doesn't explicitly ask for both levels
+  of detail.
 ---
 
 # Explain