# Agent playbook (Skillvad)

You are connected to **Skillvad**, a personal and team **skill library** for reusable AI skills and examples of their output. It is **not** a marketplace, skill store, or catalog for buying and selling. Public skills can appear on someone's profile so others can open and copy them. That is sharing, not a storefront.

Skills follow the open [Agent Skills](https://agentskills.io/specification) format: a SKILL.md (instructions with `name` and `description` frontmatter), plus optional files in `references/`, `scripts/`, and `assets/`.

**Brand name:** always **Skillvad**. Domain: `skillvad.tech`.

## First steps

1. Call `get_docs` with topic `agent` (or read `https://skillvad.tech/docs/agent.md`) if you need a refresher.
2. Use `list_skills` to check the user's skills and their teams' libraries before creating duplicates. To open someone else's shared skill, use `get_skill` with the id from its link.
3. On the Free plan a user can save up to 25 skills; `upsert_skill` returns an error at the limit. Don't work around it.
4. **Agent label (once per conversation):** before your first `upsert_skill` in this conversation, propose a short label for yourself (e.g. `Cursor on Mac`, `Claude Desktop`) and ask the user to confirm or edit it. Do not create or update a skill until they confirm. Then pass that value as `agentLabel` on every `upsert_skill` for the rest of the conversation.
5. Use `upsert_skill` with a clear title. It updates your own skill with that title, or creates a new one. Pass `team` to work in a team library.
6. Always attach at least one **example** when publishing a new skill (`add_example`).

## Using a skill

1. Load it with `get_skill`. Treat the skill as a starting point you and the user can refine, not a rigid script you must follow word for word.
2. If the skill is a process, audit, review, checklist, or methodology: briefly ask the user what matters for *this* run and how they want results shaped. Help them confirm or adjust the methodology, then use that agreed baseline. Do not invent a fixed "predefined" process and claim the AI must follow it blindly.
3. `get_skill` lists bundled `files` by path. Read one with `get_skill_file` only when the instructions point to it or the task needs it.
4. Use the skill's examples as the reference for format, tone, and quality.

## Writing a good skill

- **Description:** what the skill does *and when to use it*, with the words a user would actually say. Agents decide whether to load a skill from this alone.
- **Instructions** (`content`): raw Markdown, not HTML. Steps, rules, and what good output looks like. Keep it under about 500 lines.
- **Methods and audits:** when saving a review, audit, or checklist skill, discuss the steps with the user first. Capture *their* methodology in the skill as the baseline. Don't drop in a generic template and call it predefined.
- **References:** move long material (style guides, API notes, checklists) into `references/` with `put_skill_file`, and name each file by its path in the instructions, e.g. "For banned words, read `references/banned-words.md`". Templates and data go in `assets/`, runnable code in `scripts/`.
- **License:** only set `license` (e.g. `MIT`, `Apache-2.0`, `CC-BY-4.0`, `Proprietary`) when the user chooses one. Ask; don't pick for them.
- **Requirements:** set `compatibility` only if the skill needs specific tools or access.

## Uploading a skill folder

When the user asks you to upload a local skill (for example `~/.claude/skills/pdf-processing/`):

1. Read `SKILL.md`. Use its `name` (as a readable title), `description`, and `license`; the body after the frontmatter is the `content`.
2. Call `upsert_skill` with those fields. If the folder has a LICENSE file, pass its text as `licenseText`.
3. For each file under `references/`, `scripts/`, and `assets/`, call `put_skill_file` with the same relative path, e.g. `references/forms.md`.
4. Only text files up to 100 KB each, 30 per skill, one subfolder deep. Skip binaries (images, PDFs) and tell the user which files you skipped.
5. Give the user the skill's link when done.

To go the other way, the user can download any skill as a zip from its page and unzip it into their app's skills folder.

## Visibility

New skills are **Private** by default (only the owner). Pass `team` without `visibility` to create in a team library instead.

The owner can set `visibility` on `upsert_skill` to `private`, `unlisted`, `public`, or `team` (pass `team` with the team slug). Omit `visibility` on updates to leave it unchanged. Only change it when the user asks. Never share a skill that contains secrets. **Unlisted** is open to anyone with the link; **Public** is also listed on the owner's profile at `https://skillvad.tech/u/<username>`.

## Auth context

Your connection belongs to one user. Everything you create is owned by that user, and you can only change what that user can change.

## URLs to cite

- App: `https://skillvad.tech/app`
- Skill: use the `url` the tools return. It looks like `https://skillvad.tech/u/<username>/skills/<id>`.
- Examples: the skill URL plus `/examples`. References: the skill URL plus `/references`.
- Docs: `https://skillvad.tech/docs`
- Agent doc (raw): `https://skillvad.tech/docs/agent.md`

## Don'ts

- Don't call Skillvad a marketplace, skill store, or place to buy skills. It is a library.
- Don't delete skills or files unless the user confirms.
- Don't change visibility to unlisted, public, or team unless the user asks.
- Don't paste secrets into skills, files, or examples.
- Don't rely on client-side rendering; store Markdown source.
