Building Your Own Claude Code Skills | A Step-by-Step Guide to Project-Specific AI Development Environments [2026 Edition]

Hello, this is Hamamoto from TIMEWELL. This is the sixth article in the Claude Code series.

In previous posts I have covered off-the-shelf skills ranging from the official built-ins to finance-specific skills and sharply focused community releases. That said, once you actually put skills to work in your day job, a moment inevitably comes where you want a "hand-made skill" tuned to your company or project. Legal review checkpoints, internal coding conventions, invoice format conversion. None of these get scratched properly by off-the-shelf skills.

You can build something that works by just reading the documentation. However, to reach the level where "it auto-invokes correctly," "others actually reuse it," and "you yourself can still read it in six months," there are a few knacks involved. Drawing on what has accumulated as knowledge as of April 2026, I will cover SKILL.md conventions through team-sharing operations with concrete examples.

Why Skills Help and How to Split the Work with CLAUDE.md

Before getting into Skills, I want to pin down exactly how they differ from CLAUDE.md. If this stays vague you tend to arrive at "couldn't we just use CLAUDE.md?" after writing.

CLAUDE.md is where you put permanent project context. It gets injected into the system prompt every time a session starts. If you store coding conventions, domain terminology, and forbidden actions there, Claude always factors them in when answering. It is convenient, but as it grows larger the load cost also grows, and irrelevant information ends up loaded for every task, which hurts accuracy. This was the "CLAUDE.md is getting too fat" problem that was being debated from late 2025.

Skills solve this cleanly. When you place a skill at .claude/skills/{skill-name}/SKILL.md, Claude scans only the name and description in the SKILL.md frontmatter at startup and grasps the overall catalog. Only about 100 tokens per skill land in the context here. Even if you maintain dozens of skills, the cost is essentially negligible. Then, the moment Claude decides "ah, this task needs this skill" during the conversation flow, the body of that SKILL.md (recommended to stay within 5,000 tokens) loads, and attached scripts and templates load only at execution time. This is called progressive disclosure.

The result is that CLAUDE.md should only retain "things the whole project must always respect," and individual work procedures should be carved out into Skills. Based on my feel, more than half of a typical CLAUDE.md can be moved into Skills. In fact, on this very TIMEWELL site (timewell.jp), I carved the detailed procedure for writing columns into an article-writing skill, and left only a single line in CLAUDE.md: "When writing articles, go through the article-writing skill." Readability improved dramatically.

Another major benefit of Skills is that the same SKILL.md format works beyond Claude Code. As of 2026, Cursor, Gemini CLI, Codex CLI, Antigravity, and others support SKILL.md-compatible skill loading, meaning a skill you wrote once can be reused across multiple AI coding environments. Being able to invest without worrying about vendor lock-in is a psychological relief.

How to Write SKILL.md and Designing the Frontmatter

The heart of a custom skill is the YAML frontmatter at the top of SKILL.md. If this is sloppy, the skill never auto-invokes, and it ends up as an ornament that only runs when you explicitly call /skill-name.

There are only two required fields: name and description. Simple, but 80 percent of success or failure hinges on how you design those two lines.

---
name: sql-migration-reviewer
description: Use when reviewing SQL migration files before deployment. Checks for destructive operations (DROP, TRUNCATE), missing indexes on foreign keys, and forgotten rollback scripts. Triggers on keywords "migration", "schema change", "ALTER TABLE", or when the user asks to review .sql files in db/migrations/.
---

The name doubles as a slash command, so use lowercase letters and hyphens and pick a name that expresses the role in one word. Verb-plus-object reads well. Nominalizing to sql-migration-reviewer instead of review-sql-migration makes more sense when you revisit it after forgetting what it does.

Then there is description. This is the real battlefield. As emphasized in Anthropic's official Skill authoring best practices, the description is not just a blurb but a trigger. Claude scans the descriptions of every skill at startup and keeps as candidates only the ones that match the user's utterance. In other words, a skill is never invoked in a situation that is not written in its description.

What works here is imperative voice and explicit trigger phrasing. According to an article by Ivan Seleznov [^1] where activation rates were measured across 650 trials, passive voice descriptions like "Helps you review code" achieved 77 percent activation, while imperative and negative-constraint wording like "ALWAYS invoke this skill when reviewing any code changes before committing. DO NOT write security feedback without invoking this skill first" jumped to 100 percent. Claude, like humans, prefers strong instructions to vague ones.

Another ironclad rule is write in the third person. Second-person phrasing like "You should use this when..." has been reported to fail discovery because the subject shifts when injected into the system prompt. Imperative forms like "Use when..." or "Triggers when...," or third-person singular like "This skill reviews..." are safer.

For the body (the Markdown portion), you will not go wrong following the style recommended by Anthropic's official skill-creator. Four principles cover it. First, write steps as numbered lists. Second, use the "direct command" tone ("Extract the color palette," not "You should extract..."). Third, include concrete examples. Fourth, write failure patterns alongside their remedies. Resist the urge to make it elegant prose. The right instinct is to list commands.

