> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qredence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authoring skills

> Anatomy of a SKILL.md, the required frontmatter and workflow sections, and the validation and release workflow for adding a new skill to the Qredence catalogue.

New skills belong under `skills/figma-agent/<skill-name>/` as a kebab-case directory with a matching frontmatter `name`. Each skill is a single `SKILL.md` — there is no duplicate upload document.

## Anatomy of a skill

```text theme={null}
skills/figma-agent/<skill-name>/SKILL.md
```

A `SKILL.md` has three parts:

| Part                                     | Role                                                                    |
| ---------------------------------------- | ----------------------------------------------------------------------- |
| YAML frontmatter (`name`, `description`) | Discovery and routing for agents. `name` must match the directory name. |
| Purpose and operating role               | What the skill does and how it should behave inside Figma.              |
| Workflow sections                        | Concrete steps, limits, guardrails, and output shape.                   |

### Frontmatter

```yaml theme={null}
---
name: accessibility-audit
description: "Audits a design against WCAG 2.2 AA basics that are checkable in Figma: color contrast, text sizing, tap/click target size, focus order, and presence of alt-text-equivalent labels for meaningful icons. Use before a design is considered done."
---
```

The `description` is the routing signal — write it as a trigger. Include the observable inputs, the checks the skill performs, and when to invoke it.

### Standard sections

Match the sections used by shipped skills so agents can route reliably:

* **Purpose** — one paragraph, plain intent.
* **Operating Role** — how the skill behaves in Figma (selection-first, evidence-backed, no broad redesign unless asked).
* **Supported Context** — what the skill uses (selection, page, prototype settings, comments, connectors, code).
* **Activation Boundary** — when to run it.
* **Required Inputs** — what the user must supply, and what may be inferred.
* **Fast Defaults** — the useful-first-pass behavior when context is incomplete.
* **Workflow** — the numbered steps the skill executes.
* **Figma Execution Limits** — scoped edits, ambiguity handling, and behaviors the skill must not claim.
* **Guardrails** — quality-critical behaviors that must not drift.
* **Finding Quality Rules** — how to phrase findings, evidence, and severity.

## Scaffold a new skill

```bash theme={null}
uv run python scripts/init_skill.py my-new-skill
# edit skills/figma-agent/my-new-skill/SKILL.md
```

Use kebab-case names. Keep `name` and `description` in YAML frontmatter, and make sure `name` matches the directory name.

## Validate

Run the same checks CI runs before opening a pull request:

```bash theme={null}
uv run python scripts/validate_skills.py
uv run python tests/test_skills_catalog.py
uv run ruff check .
uv run ruff format --check .
```

Before releasing a catalogue change, verify remote discovery from a clean directory:

```bash theme={null}
npx skills@latest add qredence/skills --list
```

Only active Figma skills should appear. Anything under `archive/` is documentation only and must never contain a `SKILL.md`.

## Repository conventions

* Use `uv` for Python commands and `ruff` for formatting and linting.
* Keep README content user-focused. Maintenance details belong in `AGENTS.md`.
* Do not add plugin-manager stubs, duplicate agent rules, or archived `SKILL.md` files.

Full maintainer workflow: [`AGENTS.md`](https://github.com/Qredence/skills/blob/main/AGENTS.md).