166 lines
6.7 KiB
Markdown
166 lines
6.7 KiB
Markdown
---
|
|
name: skills-sync
|
|
description: >
|
|
Manages syncing, updating, and sharing Claude skills via Helloprint's Gitea repositories
|
|
using the Gitea MCP server. Use this skill whenever a user mentions: syncing skills, updating
|
|
skills, pulling new skills, pushing skill changes, sharing a skill, publishing a skill,
|
|
"my skills are outdated", "get latest skills", "save my skill changes", "skill sync",
|
|
"skill update", or any reference to git operations in the context of Claude skills.
|
|
This skill is designed for non-technical users who should never need to understand git commands directly.
|
|
---
|
|
|
|
# Skills Sync (Gitea MCP)
|
|
|
|
A friendly skill that handles all git operations for Claude skills behind the scenes using
|
|
the **Gitea MCP server**. The user should never need to type a git command — Claude does
|
|
everything via MCP tools and explains what happened in plain language.
|
|
|
|
## Important Principles
|
|
|
|
1. **Never show raw git output** to the user unless they ask for it or something goes wrong
|
|
2. **Use simple language**: "download latest changes" not "git pull", "save your work" not "commit"
|
|
3. **Always confirm before pushing** — the user should approve before changes go to the team
|
|
4. **Protect secrets** — never commit `.env` files or anything matching secret patterns
|
|
5. **Use Gitea MCP tools** — all operations go through the Gitea MCP server (mcp__gitea__*), not git CLI
|
|
|
|
## Backend: Gitea MCP
|
|
|
|
All skill repositories are hosted on Helloprint's self-hosted Gitea instance. The Gitea MCP
|
|
server runs locally on the user's machine via stdio, bypassing any VM network restrictions.
|
|
|
|
**Instance URL**: `https://gitea-6ac7y-u39382.vm.elestio.app`
|
|
**Organization**: `claude-skills`
|
|
|
|
### Helloprint Value Chain Repositories
|
|
|
|
Repos are organized around Helloprint's 8 core value chain processes:
|
|
|
|
| Process | Lead | Repository |
|
|
|--------------------------------|----------------|-------------------------------------|
|
|
| (Shared — everyone) | — | claude-skills/skills-shared |
|
|
| Sell Products & Services | Niels / Erwin | claude-skills/skills-sell-products |
|
|
| Add Products | Rick | claude-skills/skills-add-products |
|
|
| Source & Deliver Products | Rick | claude-skills/skills-source-deliver-products |
|
|
| Serve Customers | Lennaert | claude-skills/skills-serve-customers|
|
|
| Drive Value Through Technology | Dan | claude-skills/skills-drive-value |
|
|
| Get Paid & Be Compliant | Sven | claude-skills/skills-get-paid |
|
|
| Build the Best Team | Lizzy | claude-skills/skills-build-team |
|
|
| Steer the Future | Lennaert | claude-skills/skills-steer-future |
|
|
|
|
### Web Interface
|
|
|
|
To browse skills online:
|
|
```
|
|
https://gitea-6ac7y-u39382.vm.elestio.app/claude-skills/skills-{process}
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The sync config is stored in `.skills-sync.json` in the user's skills folder. It contains:
|
|
- Backend type (`gitea-mcp`)
|
|
- Gitea instance URL and organization
|
|
- List of repos with access levels
|
|
- User info (name, email)
|
|
- Secret patterns to exclude from commits
|
|
|
|
## Core Operations (via Gitea MCP Tools)
|
|
|
|
### 1. Get Latest Skills ("sync" / "update")
|
|
|
|
**Trigger phrases**: "update my skills", "get latest", "sync", "are my skills up to date?"
|
|
|
|
Use `mcp__gitea__get_file_content` and `mcp__gitea__get_dir_content` to check for changes
|
|
in each configured repo. Compare with local files and download any updates.
|
|
|
|
**Tell the user**:
|
|
- "Your skills are up to date!"
|
|
- If there were updates: "Updated skills: [list skill folder names that changed]"
|
|
|
|
### 2. Save & Share Changes ("push" / "share" / "publish")
|
|
|
|
**Trigger phrases**: "save my changes", "share this skill", "push my updates", "publish"
|
|
|
|
**Steps**:
|
|
|
|
1. Compare local files with repo versions using `mcp__gitea__get_file_content`
|
|
2. Summarize changes: "You've modified the **order-tracking** skill and created a new **supplier-outreach** skill."
|
|
3. **Ask for confirmation**: "Would you like to share these changes with your team?"
|
|
4. Check for secrets before pushing (see Security section)
|
|
5. If confirmed, use `mcp__gitea__create_file` (new files) or `mcp__gitea__update_file` (changed files)
|
|
6. Tell the user: "Your changes are now shared with the team!"
|
|
|
|
### 3. Check Status
|
|
|
|
**Trigger phrases**: "what's changed", "skill status", "any updates available"
|
|
|
|
Compare local files against repo contents. Summarize:
|
|
- Local changes not yet shared
|
|
- Updates available from the team
|
|
- When the last sync happened (from `.skills-sync.json`)
|
|
|
|
### 4. View History
|
|
|
|
**Trigger phrases**: "who changed this skill", "what changed recently", "skill history"
|
|
|
|
Use `mcp__gitea__list_repo_commits` to get recent commits. Present as a readable timeline:
|
|
"Recent changes to **Sell Products** skills:
|
|
- Niels updated lead-qualifier (2 days ago)
|
|
- Anna added quote-generator (5 days ago)"
|
|
|
|
### 5. Create New Skill
|
|
|
|
**Trigger phrases**: "create a new skill", "add a skill"
|
|
|
|
1. Ask which process repo it belongs to
|
|
2. Create the skill folder with SKILL.md
|
|
3. Use `mcp__gitea__create_file` to push to the appropriate repo
|
|
4. Confirm: "Your new skill is now available to the team!"
|
|
|
|
## Security: Handling Secrets
|
|
|
|
### Pre-push Secret Check
|
|
|
|
**ALWAYS run this before any push.** Scan file contents for:
|
|
|
|
- API keys, tokens, passwords
|
|
- Private keys (BEGIN ... KEY)
|
|
- Bearer tokens
|
|
- Service-specific tokens (OpenAI sk-, GitHub ghp_, GitLab glpat-, Slack xox*)
|
|
|
|
**If secrets are found**:
|
|
1. **STOP** — do not push
|
|
2. Tell the user: "I found what looks like a secret key in [filename]. I won't share this."
|
|
3. Suggest: "Move secrets to a `.env` file (which is git-ignored) or use the company's secret manager."
|
|
|
|
### .gitignore
|
|
|
|
Every skills repo should have:
|
|
```
|
|
.env
|
|
.env.*
|
|
*.key
|
|
*.pem
|
|
*.secret
|
|
*credentials*
|
|
.skills-sync.json
|
|
__pycache__/
|
|
.DS_Store
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
| Error | User-friendly message |
|
|
|-------|----------------------|
|
|
| MCP tool not available | "The Gitea connection isn't set up. Check that the Gitea MCP server is configured in Claude Desktop." |
|
|
| Auth failed | "I can't authenticate with Gitea. Your access token may need refreshing." |
|
|
| Repo not found | "The skills repo doesn't seem to exist. Can you double-check with your process lead?" |
|
|
| Permission denied | "You don't have permission to share changes to this repo. It might be read-only for your role." |
|
|
| File conflict | "Someone else also updated this file. Here's what's different: [summary]. Which version should we keep?" |
|
|
|
|
## Tone Guide
|
|
|
|
- "I'll download the latest skills from your team" (not "git pull from origin")
|
|
- "Save and share your changes" (not "commit and push")
|
|
- "Someone else also edited this file" (not "merge conflict detected")
|
|
- "Your skills are up to date!" (not "Already up to date.")
|