1 files changed, 35 insertions, 0 deletions
diff --git a/skills/skills-system-guide.md b/skills/skills-system-guide.md
new file mode 100644
index 0000000..26d3dcf
--- /dev/null
+++ b/skills/skills-system-guide.md
@@ -0,0 +1,35 @@
+---
+name: skills-system-guide
+description: How to use the skills system: load, create, patch, list, and audit skills for persistent procedural memory
+tags: [skills, system, meta]
+category: system
+---
+## Steps
+1. **Always load skills at task start:**
+   - At the START of every task, call load_skills(query) to check for stored procedures
+   - Example: load_skills("search the web") returns matching skill content
+   - Example: load_skills("edit module") returns the module editing workflow
+
+2. **Create skills after complex tasks:**
+   - After any task with 3+ tool calls, call create_skill to save the approach
+   - Required fields: name (kebab-case), description, content (markdown with YAML frontmatter)
+   - Optional: tags (comma-separated), category (e.g. research, system, dev)
+   - Skills persist in /skills/ as .md files with /skills/index.json for fast lookup
+
+3. **Patch skills when they're outdated:**
+   - If a stored procedure has wrong steps, call patch_skill(name, newContent)
+   - This replaces the entire skill content and updates the index
+   - Do NOT create a duplicate — always patch the existing skill
+
+4. **Auto-created error skills:**
+   - If the same tool fails 3+ times, a workaround skill is created automatically
+   - Named tool-<name>-workaround (e.g. tool-write_file-workaround)
+
+5. **Audit and maintenance:**
+   - list_skills(category?) — browse available skills, optionally filter
+   - Skills are audited every 20 messages for staleness (empty content, >30 days old)
+
+6. **YAML frontmatter format:**
+   - Each skill file must start with: ---\nname: <name>\ndescription: <text>\ntags: [...]\ncategory: <cat>\n---\n
+   - Steps follow under ## Steps heading
+   - Use numbered lists for sequential steps
+\ No newline at end of file