Skill: openlark/agent-skills (version 1.0.0)

--- name: agent-skills description: Agent Skills standard reference guide. Covers SKILL.md specification format, progressive disclosure mechanism, skill discovery and activation, frontmatter metadata fields, directory structure conventions. --- # Agent Skills > A standardized way to give AI agents new capabilities and expertise. > 35+ agent products support it: Claude Code, GitHub Copilot, Cursor, Pi, Codex, Gemini CLI, and more. ## Use Cases Use when creating new skills, validating skill formats, or understanding the standardized skill system design. ## Directory Structure ``` skill-name/ ├── SKILL.md # Required: YAML frontmatter + Markdown instructions ├── scripts/ # Optional: executable scripts ├── references/ # Optional: on-demand reference docs ├── assets/ # Optional: templates, resource files └── ... # Any additional files ``` ## SKILL.md Format ### Frontmatter | Field | Required | Constraints | |------|----------|-------------| | `name` | ✅ | 1-64 chars, lowercase/numbers/hyphens, no leading/trailing hyphens, no consecutive hyphens, must match directory name | | `description` | ✅ | 1-1024 chars, describe what it does and when to use | | `license` | — | License name or reference | | `compatibility` | — | ≤500 chars, environment requirements | | `metadata` | — | Arbitrary key-value pairs | | `allowed-tools` | — | Space-separated pre-approved tool list (experimental) | ### Minimal Example ```markdown --- name: pdf-processing description: Extract PDF text, fill forms, merge files. Use when handling PDFs. --- ``` ### Body Content Markdown body after frontmatter, no format restrictions. Recommended: step-by-step instructions, input/output examples, common edge cases. Split to `references/` if over 500 lines. ## Progressive Disclosure (Three Tiers) | Tier | What's Loaded | When | Token Cost | |------|--------------|------|------------| | 1. Catalog | name + description | Session start | ~50-100 per skill | | 2. Instructions | Full SKILL.md body | When skill is activated | <5000 tokens (recommended) | | 3. Resources | scripts/references/assets | When referenced by instructions | Varies | ## Skill Discovery ### Scan Locations | Scope | Path | Purpose | |------|------|---------| | Project | `<project>/.<client>/skills/` | Client-native location | | Project | `<project>/.agents/skills/` | Cross-client interoperability | | User | `~/.<client>/skills/` | Client-native location | | User | `~/.agents/skills/` | Cross-client interoperability | Scan subdirectories containing `SKILL.md`. Skip `.git/` and `node_modules/`. Name collisions: project-level overrides user-level. ## Integrating into an Agent See [references/integrate.md](references/integrate.md) for the full integration guide, covering: - Skill discovery (local/cloud/sandbox) - SKILL.md parsing (YAML degradation, lenient validation) - Model disclosure (XML/JSON catalog, behavior instructions) - Activation mechanisms (file-read activation / dedicated tool activation / user explicit activation) - Context management (compaction protection, caching strategies) ## Supported Agent Products 35+ 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). ## Validation ```bash skills-ref validate ./my-skill ``` ## References - **[integrate](references/integrate.md)** — Complete guide to integrating Skills support into agents - **[best-practices](references/best-practices.md)** — Skill creation best practices: real expertise, context management, control granularity, effective instruction patterns - **[eval-skills](references/eval-skills.md)** — Skill quality evaluation: test cases, assertions, grading, iteration loops - **[optimize-desc](references/optimize-desc.md)** — Optimizing the description field: trigger testing, train/validation splits, optimization loops - **[using-scripts](references/using-scripts.md)** — Bundling scripts in skills: one-off commands, self-contained scripts, agent-friendly design - **[products](references/products.md)** — List of 35+ products supporting Agent Skills

path: references/best-practices.md
content: # Skill Creation Best Practices

## Start from Real Expertise

Most effective skills are grounded in real domain experience, not generated from LLM general knowledge.

**Extract from hands-on tasks**: Complete real tasks, then extract reusable patterns → successful steps, manual corrections, I/O formats, project-specific context.

**Synthesize from project artifacts**: Feed internal docs/runbooks/API specs/code reviews to an LLM to synthesize skills, not generic references.

