feat: -skill suffix convention, team sharing via GitHub/GitLab
Skills now require -skill suffix for org-wide discoverability (teams search *-skill to find all skills). Suites use -suite suffix. Post-creation sharing flow: agent detects gh/glab CLI, creates repo, adds agent-skill topic, gives shareable one-liner for Slack/Teams. Supports GitHub, GitLab, Enterprise, and self-hosted instances. Updated validate.py to warn on missing -skill suffix and error on deprecated -cskill suffix. Updated architecture-guide.md naming section to match. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
francylisboacharuto
parent
96e546ffdd
commit
1154b1d6ab
4 changed files with 173 additions and 58 deletions
70
README.md
70
README.md
|
|
@ -70,9 +70,9 @@ Skill installed successfully.
|
|||
|
||||
To use it, open a new session and type:
|
||||
|
||||
/sales-report-builder Generate the weekly report for the West region
|
||||
/sales-report-skill Generate the weekly report for the West region
|
||||
|
||||
Installed at: ~/.claude/skills/sales-report-builder
|
||||
Installed at: ~/.claude/skills/sales-report-skill
|
||||
```
|
||||
|
||||
The agent detects your platform (Claude Code, Cursor, Copilot, etc.), installs the skill to the right location, and tells you exactly how to invoke it. No manual steps.
|
||||
|
|
@ -80,8 +80,8 @@ The agent detects your platform (Claude Code, Cursor, Copilot, etc.), installs t
|
|||
The generated skill directory looks like this:
|
||||
|
||||
```
|
||||
sales-report-builder/
|
||||
├── SKILL.md # Skill definition (activates with /sales-report-builder)
|
||||
sales-report-skill/
|
||||
├── SKILL.md # Skill definition (activates with /sales-report-skill)
|
||||
├── scripts/ # Functional Python code
|
||||
├── references/ # Detailed documentation
|
||||
├── assets/ # Templates, configs
|
||||
|
|
@ -89,7 +89,7 @@ sales-report-builder/
|
|||
└── README.md # Installation instructions (for sharing with others)
|
||||
```
|
||||
|
||||
Your team installs it the same way they installed agent-skill-creator — one `git clone` — and invokes it with `/sales-report-builder`. The included `install.sh` auto-detects their platform too.
|
||||
Your team installs it the same way they installed agent-skill-creator — one `git clone` — and invokes it with `/sales-report-skill`. The included `install.sh` auto-detects their platform too.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -111,41 +111,55 @@ Every skill is automatically validated (correct structure, naming, metadata) and
|
|||
|
||||
## Share Skills Across Your Team
|
||||
|
||||
Once a skill is created, publish it so everyone can use it.
|
||||
After the agent builds and installs your skill, it asks:
|
||||
|
||||
### Publish
|
||||
|
||||
```bash
|
||||
python3 scripts/skill_registry.py publish ./sales-report-builder/ --tags sales,reports,crm
|
||||
git add registry/ && git commit -m "Add sales-report-builder skill" && git push
|
||||
```
|
||||
Want to share this skill with your team so they can install it too?
|
||||
```
|
||||
|
||||
### Discover
|
||||
Say yes. The agent detects whether your team uses GitHub or GitLab, creates a repo, pushes the skill, and gives you a one-liner to share:
|
||||
|
||||
```bash
|
||||
git pull
|
||||
python3 scripts/skill_registry.py list
|
||||
```
|
||||
Shared! Your colleagues can install it by pasting this in their terminal:
|
||||
|
||||
# NAME VERSION AUTHOR TAGS
|
||||
# sales-report-builder 1.2.0 sales-team sales, reports, crm
|
||||
# deploy-checklist 2.1.0 engineering deploy, ci, checklist
|
||||
# quarterly-compliance 1.0.0 legal-team compliance, audit
|
||||
|
||||
python3 scripts/skill_registry.py search "sales"
|
||||
python3 scripts/skill_registry.py info sales-report-builder
|
||||
git clone https://github.com/your-org/sales-report-skill.git ~/.claude/skills/sales-report-skill
|
||||
```
|
||||
|
||||
### Install
|
||||
or for GitLab teams:
|
||||
|
||||
```bash
|
||||
python3 scripts/skill_registry.py install sales-report-builder
|
||||
```
|
||||
git clone https://gitlab.com/your-org/sales-report-skill.git ~/.claude/skills/sales-report-skill
|
||||
```
|
||||
|
||||
Auto-detects your platform (Claude Code, Cursor, etc.) and installs to the right location.
|
||||
Send that line to your colleague on Slack or Teams. They paste it. Done. They can now type `/sales-report-skill` in their agent.
|
||||
|
||||
No registry commands, no publishing steps, no terminal knowledge beyond paste. The agent handles the repo creation, the push, and generates install commands for every platform. Works with GitHub, GitLab, GitHub Enterprise, and self-hosted GitLab instances.
|
||||
|
||||
### The result over time
|
||||
|
||||
Each team contributes skills from their domain. Operations teams capture runbooks. Data teams capture analysis pipelines. Finance teams capture reporting workflows. Engineering teams capture deployment processes. The organization builds a living library of operational knowledge that every agent can access.
|
||||
Each team member creates skills from their own domain and shares them. Over months the organization accumulates a library of reusable skills:
|
||||
|
||||
- Sales team shares `/sales-report-skill`
|
||||
- Engineering shares `/deploy-checklist`
|
||||
- Legal shares `/quarterly-compliance`
|
||||
- Data science shares `/customer-churn-model`
|
||||
- SRE shares `/incident-runbook`
|
||||
|
||||
Any colleague installs any skill with one `git clone`. Any agent on any platform can invoke it. Knowledge compounds instead of evaporating.
|
||||
|
||||
### For power users: the registry CLI
|
||||
|
||||
If your organization prefers a centralized catalog (browsable, searchable, versioned), the registry tooling is available:
|
||||
|
||||
```bash
|
||||
python3 scripts/skill_registry.py init --name "Acme Corp Skills"
|
||||
python3 scripts/skill_registry.py publish ./sales-report-skill/ --tags sales,reports
|
||||
python3 scripts/skill_registry.py list
|
||||
python3 scripts/skill_registry.py search "sales"
|
||||
python3 scripts/skill_registry.py install sales-report-skill
|
||||
```
|
||||
|
||||
This is optional. Most teams start by sharing `git clone` links and add the registry when the skill count grows.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -261,7 +275,7 @@ All commands use exit code `0` for success, `1` for errors. All support `--json`
|
|||
|
||||
**Skill not activating**: Check that the SKILL.md `description` field contains keywords matching your query. The description is how the agent decides when to activate the skill.
|
||||
|
||||
**Validation fails on name**: Names must be lowercase, use hyphens between words, 1-64 characters. Examples: `sales-report-builder`, `deploy-checklist`.
|
||||
**Validation fails on name**: Names must be lowercase, use hyphens between words, 1-64 characters. Examples: `sales-report-skill`, `deploy-checklist`.
|
||||
|
||||
**SKILL.md too long**: Move detailed content to `references/` files and link from the main SKILL.md.
|
||||
|
||||
|
|
|
|||
112
SKILL.md
112
SKILL.md
|
|
@ -173,10 +173,10 @@ After the skill passes validation and security scan, install it immediately on t
|
|||
|
||||
```bash
|
||||
# Example for Claude Code (user-level):
|
||||
cp -R ./sales-report-builder ~/.claude/skills/sales-report-builder
|
||||
cp -R ./sales-report-skill ~/.claude/skills/sales-report-skill
|
||||
|
||||
# Example for Cursor (project-level):
|
||||
cp -R ./sales-report-builder .cursor/rules/sales-report-builder
|
||||
cp -R ./sales-report-skill .cursor/rules/sales-report-skill
|
||||
```
|
||||
|
||||
**After installing, tell the user exactly what to do next:**
|
||||
|
|
@ -186,9 +186,9 @@ Skill installed successfully.
|
|||
|
||||
To use it, open a new session and type:
|
||||
|
||||
/sales-report-builder Generate the weekly report for the West region
|
||||
/sales-report-skill Generate the weekly report for the West region
|
||||
|
||||
The skill is installed at: ~/.claude/skills/sales-report-builder
|
||||
The skill is installed at: ~/.claude/skills/sales-report-skill
|
||||
```
|
||||
|
||||
If you cannot detect the platform, show the user how to run the install manually:
|
||||
|
|
@ -196,17 +196,100 @@ If you cannot detect the platform, show the user how to run the install manually
|
|||
```
|
||||
I couldn't auto-detect your platform. To install, run:
|
||||
|
||||
./sales-report-builder/install.sh
|
||||
./sales-report-skill/install.sh
|
||||
|
||||
Or specify your platform:
|
||||
|
||||
./sales-report-builder/install.sh --platform cursor
|
||||
./sales-report-skill/install.sh --platform cursor
|
||||
```
|
||||
|
||||
The `install.sh` inside the skill handles auto-detection, platform-specific paths, project vs user level, dry-run mode, and post-install activation instructions. It is the fallback for users who receive the skill as a package (not created in their current session).
|
||||
|
||||
The generated skill must be a self-contained package that anyone can install with `git clone` or `./install.sh` and invoke with `/skill-name` — the same way agent-skill-creator itself works.
|
||||
|
||||
### Share With Your Team (Post-Creation)
|
||||
|
||||
After installing the skill locally, always ask:
|
||||
|
||||
```
|
||||
Want to share this skill with your team so they can install it too?
|
||||
```
|
||||
|
||||
Corporate users don't know what a registry is, how to `git push`, or what `skill_registry.py` does. They just want their colleague to have the same skill. You handle everything.
|
||||
|
||||
**If the user says yes, do all of this automatically:**
|
||||
|
||||
1. **Initialize a git repo** inside the generated skill directory:
|
||||
```bash
|
||||
cd ./sales-report-skill
|
||||
git init
|
||||
git add -A
|
||||
git commit -m "feat: Initial skill — sales-report-skill"
|
||||
```
|
||||
|
||||
2. **Detect the team's git platform** and create a remote repo:
|
||||
|
||||
Check which CLI tools are available and authenticated:
|
||||
|
||||
```
|
||||
gh auth status → GitHub (github.com or GitHub Enterprise)
|
||||
glab auth status → GitLab (gitlab.com or self-hosted)
|
||||
```
|
||||
|
||||
**If `gh` is available (GitHub):**
|
||||
```bash
|
||||
gh repo create sales-report-skill --public --source=. --push
|
||||
gh repo edit --add-topic agent-skill
|
||||
```
|
||||
|
||||
**If `glab` is available (GitLab):**
|
||||
```bash
|
||||
glab repo create sales-report-skill --public --defaultBranch main
|
||||
git remote add origin <returned-url>
|
||||
git push -u origin main
|
||||
glab repo edit --topic agent-skill
|
||||
```
|
||||
|
||||
The `agent-skill` topic makes skills discoverable across the org. Teams can search `topic:agent-skill` on GitHub or filter by topic on GitLab to find all shared skills.
|
||||
|
||||
**If both are available**, check the existing git remotes in the current project to infer which platform the team uses. If the current project's `origin` points to `gitlab.com` or a GitLab instance, use `glab`. Otherwise default to `gh`.
|
||||
|
||||
**If neither is available**, tell the user:
|
||||
```
|
||||
I can't create the repo automatically. To share this skill:
|
||||
1. Create a new repo on GitHub or GitLab called "sales-report-skill"
|
||||
2. Then run:
|
||||
git remote add origin <repo-url>
|
||||
git push -u origin main
|
||||
3. Share the git clone link with your team
|
||||
```
|
||||
|
||||
3. **Give the user a shareable one-liner** they can send to colleagues:
|
||||
```
|
||||
Shared! Your colleagues can install it by pasting this in their terminal:
|
||||
|
||||
git clone <repo-url> ~/.claude/skills/sales-report-skill
|
||||
|
||||
Or for VS Code Copilot:
|
||||
|
||||
git clone <repo-url> .github/skills/sales-report-skill
|
||||
|
||||
Or for Cursor:
|
||||
|
||||
git clone <repo-url> .cursor/rules/sales-report-skill
|
||||
```
|
||||
|
||||
Use the actual repo URL from step 2 (GitHub or GitLab). The install pattern is identical regardless of git platform.
|
||||
|
||||
4. **Optionally publish to the team registry** (if the agent-skill-creator registry is available):
|
||||
```bash
|
||||
python3 scripts/skill_registry.py publish ./sales-report-skill/ --tags <auto-generated-tags>
|
||||
```
|
||||
|
||||
The goal: the user who created the skill sends a one-liner to their colleague on Slack or Teams. The colleague pastes it. Done. No registry knowledge, no `skill_registry.py`, no understanding of the spec. Just `git clone` and it works — whether the team uses GitHub or GitLab.
|
||||
|
||||
**If the user says no**, that's fine — the skill is already installed locally and working. They can always share later.
|
||||
|
||||
See `references/pipeline-phases.md` for detailed Phase 5 instructions.
|
||||
|
||||
### Generated SKILL.md Format
|
||||
|
|
@ -215,7 +298,7 @@ Every generated skill's SKILL.md must follow this structure:
|
|||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name # 1-64 chars, lowercase + hyphens, matches directory
|
||||
name: skill-name-skill # 1-64 chars, must end with -skill, matches directory
|
||||
description: >- # 1-1024 chars, activation keywords
|
||||
Description here...
|
||||
license: MIT # or appropriate license
|
||||
|
|
@ -361,14 +444,21 @@ See `references/quality-standards.md` for complete standards.
|
|||
|
||||
## Naming Convention
|
||||
|
||||
Skills use standard kebab-case naming per the Agent Skills Open Standard:
|
||||
Every generated skill name must end with `-skill`. This suffix makes skills instantly discoverable across GitHub and GitLab organizations — teams can search `*-skill` and find every skill in their org.
|
||||
|
||||
- 1-64 characters, lowercase letters, numbers, and hyphens
|
||||
**Format**: `{domain}-{objective}-skill`
|
||||
|
||||
**Rules**:
|
||||
- Must end with `-skill`
|
||||
- 1-64 characters total, lowercase letters, numbers, and hyphens
|
||||
- Must match parent directory name
|
||||
- Must not start or end with hyphen
|
||||
- Must not contain consecutive hyphens
|
||||
|
||||
Examples: `stock-analyzer`, `csv-data-cleaner`, `weekly-report-generator`
|
||||
**Examples**: `sales-report-skill`, `csv-cleaner-skill`, `deploy-checklist-skill`, `stock-analyzer-skill`
|
||||
|
||||
**Suites**: `{domain}-suite` (suites are not suffixed with `-skill` — they contain skills)
|
||||
|
||||
The `-skill` suffix also serves as a signal to the agent: when it sees a repo or directory ending in `-skill`, it knows this is installable, invocable software — not documentation or a regular project.
|
||||
|
||||
## Reference Files
|
||||
|
||||
|
|
|
|||
|
|
@ -216,36 +216,30 @@ All skill and suite names follow standard kebab-case per the Agent Skills Open S
|
|||
| Consecutive hyphens | Not allowed (`my--skill` is invalid) |
|
||||
| Directory match | The `name` field in SKILL.md frontmatter must exactly match the parent directory name |
|
||||
|
||||
### 4.2 The -cskill Suffix Is Deprecated
|
||||
### 4.2 The -skill Suffix
|
||||
|
||||
The `-cskill` suffix convention from earlier versions is **removed** as of v4.0. Do not append `-cskill` to any generated skill name.
|
||||
Every generated skill name **must end with `-skill`**. This suffix makes skills instantly discoverable across GitHub and GitLab organizations — teams can search `*-skill` and find every skill in their org.
|
||||
|
||||
| Old (deprecated) | New (standard) |
|
||||
|-------------------|----------------|
|
||||
| `article-to-prototype-cskill` | `article-to-prototype` |
|
||||
| `stock-analyzer-cskill` | `stock-analyzer` |
|
||||
| `csv-data-cleaner-cskill` | `csv-data-cleaner` |
|
||||
**Suites** use the `-suite` suffix instead (e.g., `financial-suite`). Suites contain skills but are not themselves invoked as skills.
|
||||
|
||||
If a user requests the `-cskill` suffix, inform them it is deprecated and generate the skill without it.
|
||||
The previous `-cskill` suffix convention is **deprecated**. If encountered, replace with `-skill`.
|
||||
|
||||
### 4.3 Naming Pattern
|
||||
|
||||
Use the format `domain-objective` or `domain-objective-type`:
|
||||
|
||||
```
|
||||
{domain}-{objective}[-{qualifier}]
|
||||
{domain}-{objective}-skill
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
- `stock-analyzer` -- domain: stock, objective: analyzer
|
||||
- `csv-data-cleaner` -- domain: csv-data, objective: cleaner
|
||||
- `nass-usda-agriculture` -- domain: nass-usda, objective: agriculture
|
||||
- `noaa-climate-analysis` -- domain: noaa-climate, objective: analysis
|
||||
- `financial-analysis-suite` -- complex suite covering financial analysis
|
||||
- `stock-analyzer-skill` -- domain: stock, objective: analyzer
|
||||
- `csv-data-cleaner-skill` -- domain: csv-data, objective: cleaner
|
||||
- `sales-report-skill` -- domain: sales, objective: report
|
||||
- `deploy-checklist-skill` -- domain: deploy, objective: checklist
|
||||
- `financial-suite` -- complex suite (uses `-suite`, not `-skill`)
|
||||
|
||||
**Guidelines:**
|
||||
- Be descriptive but concise
|
||||
- Prefer shorter names when possible (aim for under 30 characters)
|
||||
- Must end with `-skill` (or `-suite` for multi-skill suites)
|
||||
- Be descriptive but concise — aim for under 30 characters
|
||||
- Include the primary domain for discoverability
|
||||
- Avoid generic names like `my-skill` or `tool-1`
|
||||
|
||||
|
|
@ -269,7 +263,9 @@ def validate_skill_name(name: str) -> tuple[bool, list[str]]:
|
|||
if '--' in name:
|
||||
errors.append("Consecutive hyphens not allowed")
|
||||
if name.endswith('-cskill'):
|
||||
errors.append("The -cskill suffix is deprecated; remove it")
|
||||
errors.append("The -cskill suffix is deprecated; use -skill instead")
|
||||
if not name.endswith('-skill') and not name.endswith('-suite'):
|
||||
errors.append("Name must end with '-skill' (or '-suite' for multi-skill suites)")
|
||||
return (len(errors) == 0, errors)
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -305,8 +305,23 @@ def validate_skill(skill_path: str) -> dict:
|
|||
f"(found {len(description_value)})"
|
||||
)
|
||||
|
||||
# --- Check: -cskill suffix is deprecated ---
|
||||
if name_value is not None and name_value.endswith("-cskill"):
|
||||
errors.append(
|
||||
f"'name' uses the deprecated '-cskill' suffix. "
|
||||
f"Use '-skill' instead (found: '{name_value}')"
|
||||
)
|
||||
|
||||
# --- Warnings ---
|
||||
|
||||
# Naming convention: -skill suffix (or -suite for suites)
|
||||
if name_value is not None and len(name_value) > 0:
|
||||
if not name_value.endswith("-skill") and not name_value.endswith("-suite"):
|
||||
warnings.append(
|
||||
f"'name' should end with '-skill' for discoverability "
|
||||
f"(found: '{name_value}')"
|
||||
)
|
||||
|
||||
# Body line count
|
||||
if body is not None:
|
||||
body_lines = body.split("\n")
|
||||
|
|
|
|||
Loading…
Reference in a new issue