holocron/plugins/kyberforge/docs/research/docs/agentskillsio/examples.md

topic, source_keys

topic	source_keys
agentskills-examples	agentskills-quickstart agentskills-spec agentskills-best-practices agentskills-optimizing-descriptions

Minimal skill (quickstart)

.agents/skills/roll-dice/SKILL.md

---
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

# 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

## 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

## 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

## 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

## 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

## 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)

{
  "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"
      ]
    }
  ]
}