Implementation Examples: A Code Review Skill and a Meeting Notes Formatting Skill

Abstractions alone do not move anyone's hands, so here are two skills that actually work. Drop either into .claude/skills/{skill-name}/SKILL.md under your project root and use them immediately.

Example 1: PR Security Review Skill

For teams with an internal policy that "before committing, always examine the DIFF from a security perspective."

---
name: pr-security-review
description: ALWAYS invoke this skill before the user runs `git commit` or `git push`. Use when reviewing staged changes, PR diffs, or when the user says "レビューして" "check the diff" "before I push". DO NOT write a commit message without invoking this skill first. Checks for hardcoded credentials, SQL injection risks, XSS vectors, missing input validation, and exposed debug endpoints.
---

# PR Security Review

Review staged changes from a security perspective.

## Steps

1. Fetch the diff with `git diff --staged`
2. Check the following seven items in order
   - Hardcoded credentials (API key, password, token)
   - SQL injection exposure (queries built via string concatenation)
   - XSS exposure (unescaped values in innerHTML, dangerouslySetInnerHTML)
   - Missing authorization checks (does each API route validate session/user up front?)
   - Missing input validation (presence of zod, joi, or equivalent schema validation)
   - Debug endpoints left in (/debug, /admin/test, etc.)
   - Sensitive log leakage (console.log with tokens or personal information)
3. If issues exist, cite the file and line and report them
4. If no issues, state clearly "no security concerns found"
5. Return to the normal commit-message creation process afterward

## Output Format

Only when there are findings, return a Markdown table like this.

| Severity | File:Line | Issue | Recommended Action |
|---|---|---|---|
| High | src/api/login.ts:42 | Password logged in plaintext | Remove the log statement |

## What Not to Do

- Vague judgments like "probably fine"
- Speculation (always quote the actual code to show it exists)

The key is lining up concrete triggers like git commit, git push, and "レビューして" in the description. With this in place, Claude invokes the skill automatically the moment the user says something natural like "I'm about to push."

Example 2: Meeting Notes Formatting Skill

Skills apply outside engineering too. Consider one that formats a team meeting transcript into a fixed layout.

---
name: meeting-notes-formatter
description: Use when the user pastes raw meeting transcripts, Zoom auto-captions, or otter.ai exports. Triggers on keywords "議事録" "文字起こし" "meeting notes" "整形して" or when the user provides text over 1000 characters that contains timestamps like [10:15]. Converts raw transcripts into structured minutes with decisions, action items, and open questions.
---

# Meeting Notes Formatter

Convert raw transcripts into structured meeting minutes.

## Expected Input

Auto-transcripts from Zoom / Google Meet / otter.ai, or manual notes.
Assumes timestamps, speaker names, small talk, and backchannel utterances are mixed in.

## Conversion Rules

1. Remove all backchannel utterances ("yes," "I see," "right")
2. Standardize speaker names in `**Name:**` format
3. Always create the following three sections
   - Decisions
   - Action Items (tasks with explicit owner and due date)
   - Open Questions (unresolved points)
4. Format Action Items as `- [ ] {owner}: {content} (due: {YYYY-MM-DD})`
5. Insert time headings every 10 minutes as `## 10:00-10:10`

## Prohibitions

- Do not fabricate decisions that are not in the original
- Do not paraphrase too heavily (keep proper nouns and numbers verbatim)
- Declare at the top of the body whether small talk is kept under "small talk" or fully removed

Similar versions of both skills run internally at TIMEWELL. The meeting-notes formatting skill, applied at every weekly product standup, cut the time required to produce minutes from 25 minutes to 5 minutes. It is a quiet win, but when you annualize it, the difference is far from trivial.

If you want to consult a more comprehensive skill catalog, I also summarized built-in and community examples in Claude Code Skills 45 Selections.

Sharing Skills Across an Organization

Custom skills start functioning as team assets the moment they leave your personal folder. If you neglect operational design here, that carefully crafted skill ends up pickled in someone's ~/.claude/skills/.

There are three placement tiers. ~/.claude/skills/ for user skills, personal. .claude/skills/ for project skills, usable by anyone who clones that repository. And newly supported as of 2026, the organization skills on Team and Enterprise plans, which can be distributed in bulk from organization settings. A healthy workflow is a three-stage escalation: prototype personally, promote to project skill, and eventually adopt as a company-wide standard.

The most realistic and low-friction approach is the project-skill route, committed to GitHub. A typical repository layout looks like this:

my-project/
├── .claude/
│   ├── settings.json
│   └── skills/
│       ├── pr-security-review/
│       │   └── SKILL.md
│       ├── sql-migration-reviewer/
│       │   └── SKILL.md
│       └── meeting-notes-formatter/
│           └── SKILL.md
├── src/
└── CLAUDE.md

