Skeall

LLM-friendliness patterns

These patterns come from real cross-platform testing. Apply them when creating or improving skills.

Do

• Tables over prose for structured data (parameters, options, comparisons)
• Single source of truth for any concept explained more than once
• Instruction-based framing: "This skill provides instructions for X. Follow these patterns exactly."
• Imperative verbs: "Call X after Y", "Use Z for W"
• Compact routing table at the top pointing to reference files
• Parameter comments inline in code blocks: providerAddress, // 1st: wallet address
• Copyable progress checklists for multi-step workflows (LLM tracks completion)
• Validation feedback loops for quality-sensitive output (generate, score, retry if needed)
• Consistent freedom level per section — do not mix exact scripts with vague guidance. See references/advanced-patterns.md

Do not

• Persona-based framing: "You are an expert in..." (Claude-leaning, other LLMs respond better to instructions)
• Emoji markers in headings or structural elements (token-expensive, parsed inconsistently). Emoji in frontmatter metadata values is data and acceptable
• Unicode arrows (→, ←) for data flow — use tables or plain prose
• Blockquote warnings at top of SKILL.md (wastes prime token space, primes distrust)
• "When Users Ask" checklists with 10+ items (bury critical rules, use tables instead)
• Synonym cycling for the same concept (confuses LLMs about whether it's the same thing)
• Repeated content (wastes tokens, risks contradictions if copies drift)
• Assuming exclusive activation (other skills may load simultaneously — declare dependencies explicitly)

Description field optimization

Good description pattern:

{Product/Tool name} guide for {primary use case}. Covers {feature list}.
Use this skill for {trigger phrases separated by commas}.

Example:

description: 0G Compute Network guide for decentralized AI inference and fine-tuning.
  Covers chatbots, image generation, speech-to-text, SDK integration, CLI commands.
  Use this skill for any 0G compute, 0G AI, or decentralized GPU question.

Cross-platform compatibility

Universal format (works everywhere)

Only name and description in frontmatter. Standard markdown body. Relative paths. No platform-specific syntax.

Platform discovery paths

Codex-specific extensions

OpenAI Codex adds an optional openai.yaml file alongside SKILL.md for platform metadata (interface, policy, dependencies). SKILL.md itself stays cross-platform. See references/advanced-patterns.md for details.

Things that break cross-platform

Token estimation

Estimate: wc -w SKILL.md × 1.5 (prose) or × 1.7 (code-heavy files).

Budget allocation guide

Severity reference

Mode 4: Batch scan (scan-all)

Scan every skill in a directory at once. Useful for auditing your entire skill collection.

Process

1. List all subdirectories containing SKILL.md in the target path (default: ~/.claude/skills/).
2. Run Mode 3 (scan) on each skill. Output each skill's score as you complete it.
3. Output a summary table sorted by score ascending (worst first).

Report format

## Batch Skill Audit

| Skill | Score | HIGH | MEDIUM | LOW | Status |
|-------|-------|------|--------|-----|--------|
| seo-optimizer | 5/10 | 3 | 2 | 1 | NEEDS WORK |
| reprompter | 6/10 | 2 | 3 | 0 | NEEDS WORK |
| blogger | 7/10 | 1 | 1 | 2 | NEEDS WORK |
| humanizer-enhanced | 8/10 | 0 | 2 | 1 | PASS |

Total: 4 skills scanned
PASS: 1 | NEEDS WORK: 3

Top issues across all skills:
1. [HIGH] C2 reprompter: Body exceeds 5000 tokens (est. 8,200)
2. [HIGH] C3 seo-optimizer: Content repeated 4 times
3. [HIGH] C5 reprompter: Persona-based framing

PASS threshold: Score 7+ with zero HIGH issues.

Next step: "Start with the lowest-scoring skill. Run /skeall --improve <path> on it."

Mode 5: Health check (runtime audit)

Checks whether a skill actually works at runtime — beyond what static scan can catch. Run static scan (Mode 3) first and fix HIGH issues before health check.

Process

1. Run R1-R7 checks against the target skill.
2. For --healthcheck-all: cross-check all skills for duplicates (R2) and trigger collisions (R3).
3. Output severity-tagged report with sections: RUNTIME, DUPLICATES, TRIGGER COLLISIONS.
4. Labels: [FAIL] for HIGH issues (must fix), [WARN] for MEDIUM (runtime risk), [INFO] for LOW.

For detection algorithms, report format examples, and batch output format, see references/healthcheck.md.

Scoring methodology

Formula: Score = max(0, 10 - (HIGHs x 1.5) - min(MEDIUMs x 0.5, 3) - min(LOWs x 0.2, 1))

PASS threshold: Score 7+ AND zero HIGH issues. For detailed examples, see references/scoring.md.

Troubleshooting

References

For detailed checklists and examples, see:

• Anti-patterns with before/after examples
• Runtime health check algorithms and real examples
• Complete SKILL.md template
• Scoring methodology details
• Testing patterns and examples
• Advanced patterns: categories, freedom levels, distribution, MCP, workflows

Testing your skill: After create or improve, test trigger activation (3-5 keyword variants), functional output, and negative (unrelated queries stay quiet). See references/testing.md.

MCP integration: Use fully qualified tool names (mcp__server__tool_name). Document required MCP servers and provide fallbacks. See references/advanced-patterns.md.

Reprompter integration (optional): After --create interview, say "reprompter optimize" to score description variants and validate code examples. Works standalone if reprompter is not installed.