# Linbox Agent Skills Hub

This directory is the source of truth for external agent skills (Cursor, Claude, ChatGPT-compatible markdown skills).

## Manifest

`skills/manifest.json` is the hub catalog and contract version source.

- `contract_version` — required `MAJOR.MINOR` string (no patch), e.g. `"1.0"`. The pack
  script validates this value, stamps it into every `SKILL.md` frontmatter, and writes
  `api/mcp_contract_version.json` for the MCP runtime.

## Structure

Each skill lives in its own directory and must include `SKILL.md`.

```text
skills/
├── README.md
├── linbox/
│   ├── SKILL.md
│   ├── messaging/SKILL.md
│   ├── tags/SKILL.md
│   ├── connections/SKILL.md
│   ├── enrichment/SKILL.md
│   ├── posts/SKILL.md
│   └── campaigns/SKILL.md
└── playbooks/
    ├── SKILL.md
    └── linkedin-outbound-first-touch/SKILL.md
```

## Required SKILL.md contract

### Frontmatter

```yaml
---
name: lowercase-hyphen-name
description: >-
  Third-person WHAT + WHEN description with trigger terms.
contract_version: "1.0"
---
```

- `name`: lowercase letters, numbers, hyphens, max 64 chars.
- `description`: third person, max 1024 chars, includes scope and trigger context.
- `contract_version`: stamped by `scripts/pack_agent_skills.sh` from `manifest.json`; do
  not hand-edit in source files.
- Do not set `disable-model-invocation` unless explicitly needed.

### Body section order

1. `# Title`
2. `## When to use`
3. `## Prerequisites` (only if needed)
4. `## Tools`
5. `## Workflow`
6. `## Rules`
7. `## Examples`
8. `## Related skills`

## Authoring rules

- Write in English.
- Use exact `linbox_*` tool names and parameter names from current docs/code.
- Keep `SKILL.md` under 500 lines.
- Keep root skill thin; put topic-specific detail into topic skills.
- Re-read current docs before writing/updating a skill:
  - `docs/DOCS_MCP.md`
  - `docs/DOCS_tags.md`
  - `docs/INTEGRATION_mcp_inbox_read.md`
  - `api/mcp_server.py`

## Install hints

- Cursor: add/copy `SKILL.md` into a skill directory in your skills location.
- Claude or other hosts: import the same markdown skill files as-is.
- Use individual files when you need only one capability; use the zip for full hub install.

## Pack for public download

Run:

```bash
scripts/pack_agent_skills.sh
```

The script:

1. Validates `manifest.json` `contract_version` (`MAJOR.MINOR`).
2. Stamps `contract_version` into every `skills/**/SKILL.md` frontmatter.
3. Writes `api/mcp_contract_version.json`.
4. Copies `skills/**` into:

- `app/public/skills/`
- `linbox/public/skills/`

And builds:

- `app/public/skills/linbox-skills.zip`
- `linbox/public/skills/linbox-skills.zip`
- `linbox/public/llms.txt` (includes the contract version line)