Skill Best Practices

These best practices are based on Anthropic’s official skill authoring guidelines and apply to all skills, whether generated by SkillThis or written by hand.

1. Conciseness

“The context window is a public good.”

The AI is smart. Only add context it doesn’t already have. Challenge every piece of content:

“Does the AI really need this explanation?”
“Can I assume the AI knows this?”
“Does this paragraph justify its token cost?”

Verbose (bad):

PDF (Portable Document Format) files are a common file format
that contains text, images, and other content. To extract text
from a PDF, you'll need to use a library...

Concise (good):

Use pdfplumber for text extraction:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

2. Degrees of Freedom

Match specificity to task fragility. Not every skill should be prescriptive.

Freedom Level	When to Use	Example
High	Multiple approaches valid, context-dependent	Code review process
Medium	Preferred pattern exists, some variation okay	Report generation
Low	Operations are fragile, consistency critical	Database migrations

High-freedom skills describe what to look for and why. Low-freedom skills specify exact steps and commands.

3. Description Writing

The description field in YAML frontmatter is injected into AI system prompts. Always use third person.

Good:

description: Processes Excel files and generates reports. Use when working with spreadsheets or when the user mentions Excel, CSV, or data exports.

Bad:

description: I can help you process Excel files and generate reports.

Always include both what it does and when to use it (trigger phrases).

4. Naming Conventions

Use gerund form (verb ending in -ing):

processing-pdfs
analyzing-spreadsheets
managing-databases
writing-documentation
reviewing-pull-requests

Avoid vague names (helper, utils, tools) and overly generic names (documents, data, files).

5. Provide Defaults, Not Options

Don’t present the AI with choices. Give it the recommended approach.

Too many options (bad):

You can use either PostgreSQL, MySQL, or SQLite. For PostgreSQL,
use pg library. For MySQL, use mysql2. For SQLite, use better-sqlite3.
Each has different connection string formats...

Default with escape hatch (good):

Use PostgreSQL with the pg library:
```javascript
const pool = new Pool({ connectionString: process.env.DATABASE_URL })

If the project uses a different database, adapt accordingly.

## 6. Concrete Examples Over Abstract Descriptions

Every example should be an input/output pair.

**Abstract (bad):**
```markdown
When reviewing code, look for common issues like security
vulnerabilities and performance problems.

Concrete (good):

**Example 1:**
Input: PR adds a new `/api/users/:id` DELETE endpoint
Output:
- Flag: No authentication check on delete operation
- Flag: Missing rate limiting
- Suggestion: Add soft-delete with `deleted_at` timestamp

7. Workflow Checklists

For complex multi-step tasks, include a checklist the AI can track:

Copy this checklist and track your progress:

Progress:
- [ ] Step 1: Analyze the input
- [ ] Step 2: Create mapping
- [ ] Step 3: Validate
- [ ] Step 4: Execute
- [ ] Step 5: Verify output

This helps the AI maintain state across long interactions.

8. Progressive Disclosure

Keep the main skill file focused. Link to detailed reference files for advanced features:

## Quick Start
[Immediate value code example]

## Advanced Features
**Form filling**: See [FORMS.md](FORMS.md)
**API reference**: See [REFERENCE.md](REFERENCE.md)

This pattern works in Claude Code where skills can reference other files in the same directory.

Anti-Patterns to Avoid

Anti-Pattern	Why It’s Bad
Time-sensitive information	”Before August 2025, use X” becomes stale
Inconsistent terminology	Using different terms for the same concept confuses the AI
Too many options	Decision fatigue reduces the AI’s effectiveness
Over-explaining basics	Wastes tokens on knowledge the AI already has
First/second person in description	Confuses the system prompt context

External Resources

Agent Skills Best Practices - Anthropic’s official guide
Claude Code Skills - Claude Code skills documentation
Agent Skills Overview - Skills specification overview