[
    {
        "role": "user",
        "content": "I%27d%20like%20to%20better%20understand%20skills%20in%20claude%20code.%20give%20a%20good%20simple%20skill%20example%20I%20can%20try."
    },
    {
        "role": "assistant",
        "content": "Here\u2019s a simple but useful example skill you can try writing in Claude Code. First I'll walk through what a **skill** is and how it works, then I'll show you a sample skill you can build, including the files and steps. Finally I\u2019ll give some tips for making it robust and effective.\n\n---\n\n## What Are Skills in Claude Code\n\n- Skills are reusable, modular \u201cknowledge/workflow\u201d packages that Claude loads when relevant. They consist of a `SKILL.md` file (plus optional scripts, templates, assets) that define when and how Claude should use the skill. ([docs.claude.com](https://docs.claude.com/en/docs/agents-and-tools/agent-skills?utm_source=openai))  \n- You put the skill directory under `.claude/skills/<skill-name>/SKILL.md` (matched name + directory). The name must be lowercase letters, numbers, hyphens only. ([claudetemplate.com](https://claudetemplate.com/guide/claude-code-skills?utm_source=openai))  \n- The `SKILL.md` file starts with YAML frontmatter containing fields like `name`, `description`, `dependencies` (if scripts needed). Then follows instructions in Markdown \u2014 when to use the skill, step-by-step guidance, examples. ([claude.com](https://claude.com/docs/skills/how-to?utm_source=openai))  \n\n---\n\n## Simple Example: \u201cCommit Message Generator\u201d Skill\n\nThis skill helps you craft good commit messages for code changes. When you stage changes (or describe what you did), it suggests a commit message following a style guide (e.g. Conventional Commits).\n\n### Directory Structure\n\n```\n.claude/skills/\n\u2514\u2500\u2500 commit-message/\n    \u251c\u2500\u2500 SKILL.md\n    \u2514\u2500\u2500 references/\n        \u2514\u2500\u2500 style-guide.md\n```\n\n### `style-guide.md` (under `references/`)\n\nExample content:\n\n```\n# Commit Message Style Guide\n\nWe follow Conventional Commits:\n\n- `feat:` New feature\n- `fix:` Bug fix\n- `docs:` Documentation only changes\n- `chore:` Maintenance tasks\n- `refactor:` Code changes that neither fixes a bug nor adds a feature\n\nScope is optional, but if used: `type(scope): message`\n\nExamples:\n- feat(auth): add login with Google\n- fix(api): correct response when user not found\n- chore: update dependencies\n```\n\n### `SKILL.md`\n\n```markdown\n---\nname: commit-message\ndescription: Generate a good commit message based on staged changes or a summary of changes. Follows the team's Conventional Commits style.\n---\n\n# Commit Message Generator\n\n## When to use this skill\nUse when you have made code changes (in any language) and want a proper commit message that follows the conventional commits style.\n\n## Instructions\n1. Ask for a short summary of what changes have been made, or inspect \u2003\u2003the staged diffs if available.  \n2. Decide the commit `type` (feat, fix, docs, refactor, chore, etc).  \n3. Optionally decide a `scope` if there is a part of the repo affected.  \n4. Write the commit message in format: `type(scope): summary` or `type: summary` if no scope.  \n5. If the summary is long, shorten it to under 72 characters.  \n6. Provide a header and optionally a descriptive body if more context is needed.\n\n## Examples\n\n**Input:** \u201cI updated the login endpoint to include Google OAuth, fixed the token expiry bug\u201d  \n**Output:** `feat(auth): add Google OAuth login and fix token expiry`\n\n**Input:** \u201cChanged readme to include environment setup steps\u201d  \n**Output:** `docs: update README with setup instructions`\n\n## Edge cases\n- If only documentation or comments changed \u2192 `docs:`  \n- If file structure changed but no logic changed, and if it affects many modules \u2192 `refactor:`  \n- Maintenance/dependency updates \u2192 `chore:`  \n```\n\n---\n\n## How to Try It\n\n1. On your machine, in a project folder, create `.claude/skills/commit-message/` as above.  \n2. Put `SKILL.md` and `references/style-guide.md` in the correct places.  \n3. Launch Claude Code (CLI, or tool you're using). It should load the skill automatically based on prompts. ([claudeprotocol.com](https://www.claudeprotocol.com/blog/how-to-use-claude-code-with-skills?utm_source=openai))  \n4. Test it: e.g.,  \n   - \u201cHere are my staged changes: I added validation to user input and fixed a crash in profile page. Suggest a commit message.\u201d  \n   - See if Claude uses the skill and gives something like: `fix(user): add input validation and fix crash in profile`  \n\n---\n\n## Why This Example Is Useful\n\n- It\u2019s focused: one workflow, one goal. Not trying to do everything. Skills work best that way. ([claude.com](https://claude.com/docs/skills/how-to?utm_source=openai))  \n- It includes edge cases and examples, so Claude knows what good output looks like.  \n- It has references (the style guide) separate, so the main `SKILL.md` stays concise, and more detailed rules are in `references/`.  \n\n---\n\n## Extra Tips / Best Practices\n\n- Be precise in the **description**: include both _what_ the skill does, and _when_ to use it. This helps Claude detect when to load it. ([claude.com](https://claude.com/docs/skills/how-to?utm_source=openai))  \n- If you use code/scripts (e.g. parsing diffs), specify dependencies (Python version, etc.) in frontmatter. For this example we don\u2019t need them. ([claude.com](https://claude.com/docs/skills/how-to?utm_source=openai))  \n- Provide good examples and edge cases. Helps avoid unexpected weird outputs.  \n- Start simple; iterate. You might first only do summaries, later add more complex logic like looking at diffs.  \n\n---\n\nIf you\u2019d like, I can send you a downloadable folder structure for this example skill, or help you make a slightly more advanced one (e.g. combined with lint/CI rules or multi-language support). Do you want to go in that direction?"
    },
    {
        "role": "user",
        "content": "can%20I%20put%20it%20in%20%7E%2F.claude%2Fskills%20or%20only%20in%20project%27s%20.claude%2Fskills%3F"
    },
    {
        "role": "assistant",
        "content": "Yes \u2014 you **can** put the skill in both places. Claude Code supports two locations for skills, each with a different scope: personal (global) and project. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/skills?utm_source=openai))\n\nHere\u2019s how it works, and when to use each:\n\n---\n\n## Where to Put Skills\n\n| Location | Path | Scope / Who Sees It | Best Use Cases |\n|---|---|---|---|\n| **Personal (user/global)** | `~/.claude/skills/<skill-name>/SKILL.md` | Available in **all** projects on **your machine/account**. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/skills?utm_source=openai)) | Your individual workflows, personal preferences, experiments, or tools you always want. |\n| **Project-specific** | `<project-folder>/.claude/skills/<skill-name>/SKILL.md` | Only within that project; shared with anyone who clones the repo. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/skills?utm_source=openai)) | Team workflows, project-specific style guides, conventions, repeated tasks relevant only to that codebase. |\n\n---\n\n## Precedence, Discovery & Usage\n\n- Claude Code **searches both** directories by default: your personal skills folder (`~/.claude/skills/`) **and** the `.claude/skills/` folder in the current project directory. ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/skills?utm_source=openai))  \n- If two skills have the *same name* (say \u201ccommit-message\u201d) in both places, the **project skill** tends to take precedence (so you can override a personal one with a project-specific version). ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/skills?utm_source=openai))\n\n---\n\n## What That Means Practically\n\n- If you create your \u201ccommit-message\u201d skill in `~/.claude/skills/`, you\u2019ll see it in *every* project you work in. Handy if you want consistency everywhere.  \n- If you instead put it in `.claude/skills/` inside a specific repo, it\u2019s only active there \u2014 useful if you have project-specific commit message style you'd enforce only for that codebase.\n\n---\n\nIf you want, I can show you how to structure your `.claude` folder when working with multiple projects (or in a monorepo), so your skills stay organized!"
    },
    {
        "role": "user",
        "content": "can%20it%20automatically%20gather%20the%20info%20it%20needs%20for%20the%20commit%20message%3F"
    },
    {
        "role": "assistant",
        "content": "Yes \u2014 Claude Code *can* automatically gather much of the information it needs (like diffs) to generate a commit message. There are built-in git integrations and commands that inspect your staged or unstaged changes, infer types/scopes, and suggest commit messages. ([mintlify.com](https://www.mintlify.com/killlowkey/claude-code/commands/git-workflows?utm_source=openai))\n\nHere are details:\n\n---\n\n## How Claude Code Auto-Gathering Works\n\n- The `/commit` command: if you\u2019ve staged changes (via `git add`), you can run `/commit` in the Claude Code REPL. Claude reads the diff of those staged changes and generates a suitable commit message, asking for confirmation (you can edit) before it actually creates the commit. ([mintlify.com](https://www.mintlify.com/killlowkey/claude-code/commands/git-workflows?utm_source=openai))  \n- If nothing is staged, Claude may look at unstaged changes or prompt you to stage files first. ([mintlify.com](https://www.mintlify.com/nirholas/claude-code/reference/commands/git-and-code-quality?utm_source=openai))  \n- It uses context: what files changed, recent commit history, probable type (feat/fix/etc.), sometimes even project layout. ([claudelab.net](https://claudelab.net/en/articles/claude-code/claude-code-conventional-commits-auto-generation?utm_source=openai))\n\n---\n\n## How to Build a Skill that Auto-Gathers Info\n\nIf you want to build a custom skill that does this (beyond using `/commit`), here's how you can set it up:\n\n**1. Declare it to allow executing shell commands or scripts**\n\n- In your `SKILL.md` include dependencies or instructions to run `git diff` or similar via script or tool.\n\n**2. Script/Tool for diff extraction**\n\n- A script (bash, Python, etc.) that runs something like:\n\n  ```bash\n  git diff --staged > /tmp/staged.diff\n  ```\n\n- Or `git diff` for unstaged changes if desired.\n\n**3. Feed diff to Claude via the skill**\n\n- The skill can either include the diff text in the prompt, or save it to a file and have Claude load it.\n\n**4. Prompting Logic in the Skill**\n\n- The `SKILL.md` should tell Claude:\n\n  - Run the diff script to grab the changed files.\n  - Identify what type of change it is (feat/fix/docs/refactor/chore).\n  - If there\u2019s a common location/path affected (e.g. `auth/`), propose a scope.\n  - Keep commit summary under certain length.\n  - Optionally generate a description body if needed (why the changes, etc.).\n\n---\n\n## Example: Enhancing \u201cCommit Message Generator\u201d Skill to Auto-Gather Diff\n\nYou could adapt the earlier skill like this:\n\n```markdown\n---\nname: commit-message-auto\ndescription: Generate a commit message by inspecting staged diffs automatically.\ndependencies:\n  - path: ./scripts/get-diff.sh\n    type: script\n---\n\n# Commit Message Generator (Auto)\n\n## When to use this skill\nUse when you've made changes and want a good commit message without manually describing each change. The skill will inspect the git diff automatically.\n\n## Instructions\n\n1. If no changes are staged, prompt the user to stage them (or consider unstaged).\n2. Run the diff-script: `./scripts/get-diff.sh` which runs `git diff --staged`.\n3. Take the output and analyze:\n   - What files changed?\n   - What type of change: feat/fix/docs/refactor/chore\n   - If possible, pick a scope (folder/module) from the files changed.\n4. Create the commit message: `type(scope): short summary` then optionally a body with context\n5. Show the commit message to the user; let them edit if needed.\n6. If approved, run `git commit -m \"generated message\"`\n\n## Example\n\n**Diff content:**  \n_(script shows diff for changes in `src/auth/login.js` and `src/auth/token.js` Fixing invalid token error, adding expiry check)_\n\n**Output commit message:**  \n`fix(auth): validate token expiry and handle invalid token error`\n```\n\nAnd `scripts/get-diff.sh` might be:\n\n```bash\n#!/usr/bin/env bash\ngit diff --staged\n```\n\n---\n\n## Limitations & Things to Watch\n\n- Very large diffs may exceed context windows or limits in prompt size. If so, limit to file names and summaries rather than full diff.  \n- Sometimes the inference of \u201ctype\u201d or \u201cscope\u201d may be guessy; you\u2019ll want fallback if unclear (ask user).  \n- Permissions and safety: auto-running shell commands, committing automatically \u2014 good to have a confirmation step.  \n- Make sure `.gitignore` doesn\u2019t hide files you want to analyze (or explicitly include needed ones).\n\n---\n\nIf you want, I can help you build the full folder structure (with script + SKILL.md) for this skill so you can plug it in and test it."
    },
    {
        "role": "user",
        "content": "when%20in%20claude%20code%2C%20when%20I%20want%20to%20do%20a%20commit%2C%20how%20can%20I%20ensure%20this%20skill%20is%20actually%20run%3F"
    },
    {
        "role": "assistant",
        "content": "To make sure your commit-message skill *actually runs* in Claude Code when you're doing commits, you need to set it up so Claude is pretty much guaranteed to activate it. Here are several proven methods, with what to include in your skill\u2019s frontmatter and prompts, plus experimental/workaround options if automatic invocation is inconsistent.\n\n---\n\n## What Claude Code Supports\n\nFrom official documentation:\n\n- Claude loads all Skills\u2019 **metadata** (name, description, etc.) at session start. The full Skill (instructions, scripts) is only loaded when Claude decides it\u2019s relevant. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/skills?utm_source=openai))  \n- Skills can be invoked in two ways:\n  1. **Automatically by Claude** if the context matches what the Skill\u2019s description says.  \n  2. **Explicitly by the user** via slash command: `/skill-name`. ([claude-world.com](https://claude-world.com/articles/skills-guide/?utm_source=openai))  \n\n- The frontmatter field `disable-model-invocation: true` prevents automatic activation by Claude. If you want the skill always to be manual (slash only), set that. But here, you\u2019ll likely *want* automatic. ([code.claude.com](https://code.claude.com/docs/en/slash-commands?utm_source=openai))  \n\n---\n\n## How to Ensure Your Commit-Message Skill Runs\n\nHere are the best practices and setups to maximize consistent invocation:\n\n### 1. Strong, Trigger-Specific Description\n\nYour `description` in the frontmatter should explicitly say **what** the skill does *and* **when** to use it \u2014 include key phrases like:\n\n- \u201cGenerate commit message\u201d\n- \u201cWhen committing changes\u201d\n- \u201cFrom staged git diff\u201d\n- \u201cUse when writing commit message or reviewing staged changes\u201d\n\nAvoid vague descriptions like \u201cHelps with git\u201d without referencing commit or change. ([paradime.io](https://www.paradime.io/guides/claude-code-skills-plugins-rules-guide?utm_source=openai))\n\n---\n\n### 2. Leave `disable-model-invocation` Off (False or Omitted)\n\nSince that field turns off automatic invocation, make sure it is either `false` or removed. Default behavior is that Claude *can* invoke the skill automatically. ([code.claude.com](https://code.claude.com/docs/en/slash-commands?utm_source=openai))\n\n---\n\n### 3. Define Clear Trigger Patterns / `when_to_use`\n\n- Use the `when_to_use` field in your skill frontmatter to list trigger phrases or examples. This helps Claude match the skill to your request more reliably. ([code.claude.com](https://code.claude.com/docs/en/slash-commands?utm_source=openai))  \n- You might write something like:\n\n  ```yaml\n  when_to_use: |\n    Use when you're about to commit changes, have staged diffs, want a conventional commit message\n  ```\n\n---\n\n### 4. Explicit Invocation Option\n\nEven if automatic invocation sometimes misses, you can always use the slash command: `/commit-message` (or whatever your skill\u2019s name is). That forces Claude to load and execute the skill. ([claude-world.com](https://claude-world.com/articles/skills-guide/?utm_source=openai))\n\n---\n\n### 5. Use Hooks for Guaranteed Activation (if Needed)\n\nIf you find the skill still doesn\u2019t run consistently, you can use a **hook**\u2014a mechanism that monitors your input for certain keywords (like \u201ccommit\u201d, \u201cgit commit\u201d, \u201cpush changes\u201d) and then automatically suggests or triggers the skill. This is more advanced; some users build a `UserPromptSubmit` hook that detects trigger words and injects `\"Use Skill(commit-message)\"` into the prompt. ([claudefa.st](https://claudefa.st/blog/tools/hooks/skill-activation-hook?utm_source=openai))\n\n---\n\n## Example Skill Frontmatter + SKILL.md Setup\n\nHere\u2019s an example frontmatter for your commit-message skill:\n\n```yaml\n---\nname: commit-message\ndescription: Generate a conventional commit message from your staged git diff. Use this skill when you're committing changes or reviewing staged files.\nwhen_to_use: |\n  - Use when you're ready to commit code\n  - Use when you have staged changes\n  - Use when writing a commit message\ndisable-model-invocation: false\n---\n# Commit Message Skill\n\n## Instructions\n1. If there are staged changes, run `git diff --staged`.  \n2. Analyze the diff to determine:\n   - type (feat, fix, docs, refactor, etc.)\n   - optional scope (folder/module/file)\n   - short summary under <50 characters\n   - optional longer body for context\n3. Suggest a commit message: `type(scope): summary`.  \n4. Show commit message to user; allow edits.\n5. Upon confirmation, run `git commit -m \"...\"`\n```\n\n---\n\n## What to Do in Practice\n\n1. **Test:** \u2192 Make a small change, stage it, then ask Claude: *\u201cHelp me commit\u201d* or *\u201cTime to commit these changes\u201d*. See if the skill kicks in automatically.\n2. **If not triggered enough:** Use slash command `/commit-message`. That ensures it runs explicitly.\n3. **Check logs / debug mode (if available):** There may be messages about why a Skill didn't load (e.g. description mismatch or skill too ambiguous). ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/skills?utm_source=openai))\n\n---\n\nIf you want, I can help you **validate** your skill description with examples (test prompts) to make sure the automatic match works reliably for your workflow. Do you want me to suggest those examples?"
    }
]