Skill Authoring and Refactoring

What it does

When your agent uses it

• Creating a new skill from API docs, specs or a repository
• Shortening or clarifying a skill that misfires or runs too long
• Designing frontmatter and trigger phrases so a skill activates reliably
• Adding a validator and quality gate to a skill

Example prompts

• “Turn these API docs into a skill with a SKILL.md and a references folder.”
• “My skill triggers on unrelated requests, so rewrite its description and boundaries.”
• “Run the validator on my skill folder and fix what it reports.”

Requirements

• Bash, for the create-skill and validate-skill scripts

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

1. 1A concrete directory layout (typically skills//)
2. 2An actionable SKILL.md with decidable triggers, boundaries, and reproducible examples
3. 3Long-form docs moved to references/ with a references/index.md
4. 4A pre-delivery checklist (Quality Gate)

What it can do on your machine

Read from SKILL.md and the folder at commit 9b42dd1. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 2 files in scripts/ (Shell), which the agent can run.

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • support.claude.com
  • docs.claude.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Skill Authoring and Refactoring loads about 2k tokens when it runs, and up to ~6.4k if it reads all its reference files. Until then it costs about 58 tokens; SKILL.md has 493 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~58

When it runs · the whole SKILL.md, loaded when a task matches

~2k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~6.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from 2025Emma/vibe-coding-cn at commit 9b42dd1, republished under its MIT licence (© 2025Emma). 493 words, ~2,030 tokens.

name

claude-skills

description

Claude Skills meta-skill: extract domain material (docs/APIs/code/specs) into a reusable Skill (SKILL.md + references/scripts/assets), and refactor existing Skills for clarity, activation reliability, and quality gates.

skill-name/
|-- SKILL.md              # Required: entrypoint with YAML frontmatter
|-- references/           # Optional: long-form docs/evidence/index
|   `-- index.md          # Recommended: navigation index
|-- scripts/              # Optional: helpers/automation
`-- assets/               # Optional: templates/configs/static assets

---
name: skill-name
description: "What it does + when to use (activation triggers)."
---

---
name: my-skill
description: "[Domain] capability: includes [capability 1], [capability 2]. Use when [decidable triggers]."
---

# my-skill Skill

One sentence that states the boundary and the deliverable.

## When to Use This Skill

Trigger when any of these applies:
- [Trigger 1: concrete task/keyword]
- [Trigger 2]
- [Trigger 3]

## Not For / Boundaries

- What this skill will not do (prevents misfires and over-promising)
- Required inputs; ask 1-3 questions if missing

## Quick Reference

### Common Patterns

**Pattern 1:** one-line explanation
```text
[command/snippet you can paste and run]

### Authoring Rules (Non-negotiable)

1. Quick Reference is for short, directly usable patterns
   - Keep it <= 20 patterns when possible.
   - Anything that needs paragraphs of explanation goes to `references/`.
2. Activation must be decidable
   - Frontmatter `description` should say "what + when" with concrete keywords.
   - "When to Use" must list specific tasks/inputs/goals, not vague help text.
   - "Not For / Boundaries" is mandatory for reliability.
3. No bluffing on external details
   - If the material does not prove it, say so and include a verification path.

### Workflow (Material -> Skill)

Do not skip steps:
1. Scope: write MUST/SHOULD/NEVER (three sentences total is fine)
2. Extract patterns: pick 10-20 high-frequency patterns (commands/snippets/flows)
3. Add examples: >= 3 end-to-end examples (input -> steps -> acceptance)
4. Define boundaries: what is out-of-scope + required inputs
5. Split references: move long text into `references/` + write `references/index.md`
6. Apply the gate: run the checklist and the validator

### Quality Gate (Pre-delivery Checklist)

Minimum checks (see `references/quality-checklist.md` for the full version):
1. `name` matches `^[a-z][a-z0-9-]*$` and matches the directory name
2. `description` states "what + when" with concrete trigger keywords
3. Has "When to Use This Skill" with decidable triggers
4. Has "Not For / Boundaries" to reduce misfires
5. Quick Reference is <= 20 patterns and each is directly usable
6. Has >= 3 reproducible examples
7. Long content is in `references/` and `references/index.md` is navigable
8. Uncertain claims include a verification path (no bluffing)
9. Reads like an operator's manual, not a documentation dump

Validate locally:

```bash
# From repo root (basic validation)
./skills/claude-skills/scripts/validate-skill.sh skills/<skill-name>

# From repo root (strict validation)
./skills/claude-skills/scripts/validate-skill.sh skills/<skill-name> --strict

# From skills/claude-skills/ (basic validation)
./scripts/validate-skill.sh ../<skill-name>

# From skills/claude-skills/ (strict validation)
./scripts/validate-skill.sh ../<skill-name> --strict

# From repo root (generate into ./skills/)
./skills/claude-skills/scripts/create-skill.sh my-skill --full --output skills

# From skills/claude-skills/ (generate into ../ i.e. ./skills/)
./scripts/create-skill.sh my-skill --full --output ..

# Minimal skeleton
./skills/claude-skills/scripts/create-skill.sh my-skill --minimal --output skills

© 2025Emma, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 10 other files (scripts, references, assets) in i18n/zh/skills/claude-skills of 2025Emma/vibe-coding-cn.

• SKILL.md
• AGENTS.md
• assets/template-complete.md
• assets/template-minimal.md
• references/README.md
• references/anti-patterns.md
• references/index.md
• references/quality-checklist.md
• references/skill-spec.md
• scripts/create-skill.sh
• scripts/validate-skill.sh

Open the folder on GitHubat commit 9b42dd1

Used in 2 other repositories

We found 2 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 2 other GitHub owners. This page covers the copy in 2025Emma/vibe-coding-cn, which our catalogue first saw on October 7, 2026.

• aiskillstore/marketplaceskills/2025emma/claude-skills
• foryourhealth111-pixel/Vibe-Skillsbundled/skills/claude-skills