Create Oss Skill

Create OSS Skill

Create Agent Skills that comply with the agentskills.io spec and follow authoring best practices.

Definition of World-Class

DEFINITION OF WORLD-CLASS (the bar): (1) discoverable+disambiguated by description alone (third-person, real keywords, explicit "Do NOT use for X; use " boundary, co-load relationships stated); (2) least-privilege tools derived from the body (read-only for advice/report skills; scoped Bash globs; report-only skills carry no Write); (3) orthogonal + single-owner (one job; every fact has one owning skill; portable core fenced from portfolio/host specifics); (4) eval-backed (evals/ with should-trigger/should-not-trigger near-misses + output evals on risky paths) -- evals are deferred this pass but state the intent.

Directory Structure

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── evals/            # Optional: eval test cases
    ├── evals.json
    └── files/

Place skills in skills//SKILL.md (project-level) or ~/.agents/skills//SKILL.md (user-level cross-client).

Frontmatter

| Field | Required | Constraints | |-------|----------|-------------| | name | Yes | 1-64 chars. Lowercase a-z, numbers, hyphens. No leading/trailing/consecutive hyphens. Must match parent directory name. | | description | Yes | 1-1024 chars. What it does and when to use it. Include trigger keywords. | | license | No | License name or reference to bundled file. | | compatibility | No | 1-500 chars. Environment requirements. Only if needed. | | allowed-tools | No | Space-delimited pre-approved tools. | | metadata | No | Arbitrary key-value map. |

Quote YAML values containing colons: description: "Use when: the user asks".

Writing Effective Descriptions

The description carries the entire burden of triggering; agents see only name + description at startup (~50-100 tokens) and decide whether to activate from this alone.

Principles:

• Imperative phrasing: "Use this skill when..." not "This skill does..."
• Focus on user intent: Describe what the user is trying to achieve, not internal mechanics
• Be pushy: Explicitly list contexts, including cases where the user doesn't name the domain directly
• Include keywords: Specific terms agents will match against

Good:

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

Bad: description: Helps with PDFs.

To test and optimize descriptions systematically, see [references/optimizing-descriptions.md](references/optimizing-descriptions.md).

Writing Effective Instructions

Start from Real Expertise

Don't rely solely on LLM general knowledge. Ground skills in:

• Hands-on tasks: Complete a real task with an agent, note corrections and context you provided, extract the reusable pattern
• Project artifacts: Internal docs, runbooks, API specs, code review comments, incident reports, version control history

Spend Context Wisely

The SKILL.md body competes for attention with everything else in the context window.

• Add what the agent lacks, omit what it knows. Don't explain what a PDF is. Do specify which library to use and why.
• Aim for moderate detail. Concise stepwise guidance with a working example outperforms exhaustive documentation.
• Design coherent units. Too narrow = multiple skills load for one task. Too broad = triggers on wrong tasks.

Calibrate Control

• Give freedom when multiple approaches are valid (explain why so the agent adapts)
• Be prescriptive when operations are fragile or a specific sequence must be followed
• Provide defaults, not menus: Pick one tool/approach, mention alternatives briefly

Patterns for Instructions

Gotchas sections highest-value content. Concrete corrections to mistakes the agent will make:

## Gotchas
- The `users` table uses soft deletes. Include `WHERE deleted_at IS NULL`.
- User ID is `user_id` in DB, `uid` in auth, `accountId` in billing.

Output templates more reliable than prose descriptions:

## Report structure
Use this template:
# [Title]
## Executive summary
## Key findings
## Recommendations

Checklists for multi-step workflows with dependencies:

## Workflow
- [ ] Step 1: Analyze (run `scripts/analyze.py`)
- [ ] Step 2: Validate (run `scripts/validate.py`)
- [ ] Step 3: Execute (run `scripts/execute.py`)

Validation loops instruct the agent to verify its own work:

1. Make edits
2. Run `python scripts/validate.py output/`
3. If fails: fix issues, re-validate
4. Only proceed when validation passes

Plan-validate-execute for batch/destructive operations:

1. Generate plan → `plan.json`
2. Validate plan against source of truth
3. Only execute after validation passes

Favor Procedures over Declarations

Teach how to approach a class of problems, not what to produce for a specific instance. The approach should generalize even when individual details are specific.

Progressive Disclosure Budget

| Tier | Content | Budget | |------|---------|--------| | 1. Catalog | name + description | ~50-100 tokens | | 2. Instructions | SKILL.md body | description: > . Use when , even if the user doesn't explicitly mention . license: Apache-2.0 ---

When to Use

Instructions

Gotchas

Examples

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Vague description | Add trigger keywords, capability list, imperative phrasing |
| Description says "This skill does..." | Use "Use this skill when..." |
| Name doesn't match directory | Rename directory or `name` field to match |
| Uppercase/underscores in name | Lowercase + hyphens only |
| Unquoted YAML colons | Quote: `description: "Use when: the user asks"` |
| Everything in one file | Split into references/, scripts/, assets/ |
| Missing "when to use" | Always include trigger conditions in description |
| Body too long | Target <500 lines, offload detail to reference files |
| Generic LLM-generated content | Ground in real expertise, project artifacts, hands-on tasks |
| Exhaustive rules over examples | Concise steps + working example outperform rule lists |
| Menus of equal options | Pick a default, mention alternatives briefly |
| Scripts with interactive prompts | Use flags/env vars/stdin, never TTY prompts |
| No validation step | Add validation loops or plan-validate-execute patterns |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [urmzd](https://github.com/urmzd)
- **Source:** [urmzd/dotfiles](https://github.com/urmzd/dotfiles)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.