Writing Effective Instructions

Writing Style

Write entirely in imperative/infinitive form (verb-first). Use objective, instructional language.

Good: "To accomplish X, do Y" / "Run script.py to validate"
Bad: "You should do X" / "If you need to do X"

Recommended SKILL.md Structure

---
name: your-skill  # optional namespace: ck:your-skill
description: [What + When + Key capabilities]
---
# Skill Name
## Instructions
### Step 1: [First Major Step]
Clear explanation. Example with expected output.
### Step 2: [Next Step]
(Continue as needed)
## Examples
### Example 1: [Common scenario]
**User says:** "[trigger phrase]"
**Actions:** 1. Do X  2. Do Y
**Result:** [Expected outcome]
## Troubleshooting
**Error:** [Message] → **Solution:** [Fix]

Be Specific and Actionable

Good:

Run `python scripts/validate.py --input {filename}` to check format.
If validation fails, common issues:
- Missing required fields (add to CSV)
- Invalid date formats (use YYYY-MM-DD)

Bad:

Validate the data before proceeding.

Include Error Handling

## Common Issues
### MCP Connection Failed
If "Connection refused":
1. Verify MCP server running: Settings > Extensions
2. Confirm API key valid
3. Reconnect: Settings > Extensions > [Service] > Reconnect

Reference Bundled Resources Clearly

Before writing queries, consult `references/api-patterns.md` for:
- Rate limiting guidance
- Pagination patterns
- Error codes and handling

Use Progressive Disclosure

Keep SKILL.md focused on core instructions (<300 lines). Move to references/:

Detailed API documentation
Database schemas
Extended examples
Domain-specific rules
Troubleshooting guides

Critical Instructions

Put at the top of SKILL.md. Use headers like ## CRITICAL or ## IMPORTANT. Repeat key points if they're frequently missed.

Advanced technique: For critical validations, bundle a script that performs checks programmatically rather than relying on language instructions alone. Code is deterministic; language interpretation isn't.

What NOT to Include

General knowledge Claude already has
Tool documentation (teach workflows, not what tools do)
Verbose explanations (sacrifice grammar for concision)
Duplicated content between SKILL.md and references

2.3 KiB Raw Blame History