Skills Architecture — gilesparnell / Parnell Systems

Where skills live

📚

Two formats, three locations

Every skill exists in two forms serving different purposes: a runtime file that Claude Code reads when the skill is invoked, and a portal stub that the GitHub Pages site renders as a card. These are not duplicates — they're different formats with different jobs.

global runtime

~/.claude/skills/<slug>/SKILL.md

Loaded automatically in every Claude Code session, regardless of which project you're in. Use for craft skills that apply universally — code review, git conventions, testing practices.

code-review/
git-conventions/
testing-practices/
frontend-design/
skill-publisher/

project runtime

[project]/.claude/skills/<slug>/SKILL.md

Loaded only when Claude Code is opened inside that specific project. Use for skills that reference a particular stack, client system, or domain — things that would trigger incorrectly elsewhere.

fsca/.claude/skills/
frontend-design/
parnell-systems/.claude/skills/
saas-patterns/

portal stub

~/Claude/skills/<slug>/SKILL.md

Frontmatter-only. Rendered as a card on this GitHub Pages portal. Not read by Claude Code at runtime — this is purely the display layer. All skills (global and project-scoped) get a portal stub here.

code-review/
saas-patterns/
github-pages-portal/
skill-publisher/

Global vs project-scoped

⚒

The one-question test

Ask: "Would this skill give correct, useful guidance on a completely unrelated project?" If yes — global. If no — project-scoped. When in doubt, start project-scoped. A skill that triggers on the wrong project is worse than one that doesn't trigger automatically.

Signal	Scope	Reason
It's a craft skill — review, git, testing, design principles	~/.claude/skills/	These apply to every project. Universal quality bars benefit from being always-on.
It references a specific library, API, or file path	[project]/.claude/skills/	e.g. `lib/ai.ts`, Twilio webhooks, Stripe plan IDs. Would be noise — or wrong — anywhere else.
It contains a client's brand colours, domain rules, or business logic	[project]/.claude/skills/	Client-specific context must stay in the client repo, not leak into all sessions.
Its trigger phrases are generic ("add a feature", "design this API")	[project]/.claude/skills/	Broad triggers cause false positives on unrelated work. Keep scoped to where the context is valid.
It encodes a process you run on every engagement	~/.claude/skills/	e.g. PR review process, commit message format. These should be consistent everywhere.
It was built for one client but proved useful on others	~/.claude/skills/	Graduate it. Remove or neutralise the client-specific parts first.

The 7-section skill template

📄

Runtime SKILL.md structure

The runtime file is what Claude Code reads when a skill is invoked. It should be written as direct instructions to Claude — not documentation for humans. Sections 1–4 are required. Sections 5–7 add precision and robustness.

---
name: your-skill-slug
description: Use this skill when [trigger condition]. Triggers on '[phrase 1]', '[phrase 2]'.
---

# Skill Title

## When to Use
## Context
## Process
## Output Format
## Guardrails
## Standalone Mode
  

0 Frontmatter — name and description required

name is the slug — lowercase, hyphenated, matches the folder name. description is the most important field: it's what Claude Code uses for trigger matching. Write it as a sentence starting with "Use this skill when…" and include 2–4 example trigger phrases in single quotes. Specific phrases beat vague ones — 'review this PR' is better than 'review'.

1 When to Use required

List exact trigger conditions and explicit exclusions. This helps Claude decide when not to apply the skill as much as when to use it. Include: trigger phrases, the kind of request this handles, and 1–2 "do NOT trigger when" cases to prevent false positives. Example: "Do NOT trigger for general code questions unrelated to shipping."

2 Context recommended

Why this skill exists. What problem or failure mode prompted it — a correction, a repeated mistake, a hard-won rule. This section isn't instruction; it's background. It helps Claude understand the intent behind the rules, which matters when edge cases arise. A few sentences is enough. Example: "This skill exists because early PRs shipped without test coverage. The review process now enforces it."

3 Process required

The actual instructions. What Claude should do, in what order, with what rules. Be specific and directive — write in imperative form ("Check X before Y", "Always include Z"). Use numbered steps for sequential processes, bullet lists for checklists or rules. This is the heart of the skill.

4 Output Format recommended

How the response should be structured. Markdown format, section headers, length guidance, tone. Example: "Return findings as a markdown checklist grouped by severity (blocking / suggestion / nit). Keep explanations to one sentence per item." Without this, Claude will choose a format — with it, the output is consistent and scannable.

5 Guardrails recommended

What NOT to do. Explicit prohibitions that prevent common failure modes. Example: "Do not refactor code that wasn't part of the PR. Do not suggest architectural changes unless the PR introduces an obvious structural problem." Guardrails are especially valuable for skills that touch sensitive areas — code review, design feedback, security analysis.

6 Standalone Mode optional

How to invoke this skill explicitly when it hasn't been triggered automatically, or when working outside the normal project context. Useful for skills that are occasionally needed in isolation — include a minimal invocation prompt. Example: "To use outside of a PR context: paste the diff and say 'apply code-review skill to this'."

Writing a skill from scratch

Identify the pattern

A skill worth writing is a correction you've made twice, a rule you've explained to Claude more than once, or a process that should be consistent every time. If you're typing the same instructions into a session, that's a skill. If Claude keeps getting something wrong in a specific context, that's a skill.

Decide scope

Apply the one-question test: would this give correct guidance on an unrelated project? Global goes to ~/.claude/skills/. Project-specific goes to [project]/.claude/skills/. Default to project-scoped when unsure — you can always promote it later.

Choose a slug

Lowercase, hyphenated, descriptive. The slug becomes the folder name, the portal card identifier, and part of the trigger surface. payment-webhooks is better than payments. Avoid generic slugs like coding or api — they'll conflict with everything.

Write the runtime SKILL.md

Start with the frontmatter — nail the description field first, as it drives trigger matching. Then write the 7 sections. Focus on Process and Guardrails — these are what determine whether the skill actually works. Save to the correct scope location under the slug folder.

Test the trigger

Open a new Claude Code session in the right directory. Say one of your trigger phrases. Check the session context to confirm the skill loaded. Refine the description trigger phrases if it doesn't fire — this is the most common failure mode.

Write the portal stub

Create a frontmatter-only SKILL.md in ~/Claude/skills/<slug>/. Include: title, category, icon, description (one sentence), triggers (2–4 phrases), checks-label, checks (4 maximum — curate ruthlessly), version. This is the portal display card.

Commit and verify the portal

Add the portal stub to git, commit with feat: add <slug> skill, push to gilesparnell/Claude. The GitHub Action regenerates the portal pages automatically. Check the Actions tab to confirm the run succeeded, then verify the card appears on the Skills page.

Common mistakes

🚫

Vague trigger phrases

The description field drives trigger matching. "Use when coding" is useless. "Use when the user says 'review this PR', 'adversarial review', or 'prepare for review'" is precise. If a skill never fires, the description is why.

🚫

Putting project skills in global

A skill with trigger phrases like "add a new feature" or "design this API" will fire on every project if placed in ~/.claude/skills/. SaaS-specific patterns, client brand rules, and stack-specific skills must stay in the project repo.

🚫

Confusing portal stubs with runtime files

The files in ~/Claude/skills/ are portal display stubs — frontmatter only. Claude Code does not read them at runtime. If a skill isn't working, check that the runtime SKILL.md exists in the correct scope location, not just the portal stub.

🚫

Too many checks in the portal stub

Portal stubs allow up to 4 check items. More than 4 clutters the card and dilutes the signal. Force yourself to pick the 4 most important points — this constraint is a feature, not a limitation.