## Refine with Real Execution

Run the first draft against real tasks, collect all results (not just failures). Ask: what false-triggered? What was missed? What can be cut?

Check execution traces: agent wastes time on unproductive steps → instructions too vague, don't apply, or too many options without a default.

## Spending Context Wisely

### Add what the agent lacks, omit what it knows

For each piece: "Would the agent get this wrong without this instruction?" No → cut it. Agents already know what PDFs are, how HTTP works.

### Design coherent units

Too 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.

### Aim for moderate detail

Overly comprehensive skills hurt more than help. Concise stepwise guidance + working example > exhaustive documentation.

### Structure large skills with progressive disclosure

SKILL.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."

## Calibrating Control

### Match specificity to fragility

- **Give freedom**: when multiple approaches work, explain *why* rather than rigid directives
- **Be prescriptive**: fragile operations require exact sequence (`python scripts/migrate.py --verify --backup`, do not modify)

### Provide defaults, not menus

Pick one default when multiple tools work. Mention alternatives briefly, don't list as equal options.

### Favor procedures over declarations

Teach the agent *how to approach* a class of problems, not *what to produce* for a specific instance. The approach should generalize.

## Effective Instruction Patterns

### Gotchas

The highest-value content — environment-specific facts the agent will get wrong without being told. After agent makes a mistake → add to gotchas.

### Output templates

Concrete templates outperform descriptive language (agents pattern-match better against concrete structures). Short templates in SKILL.md, long ones in assets/.

### Checklists

Multi-step workflows with checkboxes track progress and prevent skipped steps.

### Validation loops

Do work → run validator → fix issues → repeat until pass.

### Plan-validate-execute

For batch/destructive operations: create structured intermediate plan, validate against source of truth, then execute. The validation script is the key ingredient.

### Bundle reusable scripts

If agent independently rewrites the same logic each run → write a tested script once in scripts/.


path: references/eval-skills.md
content: # Skill Quality Evaluation

Use structured evals to validate skill quality.

## Test Case Design

```json
{
  "id": 1,
  "prompt": "what a real user would say",
  "expected_output": "what success looks like",
  "files": ["evals/files/input.csv"],
  "assertions": ["verifiable assertion 1", "assertion 2"]
}
```

- Start with 2-3 test cases, don't over-invest
- Vary prompts: formal/casual/typos/different detail levels
- Cover edge cases: malformed input, ambiguous instructions
- Use realistic context: file paths, column names, etc.

## Running Evals

Run each test case twice: **with skill** + **without skill** (baseline). Workspace structure:

```
workspace/iteration-1/
├── eval-01/with_skill/{outputs,timing,grading}
├── eval-01/without_skill/{outputs,timing,grading}
└── benchmark.json
```

Record `timing.json`: `{"total_tokens": 84852, "duration_ms": 23332}`

## Assertions

Good: programmatically verifiable ("output file is valid JSON"), specific and observable ("chart has labeled axes"), countable ("≥3 recommendations").

Weak: too vague ("output is good"), too brittle ("must use exact phrase X").

## Grading

Each assertion PASS/FAIL + concrete evidence (quote/reference output):

```json
{"assertion_results": [{"text": "...", "passed": true, "evidence": "Found chart.png"}],
 "summary": {"passed": 3, "failed": 1, "total": 4, "pass_rate": 0.75}}
```

Grading principles: PASS needs concrete evidence, no benefit of doubt. Also review assertions themselves for reasonableness.

**Blind comparison** (comparing versions): LLM judge scores without knowing which version is which.

## Aggregation

```json
{"run_summary": {
  "with_skill": {"pass_rate": {"mean": 0.83}},
  "without_skill": {"pass_rate": {"mean": 0.33}},
  "delta": {"pass_rate": 0.50}
}}
```

Delta tells you the skill's cost (time/tokens) vs. benefit (pass rate improvement).

## Pattern Analysis

- Remove assertions both sides pass (no signal)
- Investigate both-side failures (broken assertion or too-hard case)
- Study skill-passes / no-skill-fails (where skill adds value)
- Inconsistent results → ambiguous instructions, add examples or specifics
- Check timing/token outliers

