# Author a skill
Source: https://solidstate.cc/docs/authoring

Write a SKILL.md that triggers reliably and runs anywhere. Spec constraints, description craft, progressive disclosure, validation.

A skill teaches an agent a procedure. Once.

The format is the [Agent Skills spec](https://agentskills.io/specification) — adopted by \~40 runtimes including Claude Code, Hermes, Codex, and Cursor. Write to the spec and your skill runs everywhere.

## The anatomy

```
my-skill/
├── SKILL.md        # required — frontmatter + instructions
├── scripts/        # optional — executable helpers
├── references/     # optional — docs loaded on demand
└── assets/         # optional — templates, examples
```

## Frontmatter

```yaml theme={null}
---
name: pdf-data-extract
description: >-
  Extract financial data from PDF statements into CSV.
  Use when the user uploads bank or card statements
  and wants structured output.
  Not for scanned images without text layers.
license: MIT
---
```

The rules:

| Field           | Constraint                                                                         |
| --------------- | ---------------------------------------------------------------------------------- |
| `name`          | Required. ≤64 chars, lowercase a-z0-9 + hyphens. Must match the folder name.       |
| `description`   | Required. ≤1024 chars. Decides whether your skill ever fires.                      |
| `license`       | Optional. SPDX name or bundled file reference. Required for a Solid State listing. |
| `compatibility` | Optional. ≤500 chars of environment requirements.                                  |

## The description is the product

Agents load two things at startup: name and description. \~100 tokens. Everything else loads only on match.

So the description does all the triggering work. It needs:

* **Specific verbs.** "Extract financial data from PDFs" beats "help with documents."
* **Concrete triggers.** Name the situations: "when the user uploads bank statements."
* **Explicit boundaries.** "Not for scanned images." Negative triggers prevent false fires.

One skill, one job. "SEO optimization for blog posts" — not "content marketing helper" (too broad), not "add meta descriptions" (too narrow).

## The body

Structure for scanning: overview → prerequisites → steps → examples → error handling → limitations.

Keep `SKILL.md` under 500 lines. Under 5,000 tokens is the recommendation.

Need more? Use the menu approach: SKILL.md lists what's available, relative paths point to separate files. The agent reads only what the task needs. That's progressive disclosure — the spec's three load tiers (metadata → instructions → resources) exist so your skill costs nothing until it's used.

## Test before you ship

Three scenario classes:

1. **Normal operations.** Typical requests. Must work.
2. **Edge cases.** Missing data, odd formats. Degrade gracefully or say what's needed.
3. **Out-of-scope.** Related-but-wrong requests. The skill must stay dormant.

Triggering and execution fail separately. No activation → broaden the description. Wrong output → tighten the instructions.

Validate the structure:

```bash theme={null}
npx skills-ref validate ./my-skill
```

## Ship it

Push the folder to a public repo. Then [submit it](/docs/submitting) to the catalog.

A stated license is required for listing. → [Licensing & provenance](/docs/licensing)


# For agents
Source: https://solidstate.cc/docs/for-agents

Machine-readable access to Solid State. MCP server, llms.txt, markdown endpoints, and how to install skills programmatically.

You might be an agent reading this. Good. This page is for you.

## Read these docs as markdown

Every page here serves clean markdown three ways:

* **Index:** [`solidstate.cc/docs/llms.txt`](https://solidstate.cc/docs/llms.txt) — all pages, linked as `.md`.
* **Everything at once:** [`solidstate.cc/docs/llms-full.txt`](https://solidstate.cc/docs/llms-full.txt) — the full docs in one file.
* **Per page:** append `.md` to any docs URL. Or send `Accept: text/markdown` and get markdown back.

No HTML parsing. No token waste. Both files regenerate on every deploy — never stale.

## Connect over MCP

These docs run a hosted MCP server:

```
https://solidstate.cc/docs/mcp
```

Two tools:

* `search_solid_state` — search the Solid State knowledge base. Returns contextual content with links to the source pages.
* `query_docs_filesystem_solid_state` — read-only shell-style queries (`rg`, `cat`, `head`, `tree`) over a virtual filesystem of these docs. No writes, no network, no process control.

Add it to any MCP-capable client:

```json theme={null}
{
  "mcpServers": {
    "solidstate": {
      "url": "https://solidstate.cc/docs/mcp"
    }
  }
}
```

## Discover skills over HTTP

solidstate.cc publishes a well-known skills endpoint. Two paths, two schema versions:

```
# Discovery spec v0.2.0 — $schema, digests
https://solidstate.cc/.well-known/agent-skills/index.json

# legacy v0.1.0 — Hermes-compatible
https://solidstate.cc/.well-known/skills/index.json
```

Fetch the index, match a description, fetch the `SKILL.md` at the entry's `url`. The v0.2.0 entries carry SHA-256 digests — verify after download.

Hermes treats this site as a native source:

```bash theme={null}
hermes skills search https://solidstate.cc --source well-known
hermes skills install \
  well-known:https://solidstate.cc/.well-known/skills/publish-audit
```

The endpoint serves free, redistributable skills. The full catalog — including listings that live upstream — is at [solidstate.cc/skills](https://solidstate.cc/skills).

## Install a skill for your operator

The short version (the long version is the [install page](/docs/index)):

```bash theme={null}
# Claude Code
cp -r <skill-folder> ~/.claude/skills/

# Hermes — tap, well-known, or ClawHub
hermes skills tap add solidstatecc/skills
hermes skills install solidstatecc/skills/publish-audit

# Codex
cp -r <skill-folder> .codex/skills/
```

All Solid State originals follow the [Agent Skills spec](https://agentskills.io): one folder, `SKILL.md` at root, frontmatter with `name` and `description`. If your runtime reads the spec, the skill runs.

## Run skills over the Claude API

No filesystem? Skills run server-side too. Send the beta headers:

```text theme={null}
anthropic-beta: code-execution-2025-08-25,files-api-2025-04-14,skills-2025-10-02
```

then name skills in the request's `container.skills` array — `{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}` — alongside the code-execution tool. Custom skills upload once via the [Skills API](https://docs.claude.com/en/api/skills-guide) and load the same way. Full syntax on the [install page](/docs/index#claude-api).

## Find skills

The human catalog is [solidstate.cc/skills](https://solidstate.cc/skills). Each listing page carries the repo URL, license, and platform compatibility.

For machine discovery, use the well-known endpoint above. The docs MCP server covers documentation queries.

## Ground rules

* Listings link to upstream repos. Verify the license at source before installing for your operator.
* Install counts on this site are real or absent. Absent means unmeasured, not zero.
* If a skill's description doesn't match its behavior, that's a bug in the catalog: report it via [solidstate.cc/submit](https://solidstate.cc/submit).


# Install a skill
Source: https://solidstate.cc/docs/index

Install any Solid State skill on Claude Code, Hermes, OpenClaw, Codex, Cursor, OpenCode, or Cline — or run it over the Claude API. One folder, one SKILL.md.

Using an agent? Paste this and walk away:

```text theme={null}
Read https://solidstate.cc/docs/llms-full.txt and install a skill for me.
```

A skill is packaged judgment. Instructions that tell an agent how to think when it hits a task it's seen before.

Physically: a folder with a `SKILL.md` inside.

Installing means putting that folder where your agent looks. That's it.

Every runtime below reads the same [Agent Skills spec](https://agentskills.io). One skill, every agent. No rewrites.

## Claude Code

Drop the folder in your skills directory:

```bash theme={null}
# personal — available in every project
mkdir -p ~/.claude/skills
cp -r ./my-skill ~/.claude/skills/

# project — checked into the repo, shared with the team
mkdir -p .claude/skills
cp -r ./my-skill .claude/skills/
```

Claude loads it when the task matches the skill's description. No restart, no registration.

Plugins can bundle skills and install from marketplaces. See [Claude Code docs](https://docs.claude.com/en/docs/claude-code).

## Claude API

Skills also run server-side. No filesystem, no install step.

Three beta headers and a `container` block:

```python theme={null}
from anthropic import Anthropic

client = Anthropic(
    default_headers={
        "anthropic-beta": "code-execution-2025-08-25,files-api-2025-04-14,skills-2025-10-02"
    }
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    container={"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]},
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    messages=[{"role": "user", "content": "Build the budget spreadsheet."}],
)
```

`type: "anthropic"` loads Anthropic's built-ins (docx, pdf, pptx, xlsx). Custom skills upload once via the [Skills API](https://docs.claude.com/en/api/skills-guide), then load by `skill_id` the same way. Same folder, same `SKILL.md` — zipped instead of copied.

Files the skill creates come back as `file_id`s. Download them via the Files API.

Working notebooks: [Anthropic's skills cookbook](https://github.com/anthropics/claude-cookbooks/tree/main/skills).

## Hermes Agent

Three rails. Pick one.

**Tap** — subscribe to the Solid State repo:

```bash theme={null}
hermes skills tap add solidstatecc/skills
hermes skills install solidstatecc/skills/publish-audit
```

**Well-known** — solidstate.cc is a discovery endpoint:

```bash theme={null}
hermes skills search https://solidstate.cc --source well-known
hermes skills install \
  well-known:https://solidstate.cc/.well-known/skills/publish-audit
```

**ClawHub** — an integrated Hermes source:

```bash theme={null}
hermes skills install clawhub/<skill-name>
```

Every rail runs Hermes' security scan. Community-source warnings are normal.

Or skip all three and drop a folder into `~/.hermes/skills/`.

## OpenClaw

Install from the ClawHub registry — Solid State publishes under the `solidstate` owner:

```bash theme={null}
npx clawhub install solidstate/<skill-name>
```

Or place the folder in your OpenClaw skills directory.

## Codex

```bash theme={null}
mkdir -p .codex/skills
cp -r ./my-skill .codex/skills/
```

Same spec, same layout.

## OpenCode

OpenCode reads Claude's skill paths directly. If a skill is in `.claude/skills/` or `~/.claude/skills/`, it already works.

Native paths also work:

```bash theme={null}
mkdir -p .opencode/skills
cp -r ./my-skill .opencode/skills/
```

Global: `~/.config/opencode/skills/`. It also reads `.agents/skills/`. No conversion, no config.

## Cursor, Cline

Both consume the Agent Skills spec. Place the skill folder in the runtime's skills directory and it loads on match. Check each tool's docs for the current path — these move fast.

## Everything else

Any spec-compliant runtime works the same way:

1. Get the skill folder (clone the repo, or download from the listing page).
2. Put it where your runtime reads skills.
3. Confirm `SKILL.md` sits at the folder root.

Done. The skill triggers when your task matches its description.

## Skills vs. MCP

Skills teach. MCP connects.

A skill is knowledge — how to think about a problem.
MCP is a tool channel — what the agent can reach.

You want both. They don't compete.

## Before you install

Skills are code. Treat them like code.

In February 2026, a popular skill pack shipped with planted instructions that stole API keys from the agents that installed it. Registries added scanners after. Scanners miss things.

Read the `SKILL.md`. Read every file that ships with it. Then install.

Every listing here shows its [provenance](/docs/licensing) for exactly this reason. It's a pointer you can follow. Follow it.

## Where the skills are

Browse the catalog at [solidstate.cc/skills](https://solidstate.cc/skills). Filter by runtime, category, or license.

Every listing links to its source repo. Originals are authored by Solid State. Listings point upstream — we index, we don't claim.

***

Installed one? Write one. → [Author a skill](/docs/authoring)


# Licensing & provenance
Source: https://solidstate.cc/docs/licensing

How Solid State labels skills: kind, provenance, and SPDX licenses. The honest-directory schema explained.

Every listing on solidstate.cc carries three labels. None of them are decorative.

## Kind

| Value      | Meaning                                                                   |
| ---------- | ------------------------------------------------------------------------- |
| `original` | Authored by Solid State. We wrote it, we maintain it, we answer for it.   |
| `listing`  | Indexed from upstream. The author is the author. We link, we don't claim. |

## Provenance

Where the skill actually comes from. `first-party` means us. Everything else names the upstream source — ClawHub, skills.sh, Hermes, a GitHub repo.

There is no "verified" badge. A boolean that says "trust me" is a facade. Provenance is a pointer you can follow.

## License

Stated as an SPDX identifier. The accepted set:

`MIT` · `MIT-0` · `Apache-2.0` · `BSD-3-Clause` · `BSD-2-Clause` · `ISC` · `GPL-3.0` · `AGPL-3.0` · `MPL-2.0` · `Unlicense` · `CC0-1.0` · `source-available` · `proprietary`

Two special cases:

* **`undeclared`** — the upstream repo states no license. The listing shows it plainly. Use at your own judgment; legally, no license means all rights reserved.
* **`unknown`** — we refuse to render it. If we can't determine the license, the skill doesn't get listed.

## Why this schema exists

Marketplaces inflate. Install counts get invented, "verified" badges get sold, authorship gets blurred.

The rules here are baked into the data model:

* No install count we haven't measured.
* No authorship we don't hold.
* No repo link that 404s.
* No license field that hides what it doesn't know.

A directory is only useful if you can trust its labels. That's the whole product.

***

Reading this as an agent? There's a page for you. → [For agents](/docs/for-agents)


# Submit a skill
Source: https://solidstate.cc/docs/submitting

Get your skill listed on solidstate.cc. What we check, what we reject, how long it takes.

Submit at [solidstate.cc/submit](https://solidstate.cc/submit).

Every submission is reviewed by a person. Expect an answer within 2–5 business days.

## What we check

Curation is the product. The bar:

1. **The repo resolves.** Public, reachable, `SKILL.md` at the skill folder's root.
2. **The license is real.** A recognized SPDX license, stated in the repo. "Unknown" doesn't render on this site — literally. See [licensing](/docs/licensing).
3. **The description triggers honestly.** It says what the skill does, when it fires, and when it doesn't. No keyword stuffing.
4. **The skill works.** We install it and run it. Normal case, edge case, out-of-scope case.
5. **The claims are true.** Benchmarks, integrations, outputs — if the README says it, the skill does it.

## What gets rejected

* No license, or a license that contradicts the repo.
* Dead or private repos.
* Descriptions engineered to trigger on everything.
* Skills that shell out to undisclosed paid APIs.
* Malware, obviously. Every submission gets scanned.
* Duplicates of existing listings with no improvement.

Rejection comes with the reason. Fix it, resubmit.

## What listing means

Your skill appears in the catalog with its real provenance:

* **You stay the author.** Listings link upstream to your repo. We index — we don't fork, mirror, or claim.
* **No fabricated numbers.** We don't show install counts we haven't measured. Yours won't get invented ones either.
* **You can pull out.** Email and the listing is gone within 48 hours.

## Selling a skill

Paid originals are live on the marketplace. Third-party paid listings are coming.

Want in early? Say so in the submission notes.

***

What the labels on your listing mean → [Licensing & provenance](/docs/licensing)


# Terms of use
Source: https://solidstate.cc/docs/terms

The terms for using solidstate.cc and installing skills listed here. Plain language. Read before you install.

Last updated: June 7, 2026.

Using solidstate.cc means you accept these terms. If you don't accept them, don't use the site.

"Solid State," "we," and "us" mean the operator of solidstate.cc (Visionaire Labs). "Listings" means any skill, pack, or resource indexed or sold on this site. "Originals" means listings we authored ourselves.

## What this site is

Solid State is a curated directory. Most listings are third-party: we index public content from external repositories and link upstream. We curate what gets listed, and we run checks described in [Submitting](/docs/submitting) — but curation is not certification.

**We do not guarantee the quality, safety, correctness, or security of any listing.** Not third-party listings, and (beyond what their licenses state) not originals.

## Skills execute. Treat them that way.

A skill is a set of instructions your AI agent reads and acts on. That carries real risk, and you accept it by installing:

* **Malicious instructions and prompt injection.** A skill's files can contain text designed to manipulate an agent into unintended actions — exfiltrating data, running commands, overriding your instructions. Scanning reduces this risk. Nothing eliminates it.
* **Code execution.** Skills may bundle scripts. Installing a skill can mean running someone else's code on your machine.
* **Behavior drift.** Upstream repos change after we index them. The code you install may not be the code anyone reviewed.

**You are responsible for reviewing a skill — its SKILL.md, scripts, and source repository — before installing it, and for running agents with appropriate permissions and sandboxing.** Solid State is not liable for any damage, loss, or harm caused by any listing, including harm resulting from prompt injection, malicious instructions, or bundled code, whether or not the listing passed our checks.

## No warranty

The site and all listings are provided "as is" and "as available," without warranty of any kind, express or implied, including merchantability, fitness for a particular purpose, and non-infringement.

## Limitation of liability

To the maximum extent permitted by law, Solid State's total liability for any claim arising from the site or any listing is limited to the amount you paid us for the listing giving rise to the claim in the twelve months before the claim, or 100 USD, whichever is greater. We are not liable for indirect, incidental, special, consequential, or punitive damages, including lost data, lost profits, or the actions of any AI agent acting on a listing's instructions.

## Acceptable use

Don't submit or distribute through this site: malware or harmful payloads; skills containing hidden or obfuscated instructions intended to manipulate agents; skills that misrepresent what they do; content you don't have the rights to. We may remove any listing, reject any submission, and revoke access for violations, with or without notice.

## Purchases

Paid listings are sold through third-party processors under their own terms. Prices are shown before purchase. Unless stated otherwise on the listing, sales are final.

## Takedown and corrections

Authors can have their listing removed: email [hi@solidstate.cc](mailto:hi@solidstate.cc) and it's gone within 48 hours. The same address handles rights complaints, security reports about a listing, and factual corrections. We honor reasonable requests quickly.

## Changes

We may update these terms. The "last updated" date changes when we do. Continued use after a change means acceptance.

## Contact

[hi@solidstate.cc](mailto:hi@solidstate.cc)