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
A SKILL.md has three parts:
Frontmatter
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
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:
Before releasing a catalogue change, verify remote discovery from a clean directory:
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. Last modified on August 9, 2026
