{"id":"6d9fa6cf-704e-48fc-a9d0-d33a00904bf4","entityType":"agent","slug":"clawhub-openlark-agent-skills","name":"Agent Skills","canonicalUrl":"https://www.xpersona.co/agent/clawhub-openlark-agent-skills","canonicalPath":"/agent/clawhub-openlark-agent-skills","generatedAt":"2026-10-09T17:18:11.711Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T13:05:30.064Z","emptyReason":null},"description":"Agent Skills standard reference guide. Covers SKILL.md specification format, progressive loading, skill discovery and activation, authoring best practices, quality evaluation, description optimization Skill: Agent Skills Owner: openlark Summary: Agent Skills standard reference guide. Covers SKILL.md specification format, progressive loading, skill discovery and activation, authoring best practices, quality evaluation, description optimization Tags: latest:1.0.1 Version history: v1.0.1 | 2026-06-26T04:57:23.117Z | user - Streamlined the reference section, replacing multiple detailed documents with concise files foc","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.6K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s1727wv2g20pc729snzcm4nf8183hy72:agent-skills","sourceUrl":"https://clawhub.ai/openlark/agent-skills","homepage":"https://clawhub.ai/openlark/skills/agent-skills","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/openlark/agent-skills","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/openlark/skills/agent-skills","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":68,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Agent Skills standard reference guide. Covers SKILL.md specification format, progressive loading, skill discovery and activation, authoring best practices, qual"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:05:30.064Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:05:30.064Z","emptyReason":null},"stars":null,"forks":null,"downloads":2595,"packageName":null,"latestVersion":"1.0.1","tractionLabel":"2.6K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:05:30.025Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T13:05:30.064Z","lastCrawledAt":"2026-10-09T13:05:30.025Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T13:05:30.025Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.1","createdAt":"2026-06-26T04:57:23.117Z","changelog":"- Streamlined the reference section, replacing multiple detailed documents with concise files focused on quick start, skill spec, authoring, and anti-patterns. - Added new references: quick-start guide, authoring best practices, anti-patterns, and official specification. - Removed legacy references: best practices, evaluation, integration, description optimization, and the skill card example. - Updated documentation for easier navigation using a reference file routing table. - Simplified usage and examples, focusing on clarity and actionable steps.","fileCount":9,"zipByteSize":10355},{"version":"1.0.0","createdAt":"2026-05-29T01:10:52.303Z","changelog":"- Initial release of the Agent Skills standard reference guide. - Documents SKILL.md specification format, directory structure conventions, and frontmatter requirements. - Explains progressive disclosure (three-tier loading mechanism) for agent skills. - Details skill discovery locations for both project and user scopes. - Includes integration, validation, and best practices references. - Lists 35+ supported agent products implementing the standard.","fileCount":9,"zipByteSize":12318}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1727wv2g20pc729snzcm4nf8183hy72:agent-skills","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","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":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-openlark-agent-skills/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-openlark-agent-skills/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-openlark-agent-skills/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-openlark-agent-skills/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-openlark-agent-skills/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-openlark-agent-skills/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T17:18:11.710Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-openlark-agent-skills/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-openlark-agent-skills/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-openlark-agent-skills/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-openlark-agent-skills/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T13:05:30.064Z","emptyReason":null},"readme":"Skill: Agent Skills\n\nOwner: openlark\n\nSummary: Agent Skills standard reference guide. Covers SKILL.md specification format, progressive loading, skill discovery and activation, authoring best practices, quality evaluation, description optimization\n\nTags: latest:1.0.1\n\nVersion history:\n\nv1.0.1 | 2026-06-26T04:57:23.117Z | user\n\n- Streamlined the reference section, replacing multiple detailed documents with concise files focused on quick start, skill spec, authoring, and anti-patterns.\n- Added new references: quick-start guide, authoring best practices, anti-patterns, and official specification.\n- Removed legacy references: best practices, evaluation, integration, description optimization, and the skill card example.\n- Updated documentation for easier navigation using a reference file routing table.\n- Simplified usage and examples, focusing on clarity and actionable steps.\n\nv1.0.0 | 2026-05-29T01:10:52.303Z | auto\n\n- Initial release of the Agent Skills standard reference guide.\n- Documents SKILL.md specification format, directory structure conventions, and frontmatter requirements.\n- Explains progressive disclosure (three-tier loading mechanism) for agent skills.\n- Details skill discovery locations for both project and user scopes.\n- Includes integration, validation, and best practices references.\n- Lists 35+ supported agent products implementing the standard.\n\nArchive index:\n\nArchive v1.0.1: 9 files, 10355 bytes\n\nFiles: references/anti-patterns.md (1710b), references/authoring.md (4468b), references/products.md (724b), references/quick-start.md (1057b), references/spec.md (4512b), references/using-scripts.md (1527b), skill-card.md (2179b), SKILL.md (1505b), _meta.json (131b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: agent-skills\ndescription: Agent Skills standard reference guide. Covers SKILL.md specification format, progressive loading, skill discovery and activation, authoring best practices, quality evaluation, description optimization, and more. \n---\n\n# Agent Skills Standard\n\n> A standardized way to equip AI Agents with new capabilities and domain expertise. Adopted by 35+ Agent products.\n\n## Use Cases\n\nUse when creating new skills, validating skill formats, optimizing existing skills, or learning about standardized skill system design.\n\n## Reference File Routing\n\n| Need | Read |\n|------|------|\n| Quick skill creation (5-step guide) | [quick-start.md](references/quick-start.md) |\n| SKILL.md format spec + Agent integration | [spec.md](references/spec.md) |\n| Authoring best practices + quality eval + description optimization | [authoring.md](references/authoring.md) |\n| Common anti-patterns and fixes | [anti-patterns.md](references/anti-patterns.md) |\n| Script binding and design | [using-scripts.md](references/using-scripts.md) |\n| Supported product list | [products.md](references/products.md) |\n\n## Minimal Example\n\n```markdown\n---\nname: pdf-processing\ndescription: Extract PDF text, fill forms, merge files. Use when handling PDFs.\n---\n\n## Workflow\n1. Extract: `python scripts/extract.py input.pdf`\n2. Fill: `python scripts/fill.py template.pdf data.json`\n\n## Gotchas\n- Scanned PDFs need OCR first — use `scripts/ocr.py`\n```\n\n## Validation\n\n```bash\nskills-ref validate ./my-skill\n```\n\nFile v1.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn75qrtb885pznwsjwsh18dvf1813bv0\",\n  \"slug\": \"agent-skills\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1782449843117\n}\n\nFile v1.0.1:references/anti-patterns.md\n\n# Skill Authoring Anti-Patterns\n\n## 1. Swiss-Army Skill\n\n**Symptom:** Description covers many unrelated features. **Consequence:** Triggers on almost every conversation, wasting tokens and interfering with decisions. **Fix:** One Skill does one thing. Split into multiple Skills if functionality is broad.\n\n## 2. Vague Description\n\n**Symptom:** \"Help with development\", \"Code assistant\" — generic phrases. **Consequence:** Extremely high false-trigger rate; fails to trigger when actually needed. **Fix:** Description must include \"what\" + \"when\". ❌ \"Help with development\" → ✅ \"Extract PDF text, fill forms. Use when handling PDFs.\"\n\n## 3. Over-Prescription\n\n**Symptom:** Every step locked down to exact commands and output wording. **Consequence:** Agent loses flexibility, gets stuck on minor deviations. **Fix:** Give direction, not scripts — list \"what\" (goals) not \"how\" (exact steps). Use \"consider\", \"may\" instead of \"must\".\n\n## 4. Missing Gotchas\n\n**Symptom:** Only documents happy paths, no known traps. **Consequence:** Agent repeats the same mistakes every new session. **Fix:** Add `## Gotchas` section. Format: problem → cause → solution. Update every time you hit one.\n\n## 5. Monolithic File\n\n**Symptom:** SKILL.md 2000+ lines. **Consequence:** Burns massive tokens on every activation, only 10% actually used. **Fix:** Split at >500 lines into `references/`; main file keeps skeleton + routing table.\n\n## 6. Untested Description\n\n**Symptom:** Ships without ever validating trigger accuracy. **Consequence:** Frequent false triggers or missed triggers in production. **Fix:** Test with 5–10 real prompts before shipping. Ensure relevant scenarios trigger, irrelevant ones don't.\n\nFile v1.0.1:references/authoring.md\n\n# Skill Authoring Guide\n\nComplete methodology for creating high-quality Skills: best practices → description optimization → quality evaluation.\n\n---\n\n## I. Best Practices\n\n### 1.1 Start from Real Experience\n\nExtract reusable patterns from actual tasks (successful steps, human corrections, I/O formats), or synthesize from project docs/runbooks/API specs. Only distill Skills after completing real tasks — never design from scratch.\n\n### 1.2 Refine Through Real Execution\n\nAfter initial draft, run with real tasks and collect full traces. Look at execution traces, not just output — if the Agent spends time on useless steps, the instructions are too vague or inapplicable.\n\n### 1.3 Context Efficiency\n\n**Add what the Agent lacks, remove what it knows.** For every piece of content ask: \"Would the Agent get this wrong without this instruction?\" No → delete.\n\n**Design cohesive units.** Too narrow → multiple Skills conflict; too broad → hard to activate precisely. Querying DB + formatting results is a reasonable unit; adding DB administration is too large.\n\n**Use progressive disclosure for large Skills.** SKILL.md <500 lines. Put detailed content in `references/`; tell the Agent in the main file **when** to load them.\n\n### 1.4 Calibration Control\n\n- **Match specificity to fragility**: When multiple approaches work, explain _why_; for fragile operations (e.g., DB migrations), enforce strict sequence\n- **Provide defaults, not menus**: Pick one default, briefly mention alternatives\n- **Prefer process over declaration**: Teach the Agent **how to approach** problems, not what to produce for specific instances\n\n### 1.5 Effective Instruction Patterns\n\n- **Gotchas**: Most valuable — environment-specific traps the Agent won't know. Update every time you step on one\n- **Output templates**: More reliable than descriptive language; short templates in SKILL.md, long ones in `assets/`\n- **Checklists**: Checkbox format prevents omissions\n- **Verify loop**: Do → run validator → fix → repeat\n- **Plan-verify-execute**: For batch/destructive operations, create intermediate plan first\n- **Package scripts**: Agent repeatedly writes same logic → write a tested script once in `scripts/`\n\n---\n\n## II. Description Optimization\n\n### 2.1 Trigger Mechanism\n\nAgent loads all `name` + `description` at startup (Tier 1). Match → read full SKILL.md. Complex domain tasks are where description delivers value.\n\n### 2.2 Writing Tips\n\n- Imperative tone: \"Use this skill when...\"\n- Focus on user intent, not internal mechanics\n- Be pushy — explicitly list applicable scenarios\n- ≤1024 characters\n\n### 2.3 Trigger Eval\n\n~20 queries (8–10 should trigger + 8–10 should not). Most valuable negatives are **near-misses**: share keywords but need something different. Run each query 3×; should-trigger ≥0.5 pass, should-not <0.5 pass. 60% train + 40% validation to prevent overfitting.\n\n### 2.4 Optimization Loop\n\n1. Evaluate current description → 2. Modify using only train failures → 3. Too narrow: broaden; too broad: add constraints → 4. Avoid adding specific keywords from failed queries → 5. If stuck, try structurally different descriptions → 6. Select iteration with **highest validation pass rate**. Usually 5 rounds suffice; final validation with 5–10 fresh queries.\n\n---\n\n## III. Quality Evaluation\n\n### 3.1 Test Case Design\n\nStart with 2–3 cases. Vary prompts (formal/casual/typos/detail levels), cover edge cases. Each case: prompt, expected output, assertion list.\n\n### 3.2 Running Evals\n\nWith Skill + without Skill (baseline). Record outputs, timing, tokens.\n\n### 3.3 Assertions\n\nGood: programmatically verifiable, concretely observable, countable. Weak: too vague, too brittle.\n\n### 3.4 Scoring\n\nEach assertion PASS/FAIL + evidence. Blind comparison: LLM judge unaware of source version. Aggregate: `pass_rate(mean)` with/without + `delta`.\n\n### 3.5 Pattern Analysis\n\nRemove uninformative assertions → investigate dual failures → study Skill value → add examples for inconsistency → check outliers.\n\n### 3.6 Iteration Loop\n\nEval signals → LLM improvement → rerun → score → human review → repeat. Stop when: satisfied / feedback consistently empty / no meaningful improvement.\n\n---\n\n## Cross-References\n\n- [spec.md](spec.md) — Format spec | [quick-start.md](quick-start.md) — Quick start | [anti-patterns.md](anti-patterns.md) — Anti-patterns | [using-scripts.md](using-scripts.md) — Scripts\n\nFile v1.0.1:references/products.md\n\n# Products Supporting Agent Skills\n\nAdopted by 35+ products across terminal agents, IDEs, cloud platforms, and frameworks.\n\n| Product | Type |\n|---------|------|\n| Claude Code | Terminal/IDE |\n| GitHub Copilot | IDE |\n| Cursor | IDE |\n| OpenAI Codex | Terminal/IDE |\n| Pi | Terminal |\n| Gemini CLI | Terminal |\n| VS Code | IDE |\n| OpenCode | Terminal/IDE |\n| Roo Code | IDE |\n| Goose | Terminal |\n| Spring AI | Framework |\n| Letta | Platform |\n| fast-agent | Framework |\n| Databricks Genie Code | Platform |\n| Laravel Boost | Framework |\n\n## Universal Compatibility Paths\n\n- `~/.agents/skills/` — User-level\n- `.agents/skills/` — Project-level\n\n> Full list: [Agent Skills Official Documentation](https://agentskills.io)\n\nFile v1.0.1:references/quick-start.md\n\n# 5 Steps to Create a Skill\n\n## 1. Create Directory\n\n```bash\nmkdir -p my-skill/references\n```\n\nDirectory name = skill name, kebab-case. Prefer verb-noun phrases (`pdf-processing`, `weather-check`).\n\n## 2. Write SKILL.md\n\n```markdown\n---\nname: my-skill\ndescription: What it does + when to trigger. Use when...\n---\n\n## Workflow\n1. First step\n2. Second step\n\n## Gotchas\n- Common pitfalls\n```\n\n`description` determines trigger accuracy — clearly state \"what\" and \"when\".\n\n## 3. Split Large Files\n\nBody > 500 lines → split to `references/`, keep skeleton + routing table in main file:\n\n```markdown\n| Need | Read |\n|------|------|\n| Detailed API reference | [references/api.md](references/api.md) |\n```\n\n## 4. Add Resources (Optional)\n\n- `scripts/` — executable scripts the Agent can call directly\n- `assets/` — templates, config files\n\nScripts should be self-contained with clear I/O interfaces.\n\n## 5. Validate\n\n```bash\nskills-ref validate ./my-skill\n```\n\n---\n\nNext: [spec.md](spec.md) — Format spec | [authoring.md](authoring.md) — Authoring guide\n\nFile v1.0.1:references/spec.md\n\n# Agent Skills Specification Reference\n\n> SKILL.md format specification, integration flow, and runtime behavior reference.\n\n---\n\n## 1. Format Specification\n\n### 1.1 Directory Structure\n\n```\nskill-name/\n├── SKILL.md          # Required: YAML frontmatter + Markdown instructions\n├── scripts/          # Optional: executable scripts\n├── references/       # Optional: on-demand reference docs\n├── assets/           # Optional: templates, resource files\n```\n\n### 1.2 SKILL.md — Frontmatter\n\nFile begins with YAML frontmatter wrapped in `---`:\n\n| Field | Required | Constraints |\n|-------|:--------:|-------------|\n| `name` | ✅ | 1–64 chars, lowercase letters/digits/hyphens, no leading/trailing hyphens, no consecutive hyphens, must match directory name |\n| `description` | ✅ | 1–1024 chars, describes functionality and trigger scenarios |\n| `license` | — | License name or reference |\n| `compatibility` | — | ≤500 chars, environment requirements |\n| `metadata` | — | Arbitrary key-value pairs |\n| `allowed-tools` | — | Space-separated list of pre-approved tools (experimental) |\n\n### 1.3 Body Content\n\nMarkdown body after frontmatter, no format restrictions. Recommended: step-by-step instructions, input/output examples, common edge cases. Split to `references/` when body exceeds 500 lines; keep overview + routing table in main file.\n\n---\n\n## 2. Discovery\n\n### 2.1 Scan Locations\n\nAgent scans the following paths at startup, collecting subdirectories containing `SKILL.md`:\n\n| Scope | Path | Description |\n|-------|------|-------------|\n| Project-level | `<project>/.<client>/skills/` | Client-native |\n| Project-level | `<project>/.agents/skills/` | Cross-client interop |\n| User-level | `~/.<client>/skills/` | Client-native |\n| User-level | `~/.agents/skills/` | Cross-client interop |\n\n### 2.2 Scan Rules\n\n- Recursive scan, max depth 4–6 levels; skip `.git/`, `node_modules/`\n- Name conflicts: project-level overrides user-level\n- Untrusted sources may be skipped or gated\n- Cloud/sandbox environments inject via Git clone, URL install, or Web UI\n\n---\n\n## 3. Parsing\n\nExtract YAML between `---` → get `name`, `description`. Error tolerance: retry with quoted values → retry with block scalar → mark as unparseable.\n\nLenient validation: `name` mismatch/too long → warn but load; `description` missing → skip; YAML completely unparseable → skip.\n\nStorage: `name`, `description`, `location` (absolute path), `body` (store or read on demand), `baseDir`.\n\n---\n\n## 4. Disclosure (Tier 1)\n\nAgent injects catalog into system prompt at startup:\n\n```xml\n<available_skills>\n  <skill><name>pdf</name>\n  <description>Extract PDF text, fill forms, merge files.</description>\n  <location>/path/to/pdf/SKILL.md</location></skill>\n</available_skills>\n```\n\nAccompanying instruction: `When a task matches, use file-read tool to load SKILL.md` or `call activate_skill(name)`. Disabled/unauthorized skills are completely hidden; no catalog shown when zero skills.\n\n---\n\n## 5. Activation (Tier 2)\n\n### 5.1 Progressive Loading\n\n| Tier | Content | When | Tokens |\n|------|---------|------|--------|\n| 1 | name + description | Session start | ~50–100/skill |\n| 2 | Full SKILL.md body | On activation | <5000 (recommended) |\n| 3 | scripts/references/assets | On demand | Varies |\n\n### 5.2 Activation Methods\n\n- **File read**: Model uses standard read tool on `location` path (simplest)\n- **Dedicated Tool**: `activate_skill(name)`, name constrained to enum to prevent hallucination; can control returning frontmatter/body, wrap in `<skill_content>` tags, list resources\n- **User explicit**: `/skill-name` syntax, harness intercepts and injects; autocomplete recommended\n\n### 5.3 Structured Wrapping (Recommended)\n\n```xml\n<skill_content name=\"pdf\">\n  <!-- body content -->\n  <skill_resources>\n    <file>scripts/extract.py</file>\n  </skill_resources>\n</skill_content>\n```\n\nResource list is not pre-loaded; agent references on demand. Cap large directories. Allowlist restricts to skill directory.\n\n---\n\n## 6. Context Management\n\n- **Compaction**: Mark skill content as non-compactable, preserve `<skill_content>` tags; or replace with short reference for next reload (leverage prompt cache)\n- **Caching**: Static catalog in system prompt prefix for cache; dynamic conversation at suffix\n- **Command exposure**: `/skill-name args`\n- **Shared path**: `.agents/skills/` is the most widely adopted cross-product path\n\n---\n\n## Validation\n\n```bash\nskills-ref validate ./my-skill\n```\n\nFile v1.0.1:references/using-scripts.md\n\n# Binding Scripts in Skills\n\n## One-Shot Commands\n\n| Tool | Example | Notes |\n|------|---------|-------|\n| `uvx` | `uvx ruff@0.8.0 check .` | Python isolated env |\n| `npx` | `npx eslint@9 --fix .` | Bundled with Node.js |\n| `bunx` | `bunx eslint@9 --fix .` | Bun equivalent of npx |\n| `deno run` | `deno run npm:eslint@9 -- --fix .` | Requires permission flags |\n| `go run` | `go run golang.org/x/tools/cmd/goimports@v0.28.0 .` | Bundled with Go |\n\nLock versions, declare prerequisites, move complex commands to `scripts/`.\n\n## Referencing Scripts\n\nRelative paths from skill root directory:\n\n```markdown\n## Scripts\n- `scripts/validate.sh` — Validates config\n- `scripts/process.py` — Processes data\n\n1. `bash scripts/validate.sh \"$INPUT\"`\n2. `python3 scripts/process.py --input results.json`\n```\n\n## Self-Contained Scripts\n\n- **Python (PEP 723):** `# /// script` + `# dependencies = [...]` + `# ///` → `uv run`\n- **Deno:** `import from \"npm:pkg@ver\"` → `deno run`\n- **Bun:** `import from \"pkg@ver\"` → `bun run`\n- **Ruby:** `bundler/inline`\n\n## Agent-Friendly Design\n\n- Avoid interactive prompts; use CLI flags/env vars/stdin\n- `--help` provides usage (primary way Agent learns interface)\n- Structured output (JSON/CSV > aligned text); data → stdout, diagnostics → stderr\n- Idempotent: \"create if not exists\" > \"create then error on duplicate\"\n- Destructive ops: add `--dry-run` and `--confirm`\n- Meaningful exit codes, documented in `--help`\n- Large output: default to summary/limit, support `--offset` pagination\n\nFile v1.0.1:skill-card.md\n\n## Description:\n\nAgent Skills standard reference guide covering SKILL.md specification format, progressive loading, skill discovery and activation, authoring best practices, quality evaluation, description optimization, and more.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[openlark](https://clawhub.ai/user/openlark)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent-skill authors use this skill to create, validate, optimize, and evaluate Agent Skills using the standard SKILL.md format and supporting reference files.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Script examples may lead an agent to run package-manager commands or file-changing commands in a user's environment.\n\nMitigation: Use pinned versions, review dependencies, run dry runs when available, and require explicit approval before commands download packages or modify files.\n\nRisk: Poorly scoped or untested skill descriptions can cause false activation or missed activation in downstream agents.\n\nMitigation: Evaluate trigger behavior with representative positive and near-miss prompts before release.\n\n## Reference(s):\n\n- [Quick Start](references/quick-start.md)\n- [Agent Skills Specification Reference](references/spec.md)\n- [Skill Authoring Guide](references/authoring.md)\n- [Skill Authoring Anti-Patterns](references/anti-patterns.md)\n- [Binding Scripts in Skills](references/using-scripts.md)\n- [Products Supporting Agent Skills](references/products.md)\n- [Agent Skills Official Documentation](https://agentskills.io)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Markdown, Code, Shell commands, Configuration]\n\n**Output Format:** [Markdown guidance with inline code blocks and shell command examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [None]\n\n## Skill Version(s):\n\n1.0.1 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers 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.\n\nArchive v1.0.0: 9 files, 12318 bytes\n\nFiles: references/best-practices.md (3108b), references/eval-skills.md (2778b), references/integrate.md (2644b), references/optimize-desc.md (2633b), references/products.md (1559b), references/using-scripts.md (2442b), skill-card.md (2296b), SKILL.md (4361b), _meta.json (131b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: agent-skills\ndescription: Agent Skills standard reference guide. Covers SKILL.md specification format, progressive disclosure mechanism, skill discovery and activation, frontmatter metadata fields, directory structure conventions. \n---\n\n# Agent Skills\n\n> A standardized way to give AI agents new capabilities and expertise.\n> 35+ agent products support it: Claude Code, GitHub Copilot, Cursor, Pi, Codex, Gemini CLI, and more.\n\n## Use Cases \n\nUse when creating new skills, validating skill formats, or understanding the standardized skill system design.\n\n## Directory Structure\n\n```\nskill-name/\n├── SKILL.md          # Required: YAML frontmatter + Markdown instructions\n├── scripts/          # Optional: executable scripts\n├── references/       # Optional: on-demand reference docs\n├── assets/           # Optional: templates, resource files\n└── ...               # Any additional files\n```\n\n## SKILL.md Format\n\n### Frontmatter\n\n| Field | Required | Constraints |\n|------|----------|-------------|\n| `name` | ✅ | 1-64 chars, lowercase/numbers/hyphens, no leading/trailing hyphens, no consecutive hyphens, must match directory name |\n| `description` | ✅ | 1-1024 chars, describe what it does and when to use |\n| `license` | — | License name or reference |\n| `compatibility` | — | ≤500 chars, environment requirements |\n| `metadata` | — | Arbitrary key-value pairs |\n| `allowed-tools` | — | Space-separated pre-approved tool list (experimental) |\n\n### Minimal Example\n\n```markdown\n---\nname: pdf-processing\ndescription: Extract PDF text, fill forms, merge files. Use when handling PDFs.\n---\n```\n\n### Body Content\n\nMarkdown body after frontmatter, no format restrictions. Recommended: step-by-step instructions, input/output examples, common edge cases. Split to `references/` if over 500 lines.\n\n## Progressive Disclosure (Three Tiers)\n\n| Tier | What's Loaded | When | Token Cost |\n|------|--------------|------|------------|\n| 1. Catalog | name + description | Session start | ~50-100 per skill |\n| 2. Instructions | Full SKILL.md body | When skill is activated | <5000 tokens (recommended) |\n| 3. Resources | scripts/references/assets | When referenced by instructions | Varies |\n\n## Skill Discovery\n\n### Scan Locations\n\n| Scope | Path | Purpose |\n|------|------|---------|\n| Project | `<project>/.<client>/skills/` | Client-native location |\n| Project | `<project>/.agents/skills/` | Cross-client interoperability |\n| User | `~/.<client>/skills/` | Client-native location |\n| User | `~/.agents/skills/` | Cross-client interoperability |\n\nScan subdirectories containing `SKILL.md`. Skip `.git/` and `node_modules/`. Name collisions: project-level overrides user-level.\n\n## Integrating into an Agent\n\nSee [references/integrate.md](references/integrate.md) for the full integration guide, covering:\n- Skill discovery (local/cloud/sandbox)\n- SKILL.md parsing (YAML degradation, lenient validation)\n- Model disclosure (XML/JSON catalog, behavior instructions)\n- Activation mechanisms (file-read activation / dedicated tool activation / user explicit activation)\n- Context management (compaction protection, caching strategies)\n\n## Supported Agent Products\n\n35+ products implement Agent Skills: Claude Code, GitHub Copilot, Cursor, OpenAI Codex, Pi, Gemini CLI, Junie, OpenCode, OpenHands, Goose, Roo Code, VS Code, Mux, Amp, Spring AI, Databricks Genie Code, Qodo, Laravel Boost, and more. See [references/products.md](references/products.md).\n\n## Validation\n\n```bash\nskills-ref validate ./my-skill\n```\n\n## References\n\n- **[integrate](references/integrate.md)** — Complete guide to integrating Skills support into agents\n- **[best-practices](references/best-practices.md)** — Skill creation best practices: real expertise, context management, control granularity, effective instruction patterns\n- **[eval-skills](references/eval-skills.md)** — Skill quality evaluation: test cases, assertions, grading, iteration loops\n- **[optimize-desc](references/optimize-desc.md)** — Optimizing the description field: trigger testing, train/validation splits, optimization loops\n- **[using-scripts](references/using-scripts.md)** — Bundling scripts in skills: one-off commands, self-contained scripts, agent-friendly design\n- **[products](references/products.md)** — List of 35+ products supporting Agent Skills\n\nFile v1.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn75qrtb885pznwsjwsh18dvf1813bv0\",\n  \"slug\": \"agent-skills\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1780017052303\n}\n\nFile v1.0.0:references/best-practices.md\n\n# Skill Creation Best Practices\n\n## Start from Real Expertise\n\nMost effective skills are grounded in real domain experience, not generated from LLM general knowledge.\n\n**Extract from hands-on tasks**: Complete real tasks, then extract reusable patterns → successful steps, manual corrections, I/O formats, project-specific context.\n\n**Synthesize from project artifacts**: Feed internal docs/runbooks/API specs/code reviews to an LLM to synthesize skills, not generic references.\n\n## Refine with Real Execution\n\nRun the first draft against real tasks, collect all results (not just failures). Ask: what false-triggered? What was missed? What can be cut?\n\nCheck execution traces: agent wastes time on unproductive steps → instructions too vague, don't apply, or too many options without a default.\n\n## Spending Context Wisely\n\n### Add what the agent lacks, omit what it knows\n\nFor each piece: \"Would the agent get this wrong without this instruction?\" No → cut it. Agents already know what PDFs are, how HTTP works.\n\n### Design coherent units\n\nToo narrow → multiple skills load for one task (instruction conflicts). Too broad → hard to activate precisely. Example: query database + format results = one unit; adding database administration = too much.\n\n### Aim for moderate detail\n\nOverly comprehensive skills hurt more than help. Concise stepwise guidance + working example > exhaustive documentation.\n\n### Structure large skills with progressive disclosure\n\nSKILL.md <500 lines/5000 tokens. Detailed reference in references/, tell agent *when* to load: \"Read references/api-errors.md if API returns non-200 status.\"\n\n## Calibrating Control\n\n### Match specificity to fragility\n\n- **Give freedom**: when multiple approaches work, explain *why* rather than rigid directives\n- **Be prescriptive**: fragile operations require exact sequence (`python scripts/migrate.py --verify --backup`, do not modify)\n\n### Provide defaults, not menus\n\nPick one default when multiple tools work. Mention alternatives briefly, don't list as equal options.\n\n### Favor procedures over declarations\n\nTeach the agent *how to approach* a class of problems, not *what to produce* for a specific instance. The approach should generalize.\n\n## Effective Instruction Patterns\n\n### Gotchas\n\nThe highest-value content — environment-specific facts the agent will get wrong without being told. After agent makes a mistake → add to gotchas.\n\n### Output templates\n\nConcrete templates outperform descriptive language (agents pattern-match better against concrete structures). Short templates in SKILL.md, long ones in assets/.\n\n### Checklists\n\nMulti-step workflows with checkboxes track progress and prevent skipped steps.\n\n### Validation loops\n\nDo work → run validator → fix issues → repeat until pass.\n\n### Plan-validate-execute\n\nFor batch/destructive operations: create structured intermediate plan, validate against source of truth, then execute. The validation script is the key ingredient.\n\n### Bundle reusable scripts\n\nIf agent independently rewrites the same logic each run → write a tested script once in scripts/.\n\nFile v1.0.0:references/eval-skills.md\n\n# Skill Quality Evaluation\n\nUse structured evals to validate skill quality.\n\n## Test Case Design\n\n```json\n{\n  \"id\": 1,\n  \"prompt\": \"what a real user would say\",\n  \"expected_output\": \"what success looks like\",\n  \"files\": [\"evals/files/input.csv\"],\n  \"assertions\": [\"verifiable assertion 1\", \"assertion 2\"]\n}\n```\n\n- Start with 2-3 test cases, don't over-invest\n- Vary prompts: formal/casual/typos/different detail levels\n- Cover edge cases: malformed input, ambiguous instructions\n- Use realistic context: file paths, column names, etc.\n\n## Running Evals\n\nRun each test case twice: **with skill** + **without skill** (baseline). Workspace structure:\n\n```\nworkspace/iteration-1/\n├── eval-01/with_skill/{outputs,timing,grading}\n├── eval-01/without_skill/{outputs,timing,grading}\n└── benchmark.json\n```\n\nRecord `timing.json`: `{\"total_tokens\": 84852, \"duration_ms\": 23332}`\n\n## Assertions\n\nGood: programmatically verifiable (\"output file is valid JSON\"), specific and observable (\"chart has labeled axes\"), countable (\"≥3 recommendations\").\n\nWeak: too vague (\"output is good\"), too brittle (\"must use exact phrase X\").\n\n## Grading\n\nEach assertion PASS/FAIL + concrete evidence (quote/reference output):\n\n```json\n{\"assertion_results\": [{\"text\": \"...\", \"passed\": true, \"evidence\": \"Found chart.png\"}],\n \"summary\": {\"passed\": 3, \"failed\": 1, \"total\": 4, \"pass_rate\": 0.75}}\n```\n\nGrading principles: PASS needs concrete evidence, no benefit of doubt. Also review assertions themselves for reasonableness.\n\n**Blind comparison** (comparing versions): LLM judge scores without knowing which version is which.\n\n## Aggregation\n\n```json\n{\"run_summary\": {\n  \"with_skill\": {\"pass_rate\": {\"mean\": 0.83}},\n  \"without_skill\": {\"pass_rate\": {\"mean\": 0.33}},\n  \"delta\": {\"pass_rate\": 0.50}\n}}\n```\n\nDelta tells you the skill's cost (time/tokens) vs. benefit (pass rate improvement).\n\n## Pattern Analysis\n\n- Remove assertions both sides pass (no signal)\n- Investigate both-side failures (broken assertion or too-hard case)\n- Study skill-passes / no-skill-fails (where skill adds value)\n- Inconsistent results → ambiguous instructions, add examples or specifics\n- Check timing/token outliers\n\n## Human Review\n\nThings assertions miss: writing style, visual design, \"does it feel right\". Record specific actionable feedback.\n\n## Iteration Loop\n\n1. Feed all eval signals + current SKILL.md to LLM for improvement proposals\n2. Review and apply changes\n3. Rerun all test cases in iteration-N+1/\n4. Grade and aggregate\n5. Human review. Repeat.\n\nStop: satisfied / feedback consistently empty / no meaningful improvement.\n\nGuidance for LLM: generalize feedback (not narrow patches), keep lean (fewer better instructions > exhaustive rules), explain why, bundle repeated work into scripts.\n\nFile v1.0.0:references/integrate.md\n\n# Agent Skills Integration Guide\n\n## Progressive Loading\n\nTier 1: name+desc (session start, ~50-100t) → Tier 2: full body (on activation, <5000t) → Tier 3: refs/scripts (on demand)\n\n## Step 1: Discovery\n\n### Scan Paths\n\nProject + user level, client directories + `.agents/skills/` (cross-client), optionally `.claude/skills/` for compatibility. Find `SKILL.md` in subdirectories, skip `.git/`/`node_modules/`, cap at 4-6 levels deep.\n\nName collisions: project overrides user. Untrusted repos: consider skipping or setting a trust gate. Cloud/sandbox agents need external provisioning (clone repo / URL install / Web UI).\n\n## Step 2: Parsing\n\nExtract YAML between `---` → name, description. Fault-tolerant: wrap unquoted colon values in quotes or retry with block scalars.\n\nLenient validation: name mismatch dir/too long → warn but load; description missing → skip; YAML unparseable → skip.\n\nStore: name, description, location (absolute path), body (store or read on demand), base dir (derived from location).\n\n## Step 3: Disclosure (Tier 1)\n\nCatalog format (in system prompt or tool description):\n```xml\n<available_skills>\n  <skill><name>pdf</name><description>Extract PDF text...</description>\n  <location>/path/to/SKILL.md</location></skill>\n</available_skills>\n```\n\nBehavior instruction: \"When a task matches, use file-read tool to load SKILL.md\" or \"call activate_skill(name) tool\". Hide disabled/permission-denied skills. No skills → no catalog, no tool registration.\n\n## Step 4: Activation (Tier 2)\n\n**File-read activation**: model reads path with standard read tool (simplest).\n\n**Dedicated tool activation**: `activate_skill(name)`, constrain name as enum to prevent hallucination. Can: control frontmatter return, wrap `<skill_content>` tags, list resources/, permission checks.\n\n**User explicit activation**: `/skill-name` syntax, harness intercepts and injects. Suggest autocomplete.\n\n**Return content**: full file or body-only (strip frontmatter).\n\n**Structured wrapping** (recommended):\n```xml\n<skill_content name=\"pdf\"><skill_resources>\n  <file>scripts/extract.py</file></skill_resources></skill_content>\n```\n\nList resources without eager reading. Allowlist skill directory to avoid permission prompts.\n\n## Step 5: Context Management\n\n- During compaction: mark skill content as non-compressible, preserve `<skill_content>` tags; or replace with short ref and reload on next activation (leverage prompt cache)\n- Static catalog in system prompt prefix for caching; dynamic conversation in suffix\n- Expose skills as commands: `/skill-name args`\n- `.agents/skills/` is the most widely adopted cross-product sharing path\n\nFile v1.0.0:references/optimize-desc.md\n\n# Optimizing Skill Descriptions\n\nThe description is the sole mechanism for skill triggering. Under-specified → doesn't trigger; over-broad → false triggers.\n\n## How Triggering Works\n\nAgents load name + description for all skills at startup (Tier 1). User task matches description → full SKILL.md read. Simple requests may not need a skill; complex domain tasks are where descriptions make the difference.\n\n## Writing Effective Descriptions\n\n- **Use imperative phrasing**: \"Use this skill when...\" not \"This skill does...\"\n- **Focus on user intent**: describe what the user wants to achieve, not skill internals\n- **Err on the side of pushy**: explicitly list applicable contexts, including when the user doesn't name the domain\n- **Keep concise**: a few sentences to a short paragraph, ≤1024 chars\n\n## Trigger Eval Queries\n\n~20 queries: 8-10 should-trigger + 8-10 should-not-trigger.\n\n### Should-trigger\n\nVary across: phrasing, explicitness, detail, complexity. Most valuable are queries where the skill helps but the connection isn't obvious.\n\n### Should-not-trigger\n\nMost valuable negatives are near-misses: share keywords but need something different. Example for CSV skill: \"update Excel budget formulas\" (shares spreadsheet concept but needs Excel editing) or \"write Python script to upload CSV to database\" (involves CSV but task is ETL).\n\n## Testing\n\nRun each query 3 times, compute trigger rate. Should-trigger passes if rate ≥0.5; should-not passes if <0.5.\n\n## Avoiding Overfitting\n\n60% train (guide improvements) + 40% validation (check generalization). Keep both sets proportionally mixed.\n\n## Optimization Loop\n\n1. Evaluate on both train + validation\n2. Identify train failures only; keep validation blind\n3. Revise: too narrow → broaden; too broad → add specificity\n4. Avoid adding specific keywords from failed queries (overfitting); find the general category\n5. If stuck, try structurally different descriptions rather than incremental tweaks\n6. Repeat until train passes or no improvement\n7. Select the iteration with highest validation pass rate (not necessarily the last)\n\n~5 iterations usually suffice. No improvement → issue may be with queries, not description. Validate generalization with 5-10 fresh queries.\n\n## Example\n\n```yaml\n# Before\ndescription: Process CSV files.\n\n# After\ndescription: >\n  Analyze CSV and tabular data — compute summary statistics,\n  add derived columns, generate charts, and clean messy data.\n  Use when the user has a CSV, TSV, or Excel file and wants to\n  explore, transform, or visualize the data, even if they don't\n  explicitly mention \"CSV\" or \"analysis.\"\n```\n\nFile v1.0.0:references/products.md\n\n# Products Supporting Agent Skills\n\n## Coding Agents\n\n| Product | Type | Skills Docs |\n|---------|------|-------------|\n| Claude Code | Terminal/IDE | code.claude.com/docs/en/skills |\n| GitHub Copilot | IDE | docs.github.com/en/copilot/concepts/agents/about-agent-skills |\n| Cursor | IDE | cursor.com/docs/context/skills |\n| OpenAI Codex | Terminal/IDE | developers.openai.com/codex/skills |\n| Pi | Terminal | github.com/badlogic/pi-mono |\n| Gemini CLI | Terminal | geminicli.com/docs/cli/skills |\n| Junie | IDE (IntelliJ) | junie.jetbrains.com/docs/agent-skills |\n| OpenCode | Terminal/IDE | opencode.ai/docs/skills |\n| OpenHands | Cloud | docs.openhands.dev/overview/skills |\n| Roo Code | IDE | docs.roocode.com/features/skills |\n| Goose | Terminal | block.github.io/goose |\n| VS Code | IDE | code.visualstudio.com/docs/copilot/customization/agent-skills |\n| Mux | Cloud/Desktop | mux.coder.com/agent-skills |\n| Amp | Terminal | ampcode.com/manual#agent-skills |\n\n## Platforms & Frameworks\n\nSpring AI, Databricks Genie Code, Laravel Boost, Letta, Factory, Ona, Workshop, TRAE, fast-agent, nanobot, bub, Agentman, VT Code, Snowflake Cortex Code, Google AI Edge Gallery, Qodo, Command Code, Kiro, Emdash, Piebald, Mistral AI Vibe, Firebender, and more.\n\n## Universal Compatibility Paths\n\nMost widely adopted cross-product skill sharing paths:\n\n- `~/.agents/skills/` — user-level\n- `.agents/skills/` — project-level\n\nSome implementations also scan `.claude/skills/`, `.codex/skills/` etc. Lenient validation ensures cross-product skill interchangeability.\n\nFile v1.0.0:references/using-scripts.md\n\n# Bundling Scripts in Skills\n\n## One-off Commands\n\nReference existing tools directly without a scripts/ directory:\n\n| Tool | Example | Notes |\n|------|---------|-------|\n| `uvx` | `uvx ruff@0.8.0 check .` | Python, isolated env, needs uv |\n| `npx` | `npx eslint@9 --fix .` | Ships with Node.js |\n| `bunx` | `bunx eslint@9 --fix .` | Bun's npx equivalent |\n| `deno run` | `deno run npm:eslint@9 -- --fix .` | Needs permission flags |\n| `go run` | `go run golang.org/x/tools/cmd/goimports@v0.28.0 .` | Ships with Go |\n\n**Tips**: pin versions, state prerequisites, move complex commands into scripts/.\n\n## Referencing Scripts\n\nUse relative paths from skill directory root:\n\n```markdown\n## Available scripts\n- **`scripts/validate.sh`** — Validates config files\n- **`scripts/process.py`** — Processes input data\n\n## Workflow\n1. ```bash bash scripts/validate.sh \"$INPUT_FILE\"```\n2. ```bash python3 scripts/process.py --input results.json```\n```\n\n## Self-contained Scripts\n\nDeclare dependencies inline, no separate manifest needed:\n\n**Python (PEP 723)**: `# /// script` block with dependencies. Run: `uv run scripts/extract.py`\n\n**Deno**: `import * as lib from \"npm:pkg@1.0.0\";`. Run: `deno run scripts/extract.ts`\n\n**Bun**: `import * as lib from \"pkg@1.0.0\";`. Run: `bun run scripts/extract.ts`\n\n**Ruby**: Use `bundler/inline` to declare gems.\n\n## Agent-Friendly Script Design\n\n- **Avoid interactive prompts**: agents run in non-interactive shells. All input via CLI flags/env/stdin. If it hangs → must have clear error with usage.\n- **`--help` provides usage**: primary way agents learn your script's interface. Include brief description, flags, examples.\n- **Write helpful errors**: \"Error: --format must be one of: json, csv, table. Received: xml.\"\n- **Use structured output**: JSON/CSV > aligned text. Data → stdout, diagnostics → stderr.\n- **Idempotency**: agents may retry. \"Create if not exists\" > \"create and error on duplicate\".\n- **Input constraints**: reject ambiguous input with clear guidance, use enums and closed sets.\n- **Dry-run**: `--dry-run` flag for destructive/stateful operations.\n- **Meaningful exit codes**: distinct codes for different failure types, documented in `--help`.\n- **Safe defaults**: require explicit confirmation flags (`--confirm`) for destructive actions.\n- **Predictable output size**: default to summary or limit for large output; support `--offset` for pagination or `--output` for file output.\n\nFile v1.0.0:skill-card.md\n\n## Description: <br>\nAgent Skills standard reference guide covering SKILL.md specification format, progressive disclosure, skill discovery and activation, frontmatter metadata fields, and directory structure conventions. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[openlark](https://clawhub.ai/user/openlark) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and agent builders use this skill as a reference when creating, validating, evaluating, or integrating Agent Skills across supported agent products. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Copied integration guidance could expose full local filesystem paths to a model or user. <br>\nMitigation: Avoid disclosing full local filesystem paths when adapting the guidance into an agent integration. <br>\nRisk: Skill descriptions may trigger too broadly if adapted without testing. <br>\nMitigation: Test descriptions with near-miss negative cases before deployment so the skill activates only for appropriate tasks. <br>\n\n\n## Reference(s): <br>\n- [ClawHub Agent Skills release](https://clawhub.ai/openlark/agent-skills) <br>\n- [Integration guide](references/integrate.md) <br>\n- [Skill creation best practices](references/best-practices.md) <br>\n- [Skill quality evaluation](references/eval-skills.md) <br>\n- [Optimizing skill descriptions](references/optimize-desc.md) <br>\n- [Bundling scripts in skills](references/using-scripts.md) <br>\n- [Products supporting Agent Skills](references/products.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown guidance with tables, examples, and inline shell commands] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Documentation-only output; no executable code is bundled with this release.] <br>\n\n## Skill Version(s): <br>\n1.0.0 (source: server release metadata) <br>\n\n## Ethical Considerations: <br>\nUsers 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. <br>","readmeExcerpt":"Skill: Agent Skills Owner: openlark Summary: Agent Skills standard reference guide. Covers SKILL.md specification format, progressive loading, skill discovery and activation, authoring best practices, quality evaluation, description optimization Tags: latest:1.0.1 Version history: v1.0.1 | 2026-06-26T04:57:23.117Z | user - Streamlined the reference section, replacing multiple detailed documents with concise files foc","codeSnippets":[],"executableExamples":[{"language":"markdown","snippet":"---\nname: pdf-processing\ndescription: Extract PDF text, fill forms, merge files. Use when handling PDFs.\n---\n\n## Workflow\n1. Extract: `python scripts/extract.py input.pdf`\n2. Fill: `python scripts/fill.py template.pdf data.json`\n\n## Gotchas\n- Scanned PDFs need OCR first — use `scripts/ocr.py`"},{"language":"bash","snippet":"skills-ref validate ./my-skill"},{"language":"bash","snippet":"mkdir -p my-skill/references"},{"language":"markdown","snippet":"---\nname: my-skill\ndescription: What it does + when to trigger. Use when...\n---\n\n## Workflow\n1. First step\n2. Second step\n\n## Gotchas\n- Common pitfalls"},{"language":"markdown","snippet":"| Need | Read |\n|------|------|\n| Detailed API reference | [references/api.md](references/api.md) |"},{"language":"bash","snippet":"skills-ref validate ./my-skill"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: agent-skills\ndescription: Agent Skills standard reference guide. Covers SKILL.md specification format, progressive loading, skill discovery and activation, authoring best practices, quality evaluation, description optimization, and more. \n---\n\n# Agent Skills Standard\n\n> A standardized way to equip AI Agents with new capabilities and domain expertise. Adopted by 35+ Agent products.\n\n## Use Cases\n\nUse when creating new skills, validating skill formats, optimizing existing skills, or learning about standardized skill system design.\n\n## Reference File Routing\n\n| Need | Read |\n|------|------|\n| Quick skill creation (5-step guide) | [quick-start.md](references/quick-start.md) |\n| SKILL.md format spec + Agent integration | [spec.md](references/spec.md) |\n| Authoring best practices + quality eval + description optimization | [authoring.md](references/authoring.md) |\n| Common anti-patterns and fixes | [anti-patterns.md](references/anti-patterns.md) |\n| Script binding and design | [using-scripts.md](references/using-scripts.md) |\n| Supported product list | [products.md](references/products.md) |\n\n## Minimal Example\n\n```markdown\n---\nname: pdf-processing\ndescription: Extract PDF text, fill forms, merge files. Use when handling PDFs.\n---\n\n## Workflow\n1. Extract: `python scripts/extract.py input.pdf`\n2. Fill: `python scripts/fill.py template.pdf data.json`\n\n## Gotchas\n- Scanned PDFs need OCR first — use `scripts/ocr.py`\n```\n\n## Validation\n\n```bash\nskills-ref validate ./my-skill\n```"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn75qrtb885pznwsjwsh18dvf1813bv0\",\n  \"slug\": \"agent-skills\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1782449843117\n}"},{"path":"references/anti-patterns.md","content":"# Skill Authoring Anti-Patterns\n\n## 1. Swiss-Army Skill\n\n**Symptom:** Description covers many unrelated features. **Consequence:** Triggers on almost every conversation, wasting tokens and interfering with decisions. **Fix:** One Skill does one thing. Split into multiple Skills if functionality is broad.\n\n## 2. Vague Description\n\n**Symptom:** \"Help with development\", \"Code assistant\" — generic phrases. **Consequence:** Extremely high false-trigger rate; fails to trigger when actually needed. **Fix:** Description must include \"what\" + \"when\". ❌ \"Help with development\" → ✅ \"Extract PDF text, fill forms. Use when handling PDFs.\"\n\n## 3. Over-Prescription\n\n**Symptom:** Every step locked down to exact commands and output wording. **Consequence:** Agent loses flexibility, gets stuck on minor deviations. **Fix:** Give direction, not scripts — list \"what\" (goals) not \"how\" (exact steps). Use \"consider\", \"may\" instead of \"must\".\n\n## 4. Missing Gotchas\n\n**Symptom:** Only documents happy paths, no known traps. **Consequence:** Agent repeats the same mistakes every new session. **Fix:** Add `## Gotchas` section. Format: problem → cause → solution. Update every time you hit one.\n\n## 5. Monolithic File\n\n**Symptom:** SKILL.md 2000+ lines. **Consequence:** Burns massive tokens on every activation, only 10% actually used. **Fix:** Split at >500 lines into `references/`; main file keeps skeleton + routing table.\n\n## 6. Untested Description\n\n**Symptom:** Ships without ever validating trigger accuracy. **Consequence:** Frequent false triggers or missed triggers in production. **Fix:** Test with 5–10 real prompts before shipping. Ensure relevant scenarios trigger, irrelevant ones don't."},{"path":"references/authoring.md","content":"# Skill Authoring Guide\n\nComplete methodology for creating high-quality Skills: best practices → description optimization → quality evaluation.\n\n---\n\n## I. Best Practices\n\n### 1.1 Start from Real Experience\n\nExtract reusable patterns from actual tasks (successful steps, human corrections, I/O formats), or synthesize from project docs/runbooks/API specs. Only distill Skills after completing real tasks — never design from scratch.\n\n### 1.2 Refine Through Real Execution\n\nAfter initial draft, run with real tasks and collect full traces. Look at execution traces, not just output — if the Agent spends time on useless steps, the instructions are too vague or inapplicable.\n\n### 1.3 Context Efficiency\n\n**Add what the Agent lacks, remove what it knows.** For every piece of content ask: \"Would the Agent get this wrong without this instruction?\" No → delete.\n\n**Design cohesive units.** Too narrow → multiple Skills conflict; too broad → hard to activate precisely. Querying DB + formatting results is a reasonable unit; adding DB administration is too large.\n\n**Use progressive disclosure for large Skills.** SKILL.md <500 lines. Put detailed content in `references/`; tell the Agent in the main file **when** to load them.\n\n### 1.4 Calibration Control\n\n- **Match specificity to fragility**: When multiple approaches work, explain _why_; for fragile operations (e.g., DB migrations), enforce strict sequence\n- **Provide defaults, not menus**: Pick one default, briefly mention alternatives\n- **Prefer process over declaration**: Teach the Agent **how to approach** problems, not what to produce for specific instances\n\n### 1.5 Effective Instruction Patterns\n\n- **Gotchas**: Most valuable — environment-specific traps the Agent won't know. Update every time you step on one\n- **Output templates**: More reliable than descriptive language; short templates in SKILL.md, long ones in `assets/`\n- **Checklists**: Checkbox format prevents omissions\n- **Verify loop**: Do → run validator → fix → repeat\n- **Plan-verify-execute**: For batch/destructive operations, create intermediate plan first\n- **Package scripts**: Agent repeatedly writes same logic → write a tested script once in `scripts/`\n\n---\n\n## II. Description Optimization\n\n### 2.1 Trigger Mechanism\n\nAgent loads all `name` + `description` at startup (Tier 1). Match → read full SKILL.md. Complex domain tasks are where description delivers value.\n\n### 2.2 Writing Tips\n\n- Imperative tone: \"Use this skill when...\"\n- Focus on user intent, not internal mechanics\n- Be pushy — explicitly list applicable scenarios\n- ≤1024 characters\n\n### 2.3 Trigger Eval\n\n~20 queries (8–10 should trigger + 8–10 should not). Most valuable negatives are **near-misses**: share keywords but need something different. Run each query 3×; should-trigger ≥0.5 pass, should-not <0.5 pass. 60% train + 40% validation to prevent overfitting.\n\n### 2.4 Optimization Loop\n\n1. Evaluate current description → 2. Modify using only train failures → 3. Too narrow: broaden; too br"},{"path":"references/products.md","content":"# Products Supporting Agent Skills\n\nAdopted by 35+ products across terminal agents, IDEs, cloud platforms, and frameworks.\n\n| Product | Type |\n|---------|------|\n| Claude Code | Terminal/IDE |\n| GitHub Copilot | IDE |\n| Cursor | IDE |\n| OpenAI Codex | Terminal/IDE |\n| Pi | Terminal |\n| Gemini CLI | Terminal |\n| VS Code | IDE |\n| OpenCode | Terminal/IDE |\n| Roo Code | IDE |\n| Goose | Terminal |\n| Spring AI | Framework |\n| Letta | Platform |\n| fast-agent | Framework |\n| Databricks Genie Code | Platform |\n| Laravel Boost | Framework |\n\n## Universal Compatibility Paths\n\n- `~/.agents/skills/` — User-level\n- `.agents/skills/` — Project-level\n\n> Full list: [Agent Skills Official Documentation](https://agentskills.io)"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Agent Skills standard reference guide. Covers SKILL.md specification format, progressive loading, skill discovery and activation, authoring best practices, quality evaluation, description optimization Skill: Agent Skills Owner: openlark Summary: Agent Skills standard reference guide. Covers SKILL.md specification format, progressive loading, skill discovery and activation, authoring best practices, quality evaluation, description optimization Tags: latest:1.0.1 Version history: v1.0.1 | 2026-06-26T04:57:23.117Z | user - Streamlined the reference section, replacing multiple detailed documents with concise files foc","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1321,"uniquenessScore":55,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T13:05:30.064Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T13:05:30.064Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:18:11.711Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"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","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"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!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}