Skip to content
Skills Library
AI & agents · Building & coding

skill-creator

/skill-creator

Guides authoring, reviewing, and validating agent skills (SKILL.md + metadata.json + references/ + scripts/) in this Capgo skills repository and similar ones. Covers trigger and negative-trigger design, lean SKILL.md with a when-to-load reference index, traps over basics, verification and error-handling sections, version tagging of facts, subagent-oriented skills (main-agent vs subagent split), optional when_to_use frontmatter, inline snapshots with allowed-tools, skillgrade evals, and this repo's canonical skills/ to plugins/ mirroring and registration. Use when creating a new skill, tighteni

Licence
MIT
Last repository change
17.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: graders/check-skill.js

What it does and when to use it

Guides authoring, reviewing, and validating agent skills (SKILL.md + metadata.json + references/ + scripts/) in this Capgo skills repository and similar ones. Covers trigger and negative-trigger design, lean SKILL.md with a when-to-load reference index, traps over basics, verification and error-handling sections, version tagging of facts, subagent-oriented skills (main-agent vs subagent split), optional when_to_use frontmatter, inline snapshots with allowed-tools, skillgrade evals, and this repo's canonical skills/ to plugins/ mirroring and registration. Use when creating a new skill, tighteni

Original author description

Guides authoring, reviewing, and validating agent skills (SKILL.md + metadata.json + references/ + scripts/) in this Capgo skills repository and similar ones. Covers trigger and negative-trigger design, lean SKILL.md with a when-to-load reference index, traps over basics, verification and error-handling sections, version tagging of facts, subagent-oriented skills (main-agent vs subagent split), optional when_to_use frontmatter, inline snapshots with allowed-tools, skillgrade evals, and this repo's canonical skills/ to plugins/ mirroring and registration. Use when creating a new skill, tighteni

How it works

  1. When to Use
  2. Reference Index
  3. Procedure
  4. Traps
  5. Verification
  6. Error Handling
Original SKILL.md headings · 116 lines, 1,126 words
SKILL.md preview
---
name: skill-creator
description: Guides authoring, reviewing, and validating agent skills (SKILL.md + metadata.json + references/ + scripts/) in this Capgo skills repository and similar ones. Covers trigger and negative-trigger design, lean SKILL.md with a when-to-load reference index, traps over basics, verification and error-handling sections, version tagging of facts, subagent-oriented skills (main-agent vs subagent split), optional when_to_use frontmatter, inline snapshots with allowed-tools, skillgrade evals, and this repo's canonical skills/ to plugins/ mirroring and registration. Use when creating a new skill, tightening a skill's description or triggers, splitting a long skill into references, or fixing `bun run lint-skills` failures. Do not use for app documentation, README or marketing copy, or library code that is not a skill.
---

# Skill Authoring

Write skills that load at the right moment, teach what the model does not already know, and prove their own results.

## When to Use

TRIGGER when:

- The user creates a skill directory, or asks to improve, review, or split an existing skill.
- A skill triggers too often, too rarely, or collides with a sibling skill.
- `bun run lint-skills` fails, or a skill must be registered in a plugin or the marketplace.
- The user wants a skillgrade eval for a skill.

Do not use when:

- The user is writing app docs, a README, a changelog, or marketing copy.
- The user is editing library or plugin source that is not a skill.

## Reference Index

Only load a reference when its topic is in play.

| File | Load when |
| --- | --- |
| `references/repo-layout.md` | Adding, renaming, or registering a skill in this repository, mirroring into `plugins/`, or reading lint errors |
| `references/authoring-patterns.md` | Writing the body: trigger design, reference index, traps, verification, version tags, subagent skills, inline snapshots |

## Procedure

### 1. Scope the skill

- Write one sentence: "Load this when <concrete situation>, so the agent can <outcome>."
- List the sibling skills that could also match. Each one becomes a negative trigger.
- Split the skill if it covers two unrelated workflows. Merge it if it would be a one-paragraph stub.
- Ask the user at real judgement calls (scope, audience, which product to prefer). Do not ask about things you can read from the repo.

### 2. Write the frontmatter

```yaml
---
name: my-skill                      # lowercase, hyphenated, equals the folder name
description: <what it does>. Use when <symptoms, APIs, file names, error strings>. Do not use for <case> (sibling-skill).
---
```

- The description is the only text the router sees. Put concrete triggers in it: command names, config keys, file names, exact error strings. Name the sibling skills in the negative clause.
- Keep it to one line and at most 1024 characters (lint enforces both).
- Optional `when_to_use:` is appended to `description` in Claude Code's skill listing. The combined text is truncated at 1,536 characters, so put the key use case first. Other agents ignore it, so never move the core trigger out of `description`.
- `allowed-tools:` only when the skill runs inline commands. Keep it minimal and read-only.

### 3. Write a lean body

Target fewer than about 250 lines. Use this order:

1. One-line purpose, plus a version line ("Checked against X 8.77, October 2026").
2. `## When to Use`: TRIGGER bullets and a `Do not use when` list that points to sibling skills by name. Lint requires the `## When to Use` heading.
3. `## Reference Index`: a table of each file and *when* to load it, with "Only load a reference when its topic is in play."
4. `## Procedure`: numbered steps. Inspect before you edit, and report findings before invasive changes.
5. `## Traps`: the non-obvious failures. Skip basics the model already knows.
6. `## Verification`: exact commands or checks that prove success.
7. `## Error Handling`: exact error strings mapped to fixes.

Move dense tables, long code, and per-topic depth into `references/<topic>.md`, one level deep. Put fragile or repetitive logic in `scripts/`.

### 4. Fact-check everything