## Human Review

Things assertions miss: writing style, visual design, "does it feel right". Record specific actionable feedback.

## Iteration Loop

1. Feed all eval signals + current SKILL.md to LLM for improvement proposals
2. Review and apply changes
3. Rerun all test cases in iteration-N+1/
4. Grade and aggregate
5. Human review. Repeat.

Stop: satisfied / feedback consistently empty / no meaningful improvement.

Guidance for LLM: generalize feedback (not narrow patches), keep lean (fewer better instructions > exhaustive rules), explain why, bundle repeated work into scripts.


path: references/integrate.md
content: # Agent Skills Integration Guide

## Progressive Loading

Tier 1: name+desc (session start, ~50-100t) → Tier 2: full body (on activation, <5000t) → Tier 3: refs/scripts (on demand)

## Step 1: Discovery

### Scan Paths

Project + 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.

Name 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).

## Step 2: Parsing

Extract YAML between `---` → name, description. Fault-tolerant: wrap unquoted colon values in quotes or retry with block scalars.

Lenient validation: name mismatch dir/too long → warn but load; description missing → skip; YAML unparseable → skip.

Store: name, description, location (absolute path), body (store or read on demand), base dir (derived from location).

## Step 3: Disclosure (Tier 1)

Catalog format (in system prompt or tool description):
```xml
<available_skills>
  <skill><name>pdf</name><description>Extract PDF text...</description>
  <location>/path/to/SKILL.md</location></skill>
</available_skills>
```

Behavior 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.

## Step 4: Activation (Tier 2)

**File-read activation**: model reads path with standard read tool (simplest).

**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.

**User explicit activation**: `/skill-name` syntax, harness intercepts and injects. Suggest autocomplete.

**Return content**: full file or body-only (strip frontmatter).

**Structured wrapping** (recommended):
```xml
<skill_content name="pdf"><skill_resources>
  <file>scripts/extract.py</file></skill_resources></skill_content>
```

List resources without eager reading. Allowlist skill directory to avoid permission prompts.

## Step 5: Context Management

- 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)
- Static catalog in system prompt prefix for caching; dynamic conversation in suffix
- Expose skills as commands: `/skill-name args`
- `.agents/skills/` is the most widely adopted cross-product sharing path


path: references/optimize-desc.md
content: # Optimizing Skill Descriptions

The description is the sole mechanism for skill triggering. Under-specified → doesn't trigger; over-broad → false triggers.

## How Triggering Works

Agents 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.

## Writing Effective Descriptions

- **Use imperative phrasing**: "Use this skill when..." not "This skill does..."
- **Focus on user intent**: describe what the user wants to achieve, not skill internals
- **Err on the side of pushy**: explicitly list applicable contexts, including when the user doesn't name the domain
- **Keep concise**: a few sentences to a short paragraph, ≤1024 chars

## Trigger Eval Queries

~20 queries: 8-10 should-trigger + 8-10 should-not-trigger.

### Should-trigger

Vary across: phrasing, explicitness, detail, complexity. Most valuable are queries where the skill helps but the connection isn't obvious.

### Should-not-trigger

Most 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).

## Testing

Run each query 3 times, compute trigger rate. Should-trigger passes if rate ≥0.5; should-not passes if <0.5.

## Avoiding Overfitting

60% train (guide improvements) + 40% validation (check generalization). Keep both sets proportionally mixed.

## Optimization Loop

1. Evaluate on both train + validation
2. Identify train failures only; keep validation blind
3. Revise: too narrow → broaden; too broad → add specificity
4. Avoid adding specific keywords from failed queries (overfitting); find the general category
5. If stuck, try structurally different descriptions rather than incremental tweaks
6. Repeat until train passes or no improvement
7. Select the iteration with highest validation pass rate (not necessarily the last)

~5 iterations usually suffice. No improvement → issue may be with queries, not description. Validate generalization with 5-10 fresh queries.

## Example

```yaml
# Before
description: Process CSV files.

# After
description: >
  Analyze CSV and tabular data — compute summary statistics,
  add derived columns, generate charts, and clean messy data.
  Use when the user has a CSV, TSV, or Excel file and wants to
  explore, transform, or visualize the data, even if they don't
  explicitly mention "CSV" or "analysis."
```


