Update skill-authoring skill with Anthropic best practices
- Dominant language
- C#
- Stars
- 135
- Forks
- 260
- Avg merge
- 3d 1h
- Merged PRs (30d)
- 143
Description
Update the `skill-authoring` skill to incorporate best practices from [Anthropic's Agent Skills documentation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices).
## Description
The skill-authoring skill should be updated to include guidance from Anthropic's official best practices for writing effective Agent Skills. Key areas to incorporate:
### Core Principles
- **Concise is key** — context window is a public good; only add context Claude doesn't already have
- **Set appropriate degrees of freedom** — match specificity to task fragility (high/medium/low freedom)
- **Test with all models** — Skills should work across Haiku, Sonnet, and Opus
### Skill Structure
- **Naming conventions** — gerund form preferred (e.g., `processing-pdfs`), lowercase letters/numbers/hyphens only, max 64 chars
- **Effective descriptions** — always third person, specific with key terms, max 1024 chars
- **Progressive disclosure** — SKILL.md as overview pointing to detailed files; keep body under 500 lines
- **Avoid deeply nested references** — keep references one level deep from SKILL.md
- **Table of contents** for reference files longer than 100 lines
### Workflows & Feedback Loops
- Use workflows with checklists for complex tasks
- Implement feedback/validation loops (run validator → fix → repeat)
### Content Guidelines
- Avoid time-sensitive information
- Use consistent terminology throughout
### Common Patterns
- Template pattern (strict vs flexible)
- Examples pattern (input/output pairs)
- Conditional workflow pattern
### Evaluation & Iteration
- Build evaluations BEFORE writing documentation
- Develop Skills iteratively (Claude A designs, Claude B tests)
### Anti-Patterns
- Avoid Windows-style paths
- Avoid offering too many options
- MCP tool references must use `ServerName:tool_name` format
### Technical
- YAML frontmatter: `name` (max 64 chars) and `description` (max 1024 chars) required
- Token budget: SKILL.md body under 500 lines
- Checklist for effective Skills (core quality, code/scripts, testing)
## Original Context
Ronnie requested incorporating the Anthropic best practices page into the existing skill-authoring skill to keep our guidance aligned with the platform vendor's recommendations.
Contributor guide
Research direction
Locate the existing skill-authoring skill in the repository and read it alongside Anthropic's Agent Skills best-practices documentation. Update the guidance to cover the listed structure, workflow, content, evaluation, anti-pattern, and technical requirements, then verify that the resulting skill includes the requested checklist and stays within the stated limits.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100