Azure / Azure/azure-sdk-tools

Update skill-authoring skill with Anthropic best practices

Open
#14,547 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.