External/agent-skills
1
0
Fork 0
mirror of https://github.com/addyosmani/agent-skills.git synced 2026-08-12 18:07:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: route new-skill work through CONTRIBUTING pre-flight checks

Browse Source 
Add anti-duplication guardrails so agents working in this repo follow the CONTRIBUTING.md pre-flight checklist before adding a skill, keeping CONTRIBUTING.md as the single source of truth instead of duplicating it.

- CLAUDE.md: add a Contributing pointer plus a pre-flight Boundaries rule
- AGENTS.md: replace the stale "Creating a New Skill" section (the repo has no per-skill zips and scripts are optional) with a pointer to CONTRIBUTING.md and docs/skill-anatomy.md
- .claude/rules/skills-contributing.md: path-scoped rule (skills/**) that loads the dedup guardrail only when editing skills
This commit is contained in:
Joan Leon
2026-06-22 19:07:03 +02:00
parent 17214a29c4
commit 0066dafbd8
3 changed files with 23 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/rules/skills-contributing.md
+15
View File
@@ -0,0 +1,15 @@
---
description: Anti-duplication guardrail for adding or changing skills
paths:
- "skills/**"
---
# Adding or changing a skill
This repo already covers most of the development lifecycle, so most new-skill ideas overlap an existing skill or an open PR. Before creating a new `skills/<name>/` directory or significantly reworking an existing one:
- Run the pre-flight checks in [CONTRIBUTING.md](../../CONTRIBUTING.md#before-proposing-a-new-skill): search the catalog, check open PRs (`gh pr list --state open`), and justify the gap.
- Prefer extending an existing skill over adding a near-duplicate. If the idea overlaps an existing skill, edit that skill instead of adding a new directory.
- Keep the `SKILL.md` within [docs/skill-anatomy.md](../../docs/skill-anatomy.md), and never duplicate content between skills, reference the other skill instead.
CONTRIBUTING.md is the single source of truth for the full workflow; this rule points to it rather than restating its checklist.
AGENTS.md
+3 -102
View File
@@ -83,107 +83,8 @@ See [docs/agents.md](docs/agents.md) for the decision matrix and [references/orc
## Creating a New Skill
### Directory Structure
> **Before you start:** run the pre-flight checks in [CONTRIBUTING.md](CONTRIBUTING.md#before-proposing-a-new-skill), search the catalog, check open PRs (`gh pr list --state open`), confirm the idea fits [docs/skill-anatomy.md](docs/skill-anatomy.md), and justify the gap in your PR description. Most new-skill ideas overlap an existing skill or an open PR; prefer extending an existing skill over adding a near-duplicate. CONTRIBUTING.md is the single source of truth for this workflow.
```
skills/
{skill-name}/ # kebab-case directory name
SKILL.md # Required: skill definition
scripts/ # Required: executable scripts
{script-name}.sh # Bash scripts (preferred)
{skill-name}.zip # Required: packaged for distribution
```
Skills in this repo are markdown-first: each lives at `skills/<kebab-case-name>/SKILL.md` with YAML frontmatter (`name`, `description`) and follows the section anatomy (Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification). Add a `scripts/` directory only when the skill ships runnable helpers; most skills are markdown only, and there are no per-skill zip packages.
### Naming Conventions
- **Skill directory**: `kebab-case` (e.g. `web-quality`)
- **SKILL.md**: Always uppercase, always this exact filename
- **Scripts**: `kebab-case.sh` (e.g., `deploy.sh`, `fetch-logs.sh`)
- **Zip file**: Must match directory name exactly: `{skill-name}.zip`
### SKILL.md Format
```markdown
---
name: {skill-name}
description: {One sentence describing what the skill does, followed by one or more "Use when" trigger conditions. Include trigger phrases like "Deploy my app" or "Check logs" when helpful.}
---
# {Skill Title}
{Brief overview of what the skill does and why it matters.}
## How It Works
{Numbered list explaining the skill's workflow}
Equivalent headings like `Workflow`, `Core Process`, or `When to Use` are fine when they communicate the same structure clearly.
## Usage (Optional)
Include this section only if the skill ships runnable helpers under `scripts/`. Markdown-only skills can omit both the section and the directory entirely.
```bash
bash /mnt/skills/user/{skill-name}/scripts/{script}.sh [args]
```
**Arguments:**
- `arg1` - Description (defaults to X)
**Examples:**
{Show 2-3 common usage patterns}
## Output
{Show example output users will see}
## Present Results to User
{Template for how Claude should format results when presenting to users}
## Troubleshooting
{Common issues and solutions, especially network/permissions errors}
```
### Best Practices for Context Efficiency
Skills are loaded on-demand — only the skill name and description are loaded at startup. The full `SKILL.md` loads into context only when the agent decides the skill is relevant. To minimize context usage:
- **Keep SKILL.md under 500 lines** — put detailed reference material in separate files
- **Write specific descriptions** — helps the agent know exactly when to activate the skill
- **Use progressive disclosure** — reference supporting files that get read only when needed
- **Prefer scripts over inline code** — script execution doesn't consume context (only output does)
- **File references work one level deep** — link directly from SKILL.md to supporting files
### Script Requirements
- Use `#!/bin/bash` shebang
- Use `set -e` for fail-fast behavior
- Write status messages to stderr: `echo "Message" >&2`
- Write machine-readable output (JSON) to stdout
- Include a cleanup trap for temp files
- Reference the script path as `/mnt/skills/user/{skill-name}/scripts/{script}.sh`
### Creating the Zip Package
After creating or updating a skill:
```bash
cd skills
zip -r {skill-name}.zip {skill-name}/
```
### End-User Installation
Document these two installation methods for users:
**Claude Code:**
```bash
cp -r skills/{skill-name} ~/.claude/skills/
```
**claude.ai:**
Add the skill to project knowledge or paste SKILL.md contents into the conversation.
If the skill requires network access, instruct users to add required domains at `claude.ai/settings/capabilities`.
For the full format, naming conventions, frontmatter rules, supporting-file thresholds, and writing principles, see [docs/skill-anatomy.md](docs/skill-anatomy.md), the single source of truth for skill structure. Do not restate that guidance here, link to it.
CLAUDE.md
+5
View File
@@ -31,6 +31,10 @@ docs/ → Setup guides for different tools
- References are in `references/`, not inside skill directories
- Supporting files only created when content exceeds 100 lines
## Contributing
Before adding a new skill or significantly reworking an existing one, run the pre-flight checks in [CONTRIBUTING.md](CONTRIBUTING.md#before-proposing-a-new-skill): search the catalog, check open PRs, confirm the idea fits [docs/skill-anatomy.md](docs/skill-anatomy.md), and justify the gap. Prefer extending an existing skill over adding a near-duplicate. CONTRIBUTING.md is the single source of truth for this workflow; do not restate its checklist here or elsewhere, link to it.
## Commands
- `npm test` — Not applicable (this is a documentation project)
@@ -38,6 +42,7 @@ docs/ → Setup guides for different tools
## Boundaries
- Always: Run the CONTRIBUTING.md pre-flight checks before creating a new skill directory
- Always: Follow the skill-anatomy.md format for new skills
- Never: Add skills that are vague advice instead of actionable processes
- Never: Duplicate content between skills — reference other skills instead