Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jasonkneen/openclicky/llms.txt

Use this file to discover all available pages before exploring further.

Custom skills let you teach Clicky exactly how to handle any recurring workflow, tool integration, or domain-specific task. If you have a deployment pipeline Clicky consistently gets wrong, a third-party API it doesn’t know about, or an internal process you’ve explained three times already — write a skill once and Clicky will follow it every time. Skills are just text files: a YAML frontmatter block followed by freeform markdown instructions.

​
The SKILL.md Format

Every skill, whether bundled or custom, is a SKILL.md file with this structure: 
---
name: my-skill
description: "Brief trigger description that tells Clicky when to use this skill."
version: 1.0.0
argument-hint: "[what the user should provide]"
author: Your Name
license: MIT
metadata:
  openclicky:
    tags: [Tag1, Tag2, Tag3]
    related_skills: [other-skill-name]
---

# My Skill — Human-Readable Title

Body instructions in plain markdown. Write as if you're briefing a capable engineer
who has never done this task before but is smart enough to follow clear runbook-style instructions.

​
Frontmatter Fields Explained

name

Machine identifier. Use kebab-case. This is what other skills reference in related_skills. Keep it short and unambiguous.

description

The most important field. Clicky matches user requests against this string semantically. Write a precise trigger: “Use when the user asks to…” or state the action directly.

version

Semantic version string (MAJOR.MINOR.PATCH). Increment when you make meaningful changes so you can track which version is running.

argument-hint

Short placeholder shown in the OpenClicky UI, e.g. "[task or auth setup]". Tells the user what context to provide alongside the skill trigger.

tags

Array of keyword tags under metadata.openclicky.tags. Used for discovery and grouping in Settings → Agents.

related_skills

Array of name values for complementary skills. Helps Clicky chain skills intelligently — e.g. listing github-auth as related to a GitHub skill means Clicky will check auth state first.

​
Writing Clear Trigger Descriptions

The description field is what Clicky reads when deciding whether your skill applies to a user request. A weak description means your skill is never activated or activated for the wrong tasks. Weak trigger descriptions: 
description: "Helps with deployment stuff."
description: "AWS things."
description: "Use for database work."
Strong trigger descriptions: 
description: "Deploy a Next.js app to an AWS S3 + CloudFront stack using the project's Makefile targets."
description: "Query and update records in the company's internal PostgreSQL database using psql."
description: "Run the full CI check suite locally before pushing: lint, type-check, unit tests, integration tests."
Look at how bundled skills write their descriptions. github-issues uses: “Create, triage, label, assign GitHub issues via gh or REST.” — specific tools named, specific actions listed. That’s the pattern to follow.
Effective descriptions:
  • Name the specific tools or APIs involved (gh, gog, curl, psql)
  • List the key actions (create, triage, label — not just “manage”)
  • Include the trigger phrase Clicky should recognise (“Use when the user asks to…”)
  • Stay under 200 characters

​
Writing the Skill Body

The body is freeform markdown. Clicky reads it before starting the task. Write it like a runbook: step-by-step, with concrete commands, and explicit decision rules for edge cases.

​
Prerequisites Section

Start with what must be true before the skill can run: 
## Prerequisites

- `MY_API_KEY` must be set in your environment
- The project must have a `deploy.config.json` at root
- Run `npm run build` first if `dist/` doesn't exist

### Checking prerequisites

```bash
echo $MY_API_KEY
ls deploy.config.json
ls dist/


### Instructions Section

Give step-by-step instructions. Be specific about tool calls, command shapes, and what to check after each step:

```markdown
## Deploy Flow

1. **Read the config** — parse `deploy.config.json` to find the target environment:
   ```bash
   cat deploy.config.json | python3 -c "import json,sys; c=json.load(sys.stdin); print(c['target'])"
  1. Run the deploy — use the project’s Makefile, not direct AWS CLI calls: 
    make deploy TARGET=<target_from_config>
  2. Verify — check the deploy URL responds with HTTP 200: 
    curl -s -o /dev/null -w "%{http_code}" https://your-domain.example.com/health
  3. Report — tell the user the URL and the deploy duration. 

### Safety Rules

Every skill that touches external state should have explicit safety rules. Look at how bundled skills do this — `google-workspace-gogcli` has an entire "Safety defaults" section:

```markdown
## Safety

- Prefer read-only commands unless the user explicitly asks to write
- For destructive actions (delete, overwrite, send), confirm the exact target first
- Never send to production unless the user says "production" explicitly — default to staging
- If the API returns an unexpected status code, stop and report it; don't retry silently

​
Transport Details

If your skill calls an API or local service, document the transport explicitly. Here’s the pattern from openclicky-screen-control: 
## Transport

Local HTTP bridge:

    http://127.0.0.1:32123

Health check:

    curl -s http://127.0.0.1:32123/health

All calls use Content-Type: application/json. The bridge does not require auth.

​
Placing a Custom Skill

OpenClicky looks for learned/custom skills in your OpenClickyLearnedSkills/ directory. Each skill must live in its own subdirectory named after the skill’s name field.
1

Create the skill directory

mkdir -p "$HOME/Library/Application Support/OpenClicky/OpenClickyLearnedSkills/my-skill"
2

Write the SKILL.md file

nano "$HOME/Library/Application Support/OpenClicky/OpenClickyLearnedSkills/my-skill/SKILL.md"
Paste your skill content and save.
3