- Verify every command, flag, config key, and API against source or official docs. Prefer the package's `--help`, its type definitions, or its repo over memory.
- Tag time-sensitive facts with versions ("Capacitor 8.5+", "Xcode 27", "CLI 8.77"). Gate optional behavior on feature detection when the targets can be older.
- If you cannot verify a fact, write "check current docs" and do not guess. List any commands that do not exist but are commonly hallucinated.

### 5. Match command context

- Skill prose uses standard `npm` / `npx` examples. Capacitor and Capgo CLI examples use `npx ...@latest`.
- Use `bun` / `bunx` only for this repository's own development and CI commands, or in Bun-specific skills.
- When a skill edits another repository, tell the agent to read that repository's instructions and follow its package-manager policy.

### 6. Preserve secrets

When a skill edits user files, tell the agent never to replace user-provided tokens, keys, certificates, or passwords with placeholders unless asked. Placeholders are for new generic examples only. Do not suggest rotating secrets unless the user asks.

### 7. Register and validate (this repo)

Follow `references/repo-layout.md`: canonical folder in `skills/`, `metadata.json`, an entry in `package.json` `skills`, exposure through a plugin folder plus `.claude-plugin/marketplace.json`, then `bun run sync-skills` and `bun run lint-skills`.

### 8. Add an eval when behavior must not regress

Use `skillgrade` (`eval.yaml` + `graders/`). Prefer deterministic graders for structure. Use an LLM rubric only for qualitative judgement. Run it with `bun run lint-skills-skillgrade`, or `ENABLE_SKILLGRADE=1` with an API key during lint.

## Traps

- A vague description ("Helps with X") never triggers. A greedy one ("Use for anything about mobile") steals sibling requests.
- An index entry like "see references/" with no load condition makes the agent read everything or nothing. Always say *when*.
- Stale facts age faster than structure. Put the version line at the top so reviewers know what to re-check.
- Editing a mirrored copy under `plugins/<plugin>/skills/` is wrong. Edit the canonical `skills/<name>/`, then sync.
- Inline `!`command`` snapshots run on every load. Keep them guarded (`fs.existsSync`), fast, short in output, and read-only.

## Verification

1. `bun run lint-skills` passes. It checks the name against the folder, the description length, the `## When to Use` heading, valid `metadata.json`, marketplace exposure, and byte-identical mirrors.
2. `wc -l skills/<name>/SKILL.md` is about 250 or less, and every file in `references/` is named in the Reference Index.
3. A grep for each command in the skill matches the tool's `--help` or source.
4. Mental routing test: three prompts that should trigger the skill do, and one prompt for each sibling skill does not.

## Error Handling

| Lint message | Fix |
| --- | --- |
| `<skill>: name "<x>" does not match folder name` | Make the frontmatter `name` equal the directory |
| `<skill>: description exceeds 1024 characters` | Cut filler, keep concrete triggers and the negative clause |
| `<skill>: missing usage guidance` | Add a `## When to Use` heading |
| `<skill>: missing metadata.json` / `invalid metadata.json` | Create or fix the JSON (see `references/repo-layout.md`) |
| `claude marketplace: skill "<x>" is not exposed by any plugin` | Create `plugins/<plugin>/skills/<x>/`, then `bun run sync-skills` |
| `mirrored skills: ... (run bun run sync-skills)` | Run `bun run sync-skills`. Never hand-edit the mirror |
| `<plugin>: unknown skill "<x>"` | The plugin folder has no matching `skills/<x>`. Create the canonical skill or remove the folder |
Files in this package (7)
  • SKILL.md 8 KB
  • eval.yaml 1 KB
  • metadata.json 1 KB
  • fixtures/broken-skill/SKILL.md 1 KB
  • graders/check-skill.js 1 KB
  • references/authoring-patterns.md 5 KB
  • references/repo-layout.md 3 KB

Versions

RepositoryScoreLicence
This page · Cap-go/capgo-skills100MIT
opencue/cuecards100MIT
zzusp/night-bot100MIT
gonzalezpazmonica/savia100MIT
iuliandita/skills100MIT
langfuse/langfuse100MIT
seaworld008/commonly-used-high-value-skills100MIT
dfinity/icskills100Apache-2.0
LumenJSN/Aris100Apache-2.0

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version fde74aaa1230 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100writing-skills
    Author and pressure-test agent skills—triggers, thin SKILL.md, references, validation. Use when creating or revising skills in this repo. Triggers: "write a skill", "new skill", "skill authoring", "improve skill triggers".
  • 90skill-authoring
    Create, edit, or review a skill in the ramottamado/skills repository (a repo with skills/<name>/SKILL.md and a .claude-plugin/marketplace.json). Use when the user asks to add a new skill, rewrite a skill's description or triggers, split a skill into references, or check a skill…
  • 100skill-writer
    Guide users through creating Agent Skills for Claude Code. Use when the user wants to create, write, author, or design a new Skill, or needs help with SKILL.md files, frontmatter, or skill structure.
  • 100authoring-skills
    How to create and maintain agent skills in .agents/skills/. Use when creating a new SKILL.md, writing skill descriptions, choosing frontmatter fields, or deciding what content belongs in a skill vs AGENTS.md. Covers the supported spec fields, description writing, naming…
  • 100update-skill
    Create or update skills by generating, editing, or refining SKILL.md files in this repository. Use when authoring new skills or revising the structure, frontmatter, or guidance for existing ones.
  • 100skills-creator
    Create plugin components (skills, agents, commands, full plugins) and decide skill vs agent architecture. TRIGGER WHEN: creating, adding or scaffolding a new skill, agent, command or plugin ("new skill", "new agent", "new plugin", "skills-creator"). DO NOT TRIGGER WHEN: auditing…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.