chore: import upstream snapshot with attribution

2026-07-13 12:24:16 +08:00
commit 4b92209caa
317 changed files with 67848 additions and 0 deletions
@@ -0,0 +1,78 @@
+# Skill Document
+
+A **skill document** is a Markdown file that serves as the "prompt weights" of your agent. SkillOpt trains this document through iterative optimization.
+
+## What is a Skill Document?
+
+A skill document is a structured set of instructions that tells a language model **how** to approach a specific type of task. It's analogous to learned weights in a neural network — encoding task-specific knowledge in natural language rather than floating-point parameters.
+
+## Structure
+
+A typical skill document contains:
+
+```markdown
+# Task Strategy
+
+## General Approach
+- Break complex problems into sub-steps
+- Always verify intermediate results
+
+## Common Patterns
+- When you see X, try approach Y
+- Avoid Z because it leads to errors
+
+## Edge Cases
+- If the input contains A, handle it specially by...
+- Watch out for B — it requires C
+
+## Output Format
+- Always include reasoning before the answer
+- Format numbers with proper units
+```
+
+## How It Evolves
+
+During training, the skill document is modified by **edit patches**:
+
+1. **Additions**: New rules or strategies discovered from failed trajectories
+2. **Modifications**: Refining existing rules that are partially correct
+3. **Deletions**: Removing rules that consistently lead to errors
+
+Each edit is validated through the **gate** mechanism before being permanently accepted.
+
+## Initial Skill
+
+You can start training with:
+
+- **Empty skill**: The system learns everything from scratch
+- **Seed skill**: Provide initial instructions to bootstrap training
+- **Pre-trained skill**: Transfer a skill from a related benchmark
+
+Configure the initial skill in your YAML:
+
+```yaml
+train:
+  init_skill: "path/to/initial_skill.md"  # or omit for empty
+```
+
+## Skill Quality Metrics
+
+Track your skill's evolution through:
+
+- **Validation score**: Primary metric on the selection split
+- **Test score**: Final metric on held-out test data
+- **Skill length**: Total tokens in the document
+- **Edit acceptance rate**: Fraction of proposed edits that pass gating
+
+## Best Practices
+
+!!! tip "Tips for better skills"
+    1. **Start with a seed skill** (`env.skill_init`) if you have domain knowledge — it converges faster
+    2. **Use cosine LR schedule** — aggressive early exploration + careful late refinement
+    3. **Enable slow update** (`use_slow_update: true`) to prevent forgetting across epochs
+    4. **Enable meta skill** (`use_meta_skill: true`) so the optimizer accumulates strategy memory
+
+## Next Steps
+
+- [Deep Learning Analogy](dl-analogy.md)
+- [Configuration Reference](../reference/config.md)