Verify OpenClicky sees it

Open OpenClicky and ask Clicky: “What skills do you have available?” Your skill’s name should appear in the list. Alternatively, check Settings → Agents for the new skill toggle.
4

Test the trigger

Send a message that should match your skill’s description. Watch whether Clicky activates the right skill. If it doesn’t match, refine the description field and retry.
You don’t need to restart OpenClicky after adding a skill file — Clicky picks up changes from the filesystem on each request.

​
Learned Skills: Auto-Generated from Log Analysis

You don’t always need to write skills manually. OpenClicky can generate them for you by analysing conversation logs. The learn-from-openclicky-logs bundled skill reads your recent conversation JSONL logs, identifies repeated multi-step workflows, and drafts SKILL.md files for them. The generated skills follow the same format as hand-written ones and are saved directly to your OpenClickyLearnedSkills/ directory. To trigger this manually:
  • Tell Clicky: “Review my logs and learn from them.”
  • Or: “Find patterns in my logs and create skills for them.”
Clicky will:
  1. Read recent conversation history (bounded log scan — it won’t read everything)
  2. Identify workflows that appeared more than once
  3. Draft a SKILL.md for each pattern
  4. Save the files and report back with the skill names and trigger descriptions
Review the generated skills before relying on them — they’re good starting points but may need refinement.

​
Optimizing Existing Skills

The optimize-openclicky-skills bundled skill improves skills based on how they’ve performed in practice. It reads log evidence, identifies cases where a skill’s instructions led to incorrect or inefficient behavior, and proposes targeted edits.
Always archive before overwriting. The safe protocol for updating any skill — bundled or learned — is to copy the current SKILL.md to SKILL.md.bak before overwriting it. If the new version performs worse, you can restore from the backup.
To run skill optimization:
  • Tell Clicky: “Optimize my skills based on how they’ve been performing.”
  • Or: “Audit the github-issues skill and improve it.”
Clicky will propose diffs to the skill body. Review them, approve the changes, and Clicky will write the updated SKILL.md.

​
Manual Optimization Pattern

For hand-editing a skill: 
# 1. Archive the current version
cp SKILL.md SKILL.md.bak

# 2. Edit the skill
nano SKILL.md

# 3. If the update degrades performance, restore
cp SKILL.md.bak SKILL.md

​
Worked Example: A Custom Deployment Skill

Here is a complete, realistic SKILL.md based on the patterns you see throughout the bundled skills: 
---
name: staging-deploy
description: "Deploy the current branch to the team's staging environment using the project Makefile and report the preview URL. Use when the user says deploy to staging, push to staging, or wants to see changes on staging."
version: 1.0.0
author: Your Name
license: MIT
metadata:
  openclicky:
    tags: [Deployment, Staging, Makefile, Preview]
    related_skills: [vercel-deploy, github-pr-workflow]
---

# Staging Deploy

Deploy the current git branch to the team's staging environment.
Reports the resulting preview URL and deploy duration.

## Prerequisites

- The working directory must be the project root (has `Makefile` and `package.json`)
- `STAGING_TOKEN` must be set in the environment
- The branch must be pushed to GitHub (not just committed locally)

### Check prerequisites

```bash
ls Makefile package.json
echo "Token set: $([ -n "$STAGING_TOKEN" ] && echo yes || echo NO - set STAGING_TOKEN)"
git status --short
git log --oneline -1
If STAGING_TOKEN is missing, stop and tell the user to add it to ~/.config/openclicky/secrets.env, then retry.

​
Deploy Flow

  1. Confirm the branch and check for uncommitted changes: 
    git branch --show-current
git status --short
    If there are uncommitted changes, ask the user: “You have uncommitted changes. Deploy anyway, or commit first?”
  2. Run the staging deploy target: 
    make deploy-staging 2>&1 | tee /tmp/deploy-output.log
    This uses the project’s Makefile, not direct provider CLI calls. Timeout: 5 minutes. If it times out, report the last 20 lines of output.
  3. Extract the preview URL from output: 
    grep -o 'https://[^ ]*staging[^ ]*' /tmp/deploy-output.log | tail -1
  4. Verify the deploy is live: 
    URL=$(grep -o 'https://[^ ]*staging[^ ]*' /tmp/deploy-output.log | tail -1)
curl -s -o /dev/null -w "%{http_code}" "$URL/health"
    A 200 means the deploy succeeded. Anything else — report the status and the full /tmp/deploy-output.log.
  5. Report to the user:
    • Preview URL
    • Branch and commit SHA deployed
    • Deploy duration (check make output for timing)
    • Any warnings from the build log

​
Safety

  • Never run make deploy-production unless the user explicitly says “production”.
  • Do not force-push the branch as part of this workflow.
  • If the health check returns non-200, do not declare success. Report the failure.
  • If make deploy-staging exits non-zero, stop immediately and show the error output.

This skill demonstrates the key patterns:
- Precise `description` with explicit trigger phrases
- Concrete prerequisite checks with shell commands
- Step-by-step flow with exact commands and expected output
- Explicit safety rules for irreversible actions
- A clear reporting step so the user knows what happened

The same structure works for API integrations, data pipelines, testing workflows, or any other repeatable process.

Build docs developers (and LLMs) love

Get started for freeTalk to us