Documentation Patterns

Skill Documentation Patterns

How to write skills that Claude can find and use effectively.

Overview

| Item | Details | | ------ | --------- | | Date | 2025-12-29 | | Objective | Document patterns for high-quality skill documentation | | Outcome | Improved skill discoverability and reuse | | Source | Sionic AI HuggingFace blog |

When to Use

• Creating a new skill after /learn
• Improving an existing skill's discoverability
• Writing trigger conditions for /advise matching
• Documenting failed attempts (most valuable content)
• Making configs and parameters copy-paste ready

Verified Workflow

1. Write Specific Trigger Conditions

The description field determines if /advise finds your skill. Be specific:

Bad (vague):

"description": "Pruning experiments"

Good (specific):

"description": "GRPO training with external vLLM server. Use when: (1) Running vLLM on separate GPUs, (2) Encountering vllm_skip_weight_sync errors, (3) OpenAI API parsing issues. Verified on gemma-3-12b-it."

Pattern: {what} + Use when: {numbered triggers} + Verified on: {environment}

2. Document Failed Attempts (Most Valuable)

Failed attempts save weeks of trial-and-error. Use this table format:

| Attempt | Why it Failed | Lesson Learned |
|---------|---------------|----------------|
| Running vLLM without --served-model-name | 404 Model 'default' not found | Must add --served-model-name default |
| Execution without vllm_skip_weight_sync | 404 /update_flattened_params/ error | Mandatory flag when using vllm serve |

3. Use Concrete Numbers, Not Vague Advice

Bad:

Use a small learning rate

Good:

RoPE theta=100 works well for short sequences. d_proj=64+ prevents information loss. ksim=4 optimal with 16-bucket token distribution.

3.5. Include Environment Details in Overview

Add environment context for reproducibility:

## Overview

| Item | Details |
|------|---------|
| Date | YYYY-MM-DD |
| Objective | [What was the goal] |
| Outcome | [What happened] |
| Hardware | NVIDIA A100-SXM4-80GB |
| Software | PyTorch 2.0.1, CUDA 11.8 |
| Dataset | 100K train / 10K eval |
| Runtime | 24 GPU hours |
| Source | [Blog/paper/issue link] |

Why: Reproducibility requires environment context. "Works on A100-80GB" might fail on V100-16GB due to memory constraints.

4. Make Configs Copy-Paste Ready

# GRPO Training Config (Ready to copy-paste)
rlhf_type: grpo
use_vllm: true
vllm_mode: server
vllm_skip_weight_sync: true  # Mandatory when using standard vllm serve
tensor_parallel_size: 2
gpu_memory_utilization: 0.9
dtype: bfloat16

5. Include Error-to-Solution Mappings

Use this structured format for documenting errors:

## Error: [Error Title/Message]

**Symptom**: [What the user sees/experiences]
**Cause**: [Root cause explanation]
**Solution**: [Step-by-step fix]
**Prevention**: [How to avoid in future]
**Related Errors**: [Links to similar issues]

Example:

## Error: RuntimeError - RoPE freqs dimension mismatch

**Symptom**:

RuntimeError: The size of tensor a (32) must match the size of tensor b (16) at non-singleton dimension 3

**Cause**: Standard RoPE implementations output freqs with shape `[seq_len, head_dim/2]`, but attention layer expects `[seq_len, head_dim]` for broadcasting.

**Solution**:
```python
# In apply_rotary_pos_emb function
freqs = torch.cat((freqs, freqs), dim=-1)  # Duplicate to match head dimension
freqs = freqs.unsqueeze(0).unsqueeze(0)    # Add batch and head dims [1, 1, seq, dim]

Prevention:

• Always verify RoPE freqs shape before attention computation
• Add assertion: assert freqs.shape[-1] == head_dim

Related Errors:

• Attention mask broadcasting errors
• Position embedding shape mismatches

Failed Attempts

| Attempt | Why Failed | Lesson | |---------|-----------|--------| | Vague descriptions like "ML training" | Claude can't match to user queries | Include numbered trigger conditions | | Optional failures section | Teams skip it, lose most valuable info | Make failures REQUIRED in validation | | Pseudo-code in documentation | Users can't copy-paste directly | Always use real, tested commands | | Missing environment details | Works on my machine problems | Include versions, hardware specs | | Long prose explanations | Hard to scan quickly | Use tables and bullet points |

Results & Parameters

# Skill quality checklist
required_sections:
  - "When to Use"           # Trigger conditions
  - "Verified Workflow"     # What worked
  - "Failed Attempts"       # What didn't (most valuable)
  - "Results & Parameters"  # Copy-paste configs

description_pattern: "{what} + Use when: {numbered triggers} + Verified on: {env}"

# Anti-patterns to avoid
avoid:
  - Vague trigger conditions
  - Optional failures section
  - Pseudo-code instead of real commands
  - Missing version/environment info
  - Prose-heavy explanations

# Metrics that matter
skill_quality_indicators:
  - Times surfaced by /advise
  - Times referenced in subsequent experiments
  - Copy-paste success rate

Cultural Notes

From the Sionic AI blog:

1. Frictionless contribution: /learn takes 30 seconds; Claude writes it
2. Reward specificity: Skills with precise descriptions get surfaced, reused, cited
3. Celebrate failures: "I tried X and it broke because Y" is the most valuable content
4. Timing matters: Capture knowledge while fresh (end-of-session, not two weeks later)

References

• Source blog: https://huggingface.co/blog/sionic-ai/claude-code-skills-training
• Template gist: https://gist.github.com/sigridjineth/2f0ef5d1d56e884a84f1580de21db597

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: HomericIntelligence
• Source: HomericIntelligence/ProjectMnemosyne
• License: BSD-3-Clause

Install and usage instructions live in the source repository linked above.