01 · Foundation
Anatomy of a Claude Skill
A Skill is a .md file with instructions that Claude reads before executing a task. Skills don't store state between sessions — they give Claude a role, a process, and an output format. Context comes in per-conversation via documents and files.
🧠
Role & Thinking
Who Claude is in this context. How it reasons, what it prioritizes, what it refuses to guess.
BA: "Analyze requirements for contradictions and gaps — don't just record what the client said."
📥
Input Definition
What the person must bring to the conversation. Without a clear input spec, the skill produces unpredictable output.
BA: session recordings, previous docs, SOW, DoR/DoD
⚙️
Process Steps
How Claude processes input. Makes output predictable across sessions and people. Stop conditions included.
Find contradictions → ask for missing info → structure → generate sections
📤
Output Format
Exact sections, headings, depth. Most critical for consistency across team members and sessions.
BRD: Overview / Stakeholders / Requirements / AC / Risks / Open Questions
🚫
Stop Conditions
When Claude must pause and ask rather than generate. Prevents confident hallucination on incomplete input.
"If a requirement is ambiguous — ask. Do not assume or invent."
📏
Optimal Size
200–400 lines for role skills. Too short → Claude improvises. Too long → Claude gets lost in instructions.
Shared skills (templates + examples) can be longer — they're reference material
02 · Skill Types
Two Types of Skills
Skills separate into two distinct types based on scope and ownership. Role skills belong to one person. Shared skills belong to the team. Never duplicate shared logic into role skills.
🎭 Role Skill
What this role does and how it thinks
Describes reasoning, document structure, and process for a specific role. Portable across projects — a new project means a new project-context, not a new role skill.
ba-skill.md
qalead-skill.md
qa-skill.md
techlead-skill.md
manager-skill.md
devops-skill.md
dev-skill.md
designer-skill.md
🌐 Shared Skill
Team-wide conventions, not role-specific
Style guides, client communication conventions, document templates. Used by multiple roles. Invoked via @skill-name in conversation — not baked into role skills. Live in docs/.claude/skills/shared/ in the repo.
globallogic-doc.skill
globallogic-pptx.skill
jp-email.skill
jp-translation.skill
03 · Context Loading
What Goes Where
Three mechanisms for loading context into Claude. The rule: if needed in every conversation → automate it. If situational → invoke manually.
Automatic · Every conversation
Role skill content (copy from .md)
Always active, no user action needed
One per Claude Project
Automatic · Every conversation
project-context.md — project overview + references
team.md — roles, names, contacts
client.md — client profile, culture, key contacts
tech-stack.md — finalized stack + key decisions
conventions.md — commit format, git branching, naming, doc language
All set up once at Phase 00 — each file owned by one role
Manual · Per task
@globallogic-doc → when making a doc
@jp-email → when writing to client
@globallogic-pptx → when making slides
@jp-translation → when translating docs to Japanese
04 · Storage
Git Repository Structure
Skills live in the project repository alongside code. This gives versioning, PR reviews, and a single source of truth for the whole team. When a skill changes, every team member updates their Claude Project from the same file.
project-repo/
README.md
app/
ai-sdlc.html
docs/
decisions-log.md
.claude/
meta/
ai-sdlc-infrastructure.md
ai-sdlc-instructions.md
roles-claude-context.md
setup/
setup-guide.md
skill-building-guide.md
skills/
roles/
ba-skill.md
designer-skill.md
dev-skill.md
devops-skill.md
manager-skill.md
qa-skill.md
qalead-skill.md
techlead-skill.md
shared/
globallogic-doc.skill
globallogic-pptx.skill
jp-email.skill
jp-translation.skill
context/
project-context.md
team.md
client.md
tech-stack.md
conventions.md
infrastructure/
05 · Handoffs
How Context Moves Between Roles
Claude instances don't talk to each other. Handoffs happen through artifacts — files that one role generates and the next role loads into their conversation. The shared docs location (Drive, Confluence, or repo /docs) is the bridge. Gates are the triggers — when a gate passes, an artifact is ready to be picked up by the next role.
→
Shared Docs
Saves to
Drive / Confluence / /docs
→
TechLead
Loads into
conversation
→
TechLead
Generates
tech-spec.md
→
Shared Docs
Saves to
next roles pick up
Gate → Artifact trigger
| Gate |
Who saves |
Artifact |
Who picks up |
| Requirements Gate |
BA |
brd.docx |
TechLead, QA Lead, Manager |
| Architecture Gate |
TechLead |
tech-spec.md, arch-decisions.md |
BE Dev, FE Dev, Designer, DevOps, QA |
| Code Review Gate |
TechLead |
merged code + API docs |
QA Lead, QA Engineer |
| QA Gate |
QA Lead |
qa-sign-off.md, test-results |
DevOps, Manager |
| Staging Gate |
DevOps |
release-notes.md, rollback-plan.md |
Manager (final go decision) |
06 · Versioning
How Skills Are Updated
Skills version with the codebase. Changes go through PR — same discipline as code. After merge, affected team members update their Claude Project instructions manually (copy-paste from updated .md file).
1. QA Lead notices qa-skill generates test cases without edge cases
2. QA Lead updates docs/.claude/skills/roles/qa-skill.md locally
3. Opens PR → team reviews → merges
4. git tag v1.1
5. QA Lead + QA Eng copy new content → paste into Claude Project instructions
Who can update what:
Role skill → the role that owns it (PR → approver → merge)
Shared skill → any role via PR; Manager or TechLead approves (affects everyone)
project-context / team / client → Manager (on project changes)
tech-stack / conventions → TechLead (on architecture changes)
Building a skill from scratch
Follow docs/.claude/setup/skill-building-guide.md — it walks through all 5 parts with Claude, one at a time. Expect 1–2 hours for a first skill.
07 · Shared Docs
Recommended Google Drive Structure
Google Drive stores project artifacts only — no Claude skills or context files (those live in Git). Structure mirrors SDLC phases so any team member knows where to find and save documents without asking.
[Project Name]/
00_Setup/
contracts/
governance/
access/
01_Discovery/
sessions/
brd/
roadmap/
02_Design/
architecture/
test-plans/
03_Development/
status-reports/
04_Release/
release-notes/
deployment/
05_Monitoring/
incidents/
retros/
06_Closure/
knowledge-transfer/
acceptance/
lessons-learned/
08 · Onboarding
Setup Guide
Steps 1–7 are identical for every role. After completing them, find your role in the diff section below and complete only what's listed there.
Claude Products
💬 Claude Chat
claude.ai
Conversations, document generation, analysis. Base tool for all roles. Uses Claude Projects for persistent role context.
🖥️ Claude Cowork
Claude Desktop app
Multi-step tasks with local files and apps. No terminal. For recurring workflows and tasks spanning multiple files or sources.
⌨️ Claude Code
Terminal / CLI
Agentic coding at project level. Reads full codebase, plans across files, runs tests. For devs, QA, and DevOps working directly with code.
🎨 Claude Design
claude.ai/design
Creates prototypes, wireframes, slides through conversation. Reads codebase and design files to apply team's design system automatically.
✏️ GitHub Copilot
IDE extension
Inline code suggestions as you type. Complements Claude Code — Copilot handles autocomplete, Claude Code handles full task execution.
Connectors (MCP)
🔌 Ticketing MCP
All roles
Tasks, AC, sprint data, bug reports directly in Claude — no copy-paste from the ticketing system.
🔌 Figma MCP
Designer · FE Dev
Designer creates and edits components, tokens, mackets. FE Dev reads specs and assets for implementation.
🔌 Google Drive MCP
All roles
Read and write project artifacts directly from Claude — no manual file uploads per conversation.
Meta-Project Setup — one time only
Before the team can build or update role skills, one person sets up the Claude Project where framework design happens. This is separate from individual team members' implementation projects.
Files live in docs/.claude/meta/ — upload all three as Project Files, paste ai-sdlc-instructions.md as Project Instructions.
Full setup steps: docs/.claude/setup/skill-building-guide.md → Meta-Project Setup section.
Common setup — all roles
1
Get the repo
Pull the project repo. Open docs/.claude/setup/setup-guide.md — it mirrors these steps with role-specific details.
2
Create a Claude Project
claude.ai → New Project → name it after the project — use the name agreed with BA in Phase 00.
3
Project Instructions
Inside the Project → Instructions tab → paste the full contents of docs/.claude/skills/roles/[your-role]-skill.md
4
Project Files
Inside the Project → Files tab → upload all 5 files from docs/.claude/skills/context/
project-context.md · team.md · client.md · tech-stack.md · conventions.md
5
Shared Skills
claude.ai → Settings → Skills → Add skill → paste each file from docs/.claude/skills/shared/ → name = filename without .skill
globallogic-doc · globallogic-pptx · jp-email · jp-translation
6
Google Drive MCP
claude.ai → Settings → Connectors → Google Drive → Connect → authorize → select project folder
7
Smoke test
New conversation inside the Project → "What role are you in, what project are you working on, and what do you need from me to start?" → Claude should respond in your role and ask for the right inputs.
Role diff — additional setup only
@ Skills
@jp-email
@globallogic-pptx
@globallogic-doc
MCP
Ticketing MCP
Google Drive MCP — Cowork
Gmail MCP
Extra
Download Claude Desktop for Cowork. Sign in with same account. Gmail MCP: claude.ai → Settings → Connectors → Gmail → Connect.
@ Skills
@globallogic-doc
@jp-email
MCP
Ticketing MCP
Google Drive MCP — Cowork
Extra
Download Claude Desktop for Cowork. Sign in with same account.
@ Skills
@globallogic-doc
@globallogic-pptx
MCP
Ticketing MCP
Google Drive MCP
@ Skills
none — role skill covers all output
MCP
Ticketing MCP
Google Drive MCP
Figma MCP (FE only)
Extra
Claude Code:
docs.anthropic.com/claude-code — instructions per OS and IDE. Copilot: VS Code → Extensions → GitHub Copilot. Two devs, identical setup — tasks differ via the ticketing system.
@ Skills
@globallogic-pptx
@globallogic-doc
MCP
Figma MCP
Ticketing MCP
Google Drive MCP
Extra
Claude Design: claude.ai/design → Connect codebase → upload Figma exports + CSS tokens.
MCP
Ticketing MCP
Google Drive MCP
Extra
Primary tool: Chat for planning, gate decisions, test plan and UAT report generation. Claude Code for autotests code review and coverage analysis.
docs.anthropic.com/claude-code — installation instructions per OS and IDE.
@ Skills
none — role skill covers all output
MCP
Ticketing MCP
Google Drive MCP
Extra
Primary tool: Claude Code for automated test writing, execution, and bug report generation.
docs.anthropic.com/claude-code — installation instructions per OS and IDE.
@ Skills
none — role skill covers all output
MCP
Ticketing MCP
Google Drive MCP
09 · Security
What Can and Cannot Go Into Claude
The team uses claude.ai Pro — data is not used for model training. But sending sensitive data is still a risk: data in transit, potential account compromise, and client trust. These are team agreements, not technical restrictions.
🚫 Never send
Client PII — names, emails, phone numbers, personal data
Credentials — API keys, passwords, tokens, secrets
Client financial data — transactions, account numbers, balances
Client source code if NDA explicitly restricts it
Internal HR data — salaries, performance reviews
✓ Safe to send
Anonymized requirements and specifications
Team's own source code
Architecture and technical decisions
Publicly available client information
Generic business logic without sensitive context
Test data — synthetic or anonymized only
Practical rule: If you're unsure — anonymize before sending. Replace real names with placeholders, remove actual credentials, replace real financial figures with examples. Claude works just as well with anonymized input.