path: references/products.md
content: # Products Supporting Agent Skills

## Coding Agents

| Product | Type | Skills Docs |
|---------|------|-------------|
| Claude Code | Terminal/IDE | code.claude.com/docs/en/skills |
| GitHub Copilot | IDE | docs.github.com/en/copilot/concepts/agents/about-agent-skills |
| Cursor | IDE | cursor.com/docs/context/skills |
| OpenAI Codex | Terminal/IDE | developers.openai.com/codex/skills |
| Pi | Terminal | github.com/badlogic/pi-mono |
| Gemini CLI | Terminal | geminicli.com/docs/cli/skills |
| Junie | IDE (IntelliJ) | junie.jetbrains.com/docs/agent-skills |
| OpenCode | Terminal/IDE | opencode.ai/docs/skills |
| OpenHands | Cloud | docs.openhands.dev/overview/skills |
| Roo Code | IDE | docs.roocode.com/features/skills |
| Goose | Terminal | block.github.io/goose |
| VS Code | IDE | code.visualstudio.com/docs/copilot/customization/agent-skills |
| Mux | Cloud/Desktop | mux.coder.com/agent-skills |
| Amp | Terminal | ampcode.com/manual#agent-skills |

## Platforms & Frameworks

Spring 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.

## Universal Compatibility Paths

Most widely adopted cross-product skill sharing paths:

- `~/.agents/skills/` — user-level
- `.agents/skills/` — project-level

Some implementations also scan `.claude/skills/`, `.codex/skills/` etc. Lenient validation ensures cross-product skill interchangeability.


path: references/using-scripts.md
content: # Bundling Scripts in Skills

## One-off Commands

Reference existing tools directly without a scripts/ directory:

| Tool | Example | Notes |
|------|---------|-------|
| `uvx` | `uvx ruff@0.8.0 check .` | Python, isolated env, needs uv |
| `npx` | `npx eslint@9 --fix .` | Ships with Node.js |
| `bunx` | `bunx eslint@9 --fix .` | Bun's npx equivalent |
| `deno run` | `deno run npm:eslint@9 -- --fix .` | Needs permission flags |
| `go run` | `go run golang.org/x/tools/cmd/goimports@v0.28.0 .` | Ships with Go |

**Tips**: pin versions, state prerequisites, move complex commands into scripts/.

## Referencing Scripts

Use relative paths from skill directory root:

```markdown
## Available scripts
- **`scripts/validate.sh`** — Validates config files
- **`scripts/process.py`** — Processes input data

## Workflow
1. ```bash bash scripts/validate.sh "$INPUT_FILE"```
2. ```bash python3 scripts/process.py --input results.json```
```

## Self-contained Scripts

Declare dependencies inline, no separate manifest needed:

**Python (PEP 723)**: `# /// script` block with dependencies. Run: `uv run scripts/extract.py`

**Deno**: `import * as lib from "npm:pkg@1.0.0";`. Run: `deno run scripts/extract.ts`

**Bun**: `import * as lib from "pkg@1.0.0";`. Run: `bun run scripts/extract.ts`

**Ruby**: Use `bundler/inline` to declare gems.

## Agent-Friendly Script Design

- **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.
- **`--help` provides usage**: primary way agents learn your script's interface. Include brief description, flags, examples.
- **Write helpful errors**: "Error: --format must be one of: json, csv, table. Received: xml."
- **Use structured output**: JSON/CSV > aligned text. Data → stdout, diagnostics → stderr.
- **Idempotency**: agents may retry. "Create if not exists" > "create and error on duplicate".
- **Input constraints**: reject ambiguous input with clear guidance, use enums and closed sets.
- **Dry-run**: `--dry-run` flag for destructive/stateful operations.
- **Meaningful exit codes**: distinct codes for different failure types, documented in `--help`.
- **Safe defaults**: require explicit confirmation flags (`--confirm`) for destructive actions.
- **Predictable output size**: default to summary or limit for large output; support `--offset` for pagination or `--output` for file output.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)