Awesome-omni-skill skillcraft

Creates and validates Agent Skills (SKILL.md). Use when creating skills, writing frontmatter, or validating skill structure.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/ai-agents/skillcraft" ~/.claude/skills/diegosouzapw-awesome-omni-skill-skillcraft && rm -rf "$T"

manifest: skills/ai-agents/skillcraft/SKILL.md

source content

Skills Development

Create skills that follow the Agent Skills specification—an open format supported by Claude Code, Cursor, VS Code, GitHub Copilot, Codex, and other agent products.

Workflow

Discovery — Understand what the skill should do
Archetype Selection — Choose the best pattern
Initialization — Create skill structure
Customization — Tailor to specific needs
Validation — Verify quality before committing

Stage 1: Discovery

Ask about the skill:

What problem does this skill solve?
What are the main capabilities?
What triggers should invoke it? (phrases users would say)
Where should it live? (personal, project, or plugin)
Is it for use within a Claude plugin? If so, load the
```
/claude-craft
```
and
```
/claude-plugins
```
skills.

Stage 2: Archetype Selection

Archetype	Use When	Example
simple	Basic skill without scripts	Quick reference, style guide
api-wrapper	Wrapping external APIs	GitHub API, Stripe API
document-processor	Working with file formats	PDF extractor, Excel analyzer
dev-workflow	Automating development tasks	Git workflow, project scaffolder
research-synthesizer	Gathering and synthesizing information	Competitive analysis, literature review

Stage 3: Directory Structure

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

Stage 4: Frontmatter Schema

---
name: skill-name
description: "What it does and when to use it. Include trigger keywords."
version: 1.0.0 # optional, recommended
license: Apache-2.0 # optional
compatibility: Requires git and jq # optional
metadata: # optional
  author: your-org
  category: development
  tags: [testing, automation]
---

Field	Required	Constraints
`name`	Yes	2-64 chars, lowercase/numbers/hyphens, must match directory
`description`	Yes	10-1024 chars, quoted, describes what + when
`version`	No	Semantic version (MAJOR.MINOR.PATCH)
`license`	No	License name or reference
`compatibility`	No	1-500 chars, environment requirements
`metadata`	No	Object for custom fields

Important:

Always wrap
```
description
```
in double quotes — values containing colons, commas, or special characters can break YAML parsing otherwise.
Platform-specific fields (e.g., Claude's
```
allowed-tools
```
,
```
user-invocable
```
) should be added per-platform. Load the
```
/claude-craft
```
skill for Claude-specific fields.

Custom Frontmatter

Custom fields must be nested under

metadata

---
name: my-skill
description: "..."
metadata:
  author: your-org
  version: "1.0"
  category: development
  tags: [typescript, testing]
---

Top-level custom fields are not allowed and may cause parsing errors.

Description Formula

[WHAT] + [WHEN] + [TRIGGERS]

description: "Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or document extraction."

Checklist:

Stage 5: Validation

Validation Checklist

A. YAML Frontmatter

Opens with
```
---
```
on line 1, closes with
```
---
```
```
name
```
and
```
description
```
present (required)
```
description
```
wrapped in double quotes
Uses spaces, not tabs
Special characters quoted

B. Naming

Lowercase, numbers, hyphens only (1-64 chars)
Matches parent directory name
No
```
--
```
, leading/trailing hyphens
No
```
anthropic
```
or
```
claude
```
in name
Does not collide with a built-in slash command

C. Description Quality

WHAT: Explains capabilities
WHEN: States "Use when..." conditions
TRIGGERS: 3-5 keywords users would say
Third-person voice (not "I can" or "you can")

D. Structure

SKILL.md under 500 lines
All referenced files exist
No TODO/placeholder markers
Progressive disclosure (details in
```
references/
```
)
No
```
<bang>`command`
```
preprocessing patterns (use
```
<bang>
```
instead of literal
```
!
```
)

Report Format

# Skill Check: {skill-name}

**Status**: PASS | WARNINGS | FAIL
**Issues**: {critical} critical, {warnings} warnings

## Critical (must fix)

1. {issue with fix}

## Warnings (should fix)

1. {issue with fix}

## Strengths

- {what's done well}

Core Principles

Concise is key

Context window is shared. Only include what the agent doesn't already know. Challenge each paragraph—does it justify its token cost?

Third-person descriptions

Descriptions inject into system prompt:

"Extracts text from PDFs"
"I can help you extract text from PDFs"

Progressive disclosure

Keep SKILL.md under 500 lines. Move details to:

```
references/
```
- Detailed docs, API references
```
scripts/
```
- Executable utilities (code never enters context)
```
assets/
```
- Templates, data files

Preprocessing safety

SKILL.md files are preprocessed by Claude Code —

<bang>`command`

syntax executes at load time, even inside code fences. When documenting this syntax in SKILL.md, use

<bang>

as a stand-in for

. Reference files and EXAMPLES.md are not preprocessed, so literal

is safe there.

Skills that intentionally preprocess should declare

metadata.preprocess: true

. Run

/skillcheck

to lint for unintentional preprocessing patterns.

Token loading:

Metadata (~100 tokens): name + description at startup
Instructions (<5000 tokens): SKILL.md body when activated
Resources (as needed): files loaded only when referenced

Degrees of freedom

Match instruction specificity to task requirements:

High freedom (text): Multiple valid approaches, use judgment
Medium freedom (pseudocode): Preferred pattern with variation allowed
Low freedom (scripts): Exact sequence required, no deviation

See patterns.md for detailed examples.

Naming Requirements

Lowercase letters, numbers, hyphens only
Cannot start/end with hyphen or contain
```
--
```
Must match parent directory name
Cannot contain
```
anthropic
```
or
```
claude
```
Must not collide with built-in slash commands (
```
/help
```
,
```
/status
```
,
```
/config
```
,
```
/compact
```
,
```
/review
```
,
```
/model
```
,
```
/init
```
,
```
/login
```
,
```
/logout
```
,
```
/doctor
```
,
```
/clear
```
,
```
/mcp
```
,
```
/memory
```
,
```
/permissions
```
,
```
/terminal-setup
```
,
```
/vim
```
,
```
/cost
```
,
```
/bug
```
). Built-in commands take precedence — a skill with a colliding name will be unreachable via slash invocation.

Recommended: Gerund form (

processing-pdfs

reviewing-code

)

Platform-Specific Guidance

Skills are cross-platform, but each tool has specific implementation details:

Claude Code: Load the
```
/claude-craft
```
skill for Claude-specific skill authoring
Codex CLI: See codex.md for discovery paths,
```
$skill-name
```
invocation

See implementations.md for storage paths and invocations.md for activation patterns.

References

steps-pattern.md - Composable skill workflows with dependencies
patterns.md - Degrees of freedom, script design, variant organization
best-practices.md - Community patterns, testing strategies
quick-reference.md - Fast checklist and one-liners
implementations.md - Per-tool storage paths
invocations.md - How tools activate skills
compatibility.md - Path compatibility matrix