Przejdź do treści
Biblioteka skilli
AI i agenci · Budowanie i kod

create-skill

/create-skill

Pomaga tworzyć i pisać skille agenta Cursor oraz wyjaśnia strukturę skilla, format SKILL.md i dobre praktyki.

Repozytorium
skill-issue ↗
Licencja
MIT
Ostatnia zmiana repozytorium
16.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
3
Przestarzałość

Brak sygnałów. Repozytorium zmienione 16.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Pomaga tworzyć i pisać skille agenta Cursor oraz wyjaśnia strukturę skilla, format SKILL.md i dobre praktyki.

Oryginalny opis (EN)

Use when creating, writing, or authoring a new Cursor agent skill, or when asking about skill structure, SKILL.md format, or skill best practices.

Jak działa

  1. Skill Types
  2. Requirements Gathering
  3. Design
  4. Authoring Principles
  5. Common Patterns
  6. Script Guidelines
  7. MCP Tool References
  8. External Content and Licensing
  9. Testing and Validation
  10. Verification Checklist
Sekcje z nagłówków SKILL.md, w oryginale · 220 linii, 1 317 słów
Podgląd SKILL.md
---
name: create-skill
description: Use when creating, writing, or authoring a new Cursor agent skill, or when asking about skill structure, SKILL.md format, or skill best practices.
---

# Create Skill

## Skill Types

Categorize before writing -- this determines structure, degrees of freedom, and testing approach:

- **Technique**: concrete method with steps (e.g. condition-based-waiting)
- **Pattern**: mental model / way of thinking (e.g. flatten-with-flags)
- **Reference**: API docs, syntax guides, tool documentation
- **Workflow**: multi-step process with decision points (e.g. ship-it)

## Requirements Gathering

Infer from conversation context when possible. If clarification is needed, use AskQuestion (or ask conversationally if unavailable). Capture:

1. **Purpose and scope**: what specific task or workflow
2. **Storage location**: personal (`~/.cursor/skills/`) or project (`.cursor/skills/`)
3. **Trigger scenarios**: when should the agent apply this skill
4. **Domain knowledge**: what the agent wouldn't already know
5. **Output format**: templates, styles, or conventions required
6. **Existing patterns**: examples or conventions to follow

## Design

### Name

- Lowercase letters, numbers, hyphens only. Max 64 chars
- Prefer verb-first or gerund form: `create-skill` > `skill-creation`, `analyze-sessions` > `session-analysis`
- Name by what you DO or core insight, not generic labels
- Avoid: `helper`, `utils`, `tools`, `misc`

### Description (CSO-Critical)

The description determines whether the agent loads this skill. Max 1024 chars, third person.

**Start with "Use when..."** -- describe ONLY triggering conditions (symptoms, situations, contexts).

**NEVER summarize the skill's workflow or process.** Testing shows agents follow descriptions as shortcuts, skipping the full skill body. A description saying "does X then Y" causes agents to do exactly X then Y without reading the actual detailed instructions.

Include concrete triggers: error messages, symptoms, tool names, synonyms.

```yaml
# BAD: workflow summary -- agent will shortcut to this
description: Analyzes code diffs, generates commit messages, and pushes to remote.

# BAD: too vague
description: Helps with documents.

# GOOD: triggering conditions only
description: Use when reviewing pull requests, examining code changes, or when asked for a code review.

# GOOD: specific triggers with keywords
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently.
```

### Directory Layout

```
skill-name/
├── SKILL.md              # Required -- main instructions
├── reference.md          # Optional -- detailed docs (progressive disclosure)
└── scripts/              # Optional -- utility scripts
    └── validate.py
```

## Authoring Principles

Express requirement levels in skill instructions with RFC 2119 key words (`MUST` / `SHOULD` / `MAY`), sparingly and only where the level matters. See the `normative-language` rule.

### Conciseness

The context window is shared. Only add what the agent doesn't already know. Challenge each paragraph: "Does this justify its token cost?"

```markdown
# GOOD (~50 tokens): assumes agent knows what PDFs are
## Extract PDF text
Use pdfplumber:
  import pdfplumber
  with pdfplumber.open("file.pdf") as pdf:
      text = pdf.pages[0].extract_text()

# BAD (~150 tokens): explains what a PDF is
PDF (Portable Document Format) files are a common file format...
```

### Progressive Disclosure

Keep SKILL.md under 500 lines. Put detailed reference material in separate files the agent reads only when needed. Keep references **one level deep** from SKILL.md -- deeply nested references may be partially read.

```markdown
## Advanced features
**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
```

For reference files over 100 lines, include a table of contents at the top.

### Degrees of Freedom

Match specificity to task fragility:

- **High freedom** (text instructions): multiple valid approaches, context-dependent. Example: code review guidelines
- **Medium freedom** (pseudocode/templates): preferred pattern with acceptable variation. Example: report generation
- **Low freedom** (exact scripts): fragile operations, consistency critical. Example: database migrations -- "Run exactly this. Do not modify."

### Token Efficiency

- Move details to `--help` flags or reference files
- Cross-reference other skills instead of repeating content
- One excellent example beats many mediocre ones
- Compress examples: show minimal input/output, not verbose narratives

## Common Patterns

Brief summary below. See [best-practices.md](best-practices.md) for detailed examples with good/bad comparisons.

- **Template**: provide output format templates (strict for APIs, flexible for analysis)
- **Examples**: input/output pairs showing desired style and detail level
- **Workflow/Checklist**: sequential steps with copy-paste progress checklist
- **Conditional workflow**: decision points guiding to different paths
- **Feedback loop**: validate → fix → re-validate cycle for quality-critical tasks

## Script Guidelines

When including utility scripts:

- **Solve, don't punt**: handle errors explicitly instead of failing and letting the agent figure it out
- **Self-documenting constants**: no magic numbers -- comment why each value was chosen
- **Clear intent**: state whether the agent should **execute** the script ("Run `analyze.py`") or **read** it as reference ("See `analyze.py` for the algorithm")
- Pre-made scripts are more reliable than generated code, save tokens, and ensure consistency

## MCP Tool References

Always use fully qualified names: `ServerName:tool_name`

```markdown
Use the GitHub:create_issue tool to create issues.
Use the Atlassian:getJiraIssueTypeMetaWithFields tool to discover custom fields.
```

## External Content and Licensing

When incorporating content from web sources or OSS into a skill:

- **Inline the content** -- skills should be self-contained with no runtime web lookups
- **Always cite the source URL** even when content is fully inlined
- **Comply with licensing terms**: MIT/Apache/etc. require copyright notice preserved
- Include a **Sources** section in the skill with attribution and license type
- For OSS: link to the repo/file, note the license, credit the author(s)
- For web content (docs, blog posts): link to the source URL for reference

## Testing and Validation

Skills are TDD applied to process documentation. If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.

### RED -- Baseline

Run a representative scenario WITHOUT the skill. Document:
- What choices did the agent make?
- What rationalizations did it use (verbatim)?
- Which pressures triggered violations?

### GREEN -- Write Minimal Skill

Write the skill addressing those specific failures. Run the same scenario WITH the skill. The agent should now comply.

### REFACTOR -- Close Loopholes

Agent found a new rationalization? Add an explicit counter. Re-test until the skill is robust.

### Testing by Skill Type

- **Discipline-enforcing** (rules/requirements): pressure scenarios combining time + sunk cost + exhaustion
- **Technique** (how-to guides): application scenarios + edge cases + missing-information tests
- **Pattern** (mental models): recognition scenarios + counter-examples (when NOT to apply)
- **Reference** (documentation): retrieval scenarios + application scenarios + gap testing

### Bulletproofing Discipline Skills

For skills that enforce rules, agents will rationalize under pressure:

- Don't just state the rule -- forbid specific workarounds
- Build a rationalization table: `| Excuse | Reality |`
- Create a red flags list for self-checking
- Address "spirit vs letter" arguments: "Violating the letter of the rules IS violating the spirit"

## Verification Checklist

Before finalizing:

- [ ] Description starts with "Use when..." -- triggering conditions only, no workflow summary
- [ ] SKILL.md body is under 500 lines
- [ ] Consistent terminology throughout (pick one term, use it everywhere)
- [ ] File references are one level deep from SKILL.md
- [ ] No time-sensitive information (use "old patterns" section if needed)
- [ ] Examples are concrete, not abstract
- [ ] Tested with a representative scenario (baseline → with skill)
- [ ] External content is inlined with source attribution

## Anti-Patterns

- **Narrative storytelling**: "In session 2025-10-03, we found..." -- too specific, not reusable
- **Multi-language dilution**: one excellent example in the most relevant language beats mediocre examples in five languages
- **Workflow summary in description**: causes agents to shortcut past the actual skill body
- **Generic labels**: helper1, step3, pattern4 -- labels should have semantic meaning
- **Windows-style paths**: always use forward slashes (`scripts/helper.py`)
- **Too many options**: provide a default with an escape hatch, not a menu of five libraries
- **Vague names**: `helper`, `utils`, `tools` -- name by what the skill does
- **Inconsistent terminology**: pick one term (e.g. always "API endpoint", not mixing "URL", "route", "path")

---

## Sources

Content in this skill and [best-practices.md](best-practices.md) incorporates material from:

- [Anthropic: Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
- [obra/superpowers: writing-skills](https://github.com/obra/superpowers/blob/main/skills/writing-skills/SKILL.md) -- used under [MIT License](https://github.com/obra/superpowers/blob/main/LICENSE), copyright Jesse Vincent
Pliki w paczce (2)
  • SKILL.md 10 KB
  • best-practices.md 13 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · paultyng/skill-issue100MIT
mgiovani/cc-arsenal100MIT
zylos-ai/zylos-core100MIT
mthines/agent-skills100MIT
jongio/skills100MIT
fairladyz625/harness-anything100AGPL-3.0
coco-research/coco100MIT
builderio/agent-native100MIT
BrandeisPatrick/silo-harness100MIT

Migawka bazy z 13.11.2026 · wersja paczki 25e38e541827 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95creating-agent-skills
    Tworzy i poprawia skille Claude Code: pliki SKILL.md, strukturę skilla i dobre praktyki jego pisania.
  • 95creating-agent-skills
    Tworzy i poprawia skille Claude Code: pliki SKILL.md, strukturę skilla i dobre praktyki jego pisania.
  • 95creating-agent-skills
    Podpowiada, jak tworzyć i ulepszać skille Claude Code: pliki SKILL.md, strukturę i dobre praktyki.
  • 100skill-creator
    Pomaga tworzyć, poprawiać i audytować skille Claude Code: strukturę SKILL.md, szkielet, pakowanie i dobre praktyki.
  • 95skill-development
    Podpowiada, jak tworzyć skille do wtyczek Claude Code: strukturę, opisy, stopniowe ujawnianie treści i dobre praktyki.
  • 100create-agent-skills
    Doradza przy tworzeniu skilli i komend slash dla Claude Code: pliki SKILL.md, struktura skilla i dobre praktyki.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.