docs(authoring-skills): adopt Anthropic patterns

Detailed changes

skills/authoring-skills/SKILL.md 🔗

@@ -8,7 +8,7 @@ metadata:
   version: "1.0"
 ---
 
-Skills extend agent capabilities through a simple folder structure. Every skill requires a `SKILL.md` file with YAML frontmatter and markdown instructions.
+Skills extend agent capabilities through a simple folder structure. Think of them as onboarding guides—they transform a general-purpose agent into a specialized one equipped with procedural knowledge no model can fully possess.
 
 ```
 skill-name/
@@ -18,9 +18,11 @@ skill-name/
 └── assets/           # Optional: templates, resources
 ```
 
-1. Conciseness: The context window is shared. Challenge every token: "Does the agent really need this?"
-2. Progressive disclosure: Load metadata at startup, instructions when activated, resources only when needed
-3. Appropriate freedom: Match specificity to task fragility (see [patterns.md](references/patterns.md))
+## Core principles
+
+1. **Conciseness**: The context window is a public good. Default assumption: the agent is already smart. Only add context it doesn't already have. Does this paragraph justify its token cost? Prefer concise examples over verbose explanations.
+2. **Progressive disclosure**: Load metadata at startup, instructions when activated, resources only when needed
+3. **Appropriate freedom**: Match specificity to task fragility (see [patterns.md](references/patterns.md))
 
 ## Required frontmatter
 
@@ -47,6 +49,8 @@ description: Extracts text and tables from PDF files. Use when working with PDFs
 - Include trigger keywords for discovery
 - No markdown formatting
 
+The description is the primary trigger mechanism. The body only loads *after* activation, so "When to Use" sections in the body don't help agents discover the skill.
+
 **Good**: `Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.`
 
 **Bad**: `Helps with PDFs.`
@@ -66,8 +70,9 @@ allowed-tools: Bash(git:*) Read
 
 - Keep under 500 lines (move details to reference files)
 - No format restrictions—write what helps agents perform the task
-- Assume the agent is intelligent; only add context it doesn't already have
+- Information should live in either SKILL.md or references, not both
 - Use consistent terminology throughout
+- For large reference files (>10k words), include grep search patterns in SKILL.md
 
 ### Recommended sections
 
@@ -76,6 +81,16 @@ allowed-tools: Bash(git:*) Read
 - Common edge cases
 - Links to reference files for advanced details
 
+### What NOT to include
+
+Skills should only contain what an agent needs to do the job. Do not create:
+
+- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md
+- Setup/testing procedures, user-facing documentation
+- Auxiliary context about the skill's creation process
+
+These add clutter without helping agents perform tasks.
+
 ## Progressive disclosure structure
 
 ```markdown
@@ -91,6 +106,7 @@ Keep file references **one level deep** from SKILL.md. Avoid nested reference ch
 
 ## Detailed guidance
 
+- **Creation process**: See [process.md](references/process.md)
 - **Technical specification**: See [specification.md](references/specification.md)
 - **Common patterns**: See [patterns.md](references/patterns.md)
 - **Pre-publish checklist**: See [checklist.md](references/checklist.md)

skills/authoring-skills/references/checklist.md 🔗

@@ -17,6 +17,7 @@
 
 ## Scripts (if applicable)
 
+- [ ] Scripts are tested by actually running them (not just written)
 - [ ] Scripts solve problems rather than punt to agent
 - [ ] Error handling is explicit and helpful
 - [ ] No magic constants (all values justified/documented)

skills/authoring-skills/references/patterns.md 🔗

@@ -12,7 +12,7 @@
 
 ## Degrees of freedom
 
-Match specificity to task fragility.
+Match specificity to task fragility. Think of an agent exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
 
 ### High freedom (text instructions)

skills/authoring-skills/references/process.md 🔗

@@ -0,0 +1,43 @@
+# Creation Process
+
+## Understanding the skill
+
+Before creating a skill, gather concrete usage examples. Ask:
+
+- What functionality should the skill support?
+- Can you give examples of how this would be used?
+- What would a user say that should trigger this skill?
+
+Skip this when usage patterns are already clear. Conclude when you have a clear sense of the functionality the skill should support.
+
+## Planning reusable contents
+
+Analyze each example by:
+
+1. Considering how to execute on the example from scratch
+2. Identifying what scripts, references, and assets would help when doing this repeatedly
+
+### Example analyses
+
+**pdf-editor** for "Help me rotate this PDF":
+
+1. Rotating a PDF requires re-writing the same code each time
+2. → A `scripts/rotate_pdf.py` script would be helpful
+
+**frontend-webapp-builder** for "Build me a todo app":
+
+1. Writing a frontend webapp requires the same boilerplate each time
+2. → An `assets/hello-world/` template with boilerplate project files would be helpful
+
+**big-query** for "How many users logged in today?":
+
+1. Querying BigQuery requires re-discovering table schemas each time
+2. → A `references/schema.md` documenting table schemas would be helpful
+
+## Creating the skill
+
+1. Create the skill directory with `SKILL.md`
+2. Implement reusable resources (`scripts/`, `references/`, `assets/`)
+3. Write SKILL.md frontmatter and body
+4. Validate with `skills-ref validate ./my-skill`
+5. Iterate based on real usage

Change summary

Detailed changes

skills/authoring-skills/SKILL.md 🔗

skills/authoring-skills/references/checklist.md 🔗

skills/authoring-skills/references/patterns.md 🔗

skills/authoring-skills/references/process.md 🔗