With this in the repository, a new team member who clones it and runs claude immediately gets every team-shared skill applied. It dramatically reduces onboarding cost.

The well-known OSS project obra/superpowers is a framework that pushes this philosophy to the extreme. It packages more than 15 skills including brainstorming, writing-plans, using-git-worktrees, subagent-driven-development, and systematic-debugging, turning the methodology for every phase of software development into a single plugin. Install it with /plugin install superpowers@claude-plugins-official. I also keep it installed for trying out sub-agent driven development. For install steps and when to use what, see the Superpowers plugin deep dive.

Organizations on Team and Enterprise plans get stronger distribution options. A member with admin privileges can upload skills from the Skills tab in organization settings, and every user in the organization automatically receives them in the "Organization" section alongside Personal and Shared. Individuals can disable them, so it is positioned as "default-on company standards" rather than forced enablement. Combined with enterprise managed settings, you can actually enforce specific skills. This fits scenarios like mandatory legal review or mandatory banned-word checks [^2].

One more thing to think about in shared operations is version management. Skill content gets updated frequently, so a ## Changelog section at the bottom of SKILL.md that tracks the revision history pays off during debugging six months later. I tag with skill-vX.Y.Z in Git.

Failure Patterns and Operational Lessons

After running custom skills for nearly a year, including my share of stumbles, I have a list of failure patterns worth sharing. Knowing them up front saves hours.

The most common failure is skills that never auto-invoke. You pour effort into the body, but no matter how the conversation unfolds, Claude never calls it. The cause is almost always the description. Overly generic wording like "Helps with code review" competes with similar skills, splitting the invocation decision. As noted earlier, making it imperative and listing concrete keywords and situations helps. When it still does not invoke, first check whether it shows up with /list-skills. If it shows up but does not trigger, suspect ambiguity in the description. Make this triage habitual.

Next most common is the mega-skill problem. You cram in every capability, and it ends up half-working in every situation. As Anthropic repeatedly emphasizes, one skill equals one responsibility is the rule. "A skill that does code review and documentation generation and test authoring" should be three separate skills. Accuracy is higher and reuse is easier. I myself built a giant "development support skill" early on and split it into three three months later. A bitter experience.

Third is the "test prompts are too clean" problem. Skill authors tend to imagine idealized user utterances, like "this is how my skill will be used." Real team members phrase things far more sloppily. "Take a look," "is this okay?," "about that DIFF earlier." A UX Planet article [^3] points out that the right verification approach is to base test prompts on actual Slack conversations, complete with elisions, typos, and casual spoken language.

Finally, once operations settle in, the role split between CLAUDE.md and Skills starts to matter. To repeat the earlier point, keep only "things the project must always respect" in CLAUDE.md, and carve individual procedures into Skills. Enforcing this separation alone improves context efficiency and accuracy.

Designing these operations as a solo engineer on the side gets tedious quickly. For cases like "turn the company's SOPs into skills and roll them out organization-wide," or "encode industry-specific compliance requirements as skills," borrowing outside expertise is a realistic option. TIMEWELL's AI consulting service WARP supports designing the skill-ification of internal operations using Claude Code and the Claude Agent SDK. For cases where you want the AI to treat internal knowledge as a first-party data source, combining this with our GraphRAG-based platform ZEROCK lets us build the underlying data layer that Skills reference, end to end.

If you want to go deeper on Skills concepts and implementation patterns, reading the Claude Code agent team construction guide alongside this piece broadens your view to include skill plus sub-agent combinations.

Wrap-Up

Claude Code Skills elegantly solve the problem of CLAUDE.md, that catch-all pocket, getting too bloated. Project-specific conventions, internal policies, industry-specific judgment criteria, the kind of "knowledge you don't use every time but absolutely want to use in specific moments," can now be slotted in without sacrificing context efficiency.

The most important thing when building your own is writing the SKILL.md description in imperative mood with a list of trigger keywords. Get that right and skills auto-invoke reliably. Beyond that, keep one skill equal to one responsibility, put them in a GitHub repository, and share with your team. In six months, the development experience will have shifted enough that you think "how did I ever work without this?"

Start with one routine task you do at least three times a week and write a single SKILL.md. It takes an hour and starts paying off the next day. My recommended starter is a PR review skill. Effects are easy to feel and team rollout is easy. A great entry point.

[^1]: Ivan Seleznov, "Why Claude Code Skills Don't Activate (650 Trials)," Medium, 2026. https://medium.com/@ivan.seleznov1/why-claude-code-skills-dont-activate-and-how-to-fix-it-86f679409af1 [^2]: Anthropic, "Provision and manage Skills for your organization," Claude Help Center, 2026. https://support.claude.com/en/articles/13119606-provision-and-manage-skills-for-your-organization [^3]: Nick Babich, "7 Rules for Creating an Effective Claude Code Skill," UX Planet, April 2026. https://uxplanet.org/7-rules-for-creating-an-effective-claude-code-skill-2d81f61fc7cd