diff --git a/.claude/rules/skills-contributing.md b/.claude/rules/skills-contributing.md new file mode 100644 index 0000000..8553dc3 --- /dev/null +++ b/.claude/rules/skills-contributing.md @@ -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//` 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. diff --git a/AGENTS.md b/AGENTS.md index 87f130b..2fdfd9b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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//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. diff --git a/CLAUDE.md b/CLAUDE.md index 7332a48..450c207 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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