Defame1297
41c4da31cf
- Add agentskillsio/ reference docs (8 topic files, agentskills- prefix stripped) - Add agentsmd/ reference docs (4 topic files) - Add skill-write examples: skill-creator (Anthropic), writing-great-skills (mattpocock), writing-skills (obra/superpowers) with canonical sources.md files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
155 lines
3.8 KiB
Markdown
155 lines
3.8 KiB
Markdown
---
|
|
topic: agentskills-examples
|
|
source_keys:
|
|
- agentskills-quickstart
|
|
- agentskills-spec
|
|
- agentskills-best-practices
|
|
- agentskills-optimizing-descriptions
|
|
---
|
|
|
|
## Minimal skill (quickstart)
|
|
|
|
```
|
|
.agents/skills/roll-dice/SKILL.md
|
|
```
|
|
|
|
```markdown
|
|
---
|
|
name: roll-dice
|
|
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
|
|
---
|
|
|
|
To roll a die, use the following command that generates a random number from 1
|
|
to the given number of sides:
|
|
|
|
```bash
|
|
echo $((RANDOM % <sides> + 1))
|
|
```
|
|
|
|
Replace `<sides>` with the number of sides on the die (e.g., 6 for a standard
|
|
die, 20 for a d20).
|
|
```
|
|
|
|
This is a complete, working skill: one file, under 20 lines. The `name` matches the directory name; the description is specific and imperative.
|
|
|
|
## Extended frontmatter
|
|
|
|
```yaml
|
|
---
|
|
name: pdf-processing
|
|
description: >
|
|
Extract text and tables from PDF files, fill PDF forms, and merge multiple
|
|
PDFs. Use when the user mentions PDFs, forms, document extraction, or needs
|
|
to work with PDF files — even if they don't use the word "PDF."
|
|
license: Apache-2.0
|
|
compatibility: Requires python3, uv, and pdfplumber
|
|
metadata:
|
|
author: example-org
|
|
version: "1.0"
|
|
category: document
|
|
---
|
|
```
|
|
|
|
## Description before and after
|
|
|
|
```yaml
|
|
# Before — too vague, won't trigger reliably
|
|
description: Process CSV files.
|
|
|
|
# After — specific about capabilities, broad about when to apply
|
|
description: >
|
|
Analyze CSV and tabular data files — compute summary statistics,
|
|
add derived columns, generate charts, and clean messy data. Use this
|
|
skill when the user has a CSV, TSV, or Excel file and wants to explore,
|
|
transform, or visualize the data, even if they don't explicitly mention
|
|
"CSV" or "analysis."
|
|
```
|
|
|
|
## Gotchas section
|
|
|
|
```markdown
|
|
## Gotchas
|
|
|
|
- The `users` table uses soft deletes. Always include `WHERE deleted_at IS NULL`.
|
|
- User ID is `user_id` in the database, `uid` in the auth service, and
|
|
`accountId` in the billing API — they all refer to the same entity.
|
|
- `/health` returns 200 even when the database is down. Use `/ready` instead.
|
|
```
|
|
|
|
## Output format template inline
|
|
|
|
```markdown
|
|
## Report structure
|
|
|
|
Use this template:
|
|
|
|
\`\`\`markdown
|
|
# [Analysis Title]
|
|
|
|
## Executive summary
|
|
[One-paragraph overview of key findings]
|
|
|
|
## Key findings
|
|
- Finding 1 with supporting data
|
|
|
|
## Recommendations
|
|
1. Specific actionable recommendation
|
|
\`\`\`
|
|
```
|
|
|
|
## Multi-step checklist
|
|
|
|
```markdown
|
|
## Form processing workflow
|
|
|
|
Progress:
|
|
- [ ] Step 1: Analyze the form (`scripts/analyze_form.py`)
|
|
- [ ] Step 2: Create field mapping (`fields.json`)
|
|
- [ ] Step 3: Validate mapping (`scripts/validate_fields.py`)
|
|
- [ ] Step 4: Fill the form (`scripts/fill_form.py`)
|
|
- [ ] Step 5: Verify output (`scripts/verify_output.py`)
|
|
```
|
|
|
|
## Plan-validate-execute pattern
|
|
|
|
```markdown
|
|
## Database migration
|
|
|
|
1. Run `python scripts/migrate.py --verify --backup`
|
|
2. Review the migration plan output
|
|
3. If plan looks correct, run `python scripts/migrate.py --execute`
|
|
|
|
Do not modify commands or add flags.
|
|
```
|
|
|
|
## Conditional reference loading
|
|
|
|
```markdown
|
|
## Error handling
|
|
|
|
If the API returns a non-200 status code, read `references/api-errors.md`
|
|
for the full error code table and retry guidance.
|
|
```
|
|
|
|
## Eval test case (evals.json)
|
|
|
|
```json
|
|
{
|
|
"skill_name": "csv-analyzer",
|
|
"evals": [
|
|
{
|
|
"id": 1,
|
|
"prompt": "I have a CSV of monthly sales data in data/sales_2025.csv. Find the top 3 months by revenue and make a bar chart.",
|
|
"expected_output": "A bar chart image showing the top 3 months by revenue, with labeled axes.",
|
|
"files": ["evals/files/sales_2025.csv"],
|
|
"assertions": [
|
|
"The output includes a bar chart image file",
|
|
"The chart shows exactly 3 months",
|
|
"Both axes are labeled",
|
|
"The chart title or caption mentions revenue"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|