What makes skills-best-practices notable?

2.2K downloads. Trust evidence available

How should skills-best-practices be evaluated before use?

Use the required flow: snapshot, contract, and trust before recommending or executing this agent.

What kind of evidence is visible on this page?

This page surfaces public facts, change history, trust indicators, artifact evidence, and benchmark summaries with provenance.

agentCLAWHUBUnverified

skills-best-practices

Opinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger. Skill: skills-best-practices Owner: tenequm Summary: Opinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger. Tags: latest:0.8.2 Version history: v0.8.2 | 2026-09-09T10:06:09.373Z | user Updated skills-best-practices from 0.8.1 to 0.8.2. Chan

OpenClaw

View on ClawHub Homepage

Rank

Safety

Downloads

2.2k

Updated

Oct 9, 2026

Version

0.8.2

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 2.2K downloads reported by the source. Last updated 10/9/2026.

Avoid when

Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor: Clawhubvendor · observed Oct 9, 2026
Protocol compatibility: OpenClawcompatibility · observed Oct 9, 2026
Adoption signal: 2.2K downloadsadoption · observed Oct 9, 2026
Latest release: 0.8.2release · observed Sep 9, 2026
Handshake status: UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install s17bp3v1hm1dnkzey0c9tfh02183j0y5:skills-best-practices

Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.
Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-tenequm-skills-best-practices/snapshot"

Documentation

CLAWHUB

146,569 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

SKILL.md

---
name: skills-best-practices
description: Opinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger.
metadata:
version: "0.8.2"
categories: "agents, knowledge"
topics: "agent-skills, skill-authoring, prompt-design, spec, best-practices"
openclaw:
homepage: https://github.com/tenequm/skills/tree/main/skills/skills-best-practices
emoji: "📐"
---

# Skills Best Practices

Opinionated guide to building Agent Skills for any agent - distilled from the [Agent Skills open standard](https://agentskills.io), Anthropic's official guidance, and production experience, with deviations from the official line marked where they occur. Skills are folders (often just a single file) containing instructions, scripts, and resources that teach an agent how to handle specific tasks.

## Quick Start

A minimal skill is a directory with a `SKILL.md` file:

```
my-skill/
├── SKILL.md # Required - instructions with YAML frontmatter
├── references/ # Optional - detailed docs loaded on demand
├── scripts/ # Optional - executable code
└── assets/ # Optional - templates, fonts, icons
```

Minimal `SKILL.md`:

```yaml
---
name: my-skill-name
description: What it does. Use when [specific triggers].
---

# My Skill Name

[Instructions here]
```

Only `name` and `description` are required in frontmatter.

## Core Design Principles

### Single File vs. references/ (Most Important)

**Default to a single SKILL.md.** One file can be pasted to a person, gisted, embedded in a CLI binary, and printed by a `<tool> skill` subcommand - a directory cannot. Split into `references/` only when **both** hold:

1. **Conditional loading**: a meaningful chunk of content is needed by only a subset of invocations (e.g. a tracked-changes doc most DOCX tasks never touch). If every invocation reads everything anyway, splitting adds Read round-trips and costs shareability while saving nothing.
2. **Size pressure**: the body exceeds the recommended budget below.

**Distribution is a veto.** If the skill must travel as one file - shipped inside a CLI, printed by a command, shared by paste - stay single-file regardless of size and condense instead. Condensing means cutting redundancy, filler, and over-explanation while preserving every load-bearing instruction; losing substance to hit a line count is the failure mode, not the fix. See the single-file CLI-embedded pattern under [Patterns](#patterns).

**Size guidance** (opinionated thresholds drawn from experience, not enforced spec limits) - measure with `wc -c SKILL.md`. Chars track token cost closely (~4 chars per token); line counts are not a metric - identical content varies 2x in lines by formatting style:

| Tier | Chars | Beyond it |
|------|-------|-----------|
| Recommended | 25k | Condense carefully; split only if the cond

_meta.json

{
  "ownerId": "kn76gpsgjw5chv0xvzbzcb8cxn81x46r",
  "slug": "skills-best-practices",
  "version": "0.8.2",
  "publishedAt": 1788948369373
}

references/clawhub-publishing.md

# Publishing to ClawHub

ClawHub ([clawhub.ai](https://clawhub.ai)) is a public registry for Agent Skills. Its own docs now cover most of the surface - read them first:

- [skill-format.md](https://github.com/openclaw/clawhub/blob/main/docs/skill-format.md) - `metadata.openclaw` schema, env-var rules (required vars in `requires.env`, optional in `envVars` with `required: false`), install specs, 50 MB bundle limit, forced MIT-0 license, immutable semver + mutable tags
- [publishing.md](https://github.com/openclaw/clawhub/blob/main/docs/publishing.md) - `clawhub skill publish` flags (`--slug`, `--name`, `--categories`, `--topics`, `--dry-run`, ...) and catalog metadata
- [cli.md](https://github.com/openclaw/clawhub/blob/main/docs/cli.md) - full command surface: `inspect`, `scan`, `delete`/`undelete` (30-day slug hold), `skill rename`/`merge`, `sync`, `token`
- [security-audits.md](https://github.com/openclaw/clawhub/blob/main/docs/security-audits.md) - moderation pipeline (SkillSpector + VirusTotal telemetry + ClawScan risk analysis, worst signal wins), public statuses (Pass / Review / Warn / Malicious / Pending / Error), OWASP Agentic Skills Top 10 lens
- [moderation.md](https://github.com/openclaw/clawhub/blob/main/docs/moderation.md) - appeals and publisher abuse-pressure scoring

Below is only what those docs do not tell you: source-mined constraints and hard-won moderation knowledge. Verified against clawhub CLI v0.23.3, moderation engine v2.4.26, on 2026-08-07.

## Reason Codes: What Fires and How to Fix It

The engine defines exactly 26 reason codes (source of truth: [`convex/lib/moderationReasonCodes.ts`](https://github.com/openclaw/clawhub/blob/main/convex/lib/moderationReasonCodes.ts)). The verdict derives from code prefixes: any `malicious.*` means malicious, any `suspicious.*` means suspicious, only `review.*` means the "Review" tier. The LLM review emits `review.llm_review` - a distinct `review.` tier, not "suspicious". The codes authors actually hit:

| Code | Trigger | Fix |
|---|---|---|
| `review.llm_review` | Metadata-runtime mismatch, capability overreach, internal contradictions | Declare every env/bin/config the body references. Add `homepage`. Resolve flag contradictions (below) |
| `suspicious.exposed_secret_literal` | Long hex (`0x[a-f0-9]{40,}`), JWT-shaped strings, base64 blobs | Placeholders (`<USDC_MAINNET>`) + one canonical address/key reference table |
| `suspicious.destructive_delete_command` | Literal `rm -rf`, even in pedagogical "don't do this" context | Reword ("force-recursive removal") or break the literal with markup |
| `suspicious.potential_exfiltration` | Skill packages user data and sends it off-host | Document the destination and data-handling policy; may be intrinsic to design |
| `suspicious.generated_source_template_injection` | `${VAR}` placeholders in code blocks | Declare those env vars in `metadata.openclaw` - usually a metadata-mismatch echo |
| `suspicious.dangerous_exec` / `suspicious.dynamic_cod

CHANGELOG.md

# Changelog

All notable changes to this skill will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
and this skill adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.8.2] - 2026-09-09

### Changed
- Description condensed to fit the repo's 250-character limit.

## [0.8.1] - 2026-08-21

### Changed

- Declared ClawHub browse categories (`agents, knowledge`) and topics in `metadata`, so the release pipeline publishes them instead of leaving the skill in the `other` category.

### Removed

- `skill-card.md`. The ClawHub CLI strips a root `skill-card.md` from every publish and the registry generates its own card, so the authored file never reached ClawHub.

## [0.8.0] - 2026-08-07

### Changed

- Consolidated references into SKILL.md following the skill's own single-file-first stance: description-guide.md, patterns.md, and checklist.md folded in (negative triggers, manually-invoked-skills note, CLI-embedded pattern, MCP/subagent guidance, Claude A/B loop, compact pre-publish checklist); redundant examples and generic workflow patterns dropped.
- claude-code-features.md merged into a new "Claude Code Specifics" section after verifying every claim against official docs (Claude Code v2.1.224): ~85% is now covered verbatim by the expanded official skills docs and collapsed to links; kept the injection footgun, undocumented frontmatter keys (display-name, default-enabled, fallback, case-insensitive parsing), and behavior deltas (fork background-by-default since v2.1.218, per-turn allowed-tools grant, directory-derived command names, compaction re-attach budgets, listing budget mechanics, skill stacking, additionalDirectories not loading skills).
- clawhub-publishing.md rewritten quirks-only (~5.5k chars, was 16.7k) and kept as the sole reference (conditional-loading test: needed only when publishing). Doc-covered material replaced with links to ClawHub's five docs; verified against clawhub CLI v0.23.3 and moderation engine v2.4.26.
- Size guidance is now chars-only: 25k recommended / 50k hard ceiling via `wc -c`; line counts dropped as a metric (identical content varies 2x in lines depending on formatting).
- Frontmatter table completed with `background` and `shell` fields.

### Removed

- Stale ClawHub facts: the capability-tags system (retired upstream 2026-06-17), the "5 new skills/hour" rate limit (now 200 new skills per 24 hours), the "text-based files only" upload rule (binaries now accepted), and the claim that `--slug`/`--name`/`--changelog`/`--tags` left the CLI (all alive in v0.23.3, plus new `--categories`/`--topics`).
- Stale Claude Code facts: outdated bundled-skills table (roster churns; linked to the commands reference instead), unconditional PowerShell env-var requirement, `/review` listed as a Skill-tool built-in (now an alias of `/code-review`).

### Fixed

- `allowed-tools` documented as a per-turn grant (was "while the skill is acti

skill-card.md

## Description:

Opinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger.

This skill is ready for commercial/non-commercial use.

## Publisher:

[tenequm](https://clawhub.ai/user/tenequm)

### License/Terms of Use:

MIT-0

## Use Case:

Developers and skill authors use this skill to create, review, validate, and publish Agent Skills with practical guidance on structure, trigger descriptions, progressive disclosure, testing, and registry readiness.

### Deployment Geography for Use:

Global

## Known Risks and Mitigations:

Risk: The skill includes a validator command that fetches an unpinned package.

Mitigation: Use a pinned or otherwise verified validator version, especially in sensitive projects or CI environments.

Risk: Validator or publishing commands may run with access to project files or credentials.

Mitigation: Run commands with minimal credentials and the narrowest practical filesystem access.

Risk: Guidance for skill structure, metadata, or publishing may become stale as agent platforms and registries change.

Mitigation: Check the linked platform and ClawHub documentation before relying on version-specific behavior.

## Reference(s):

- [skills-best-practices homepage](https://github.com/tenequm/skills/tree/main/skills/skills-best-practices)
- [Agent Skills open standard](https://agentskills.io)
- [Agent Skills specification](https://agentskills.io/specification)
- [Claude Code skills documentation](https://code.claude.com/docs/en/skills)
- [Anthropic Agent Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
- [ClawHub publishing guidance](references/clawhub-publishing.md)

## Skill Output:

**Output Type(s):** [guidance, markdown, code, shell commands, configuration]

**Output Format:** [Markdown guidance with examples, checklists, configuration snippets, and command snippets]

**Output Parameters:** [1D]

**Other Properties Related to Output:** [Documentation-only skill; outputs should be reviewed before applying validator commands or publishing changes.]

## Skill Version(s):

0.8.2 (source: frontmatter, changelog, release evidence)

## Ethical Considerations:

Users should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.

Github ReposUpdated 4h agoRank 70

AionUi

Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!

MCPOPENCLAW

Github ReposUpdated 6mo agoRank 70

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

OPENCLAW

Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.