Why Claude Code Skills?
Every product team has tasks they repeat constantly. Writing PRDs. Documenting design system components. Creating QA checklists. Drafting release notes. And every time, you're feeding the same context into a tool that's already forgotten everything from last week.
Current AI tools are fast, but they're stateless. You open a new conversation, paste your template, re-explain your product architecture, remind it about your team's conventions, and hope the output is close enough. Multiply that by every PM, designer, and engineer on your team, and you've got a serious context tax.
Claude Code skills solve this. A skill is a reusable set of instructions that encodes your team's process, templates, and product knowledge into something Claude Code can execute on demand. Build it once, push it to your repo, and every team member gets the same quality and consistency without the setup.
We recently built one to automate PRD creation from conversation transcripts. It went from raw transcript to fully detailed PRD (with Linear issues auto-created) in about six minutes. But PRDs are just one example. Anything your team does more than twice with a predictable structure is a candidate.
Key takeaways
- A Claude Code skill is a reusable folder of markdown instructions that gives Claude Code persistent context for a specific task type. Build it once, your whole team uses it.
- Skills connect to your actual codebase. Unlike other AI tools, a skill can research your repo, reference real architecture, and generate output grounded in what's already built.
- You don't need to be a developer to build one. Skills are written in markdown. If you can describe a process clearly, you can build a skill.
- Skills are shareable and versionable. Push to your repo, create a PR, and the whole team stays on the same version.
- They're extensible. Connect to Linear, Jira, Slack, or any tool with an MCP integration to chain actions together.
Table of contents:
- What is a Claude Code skill?
- Why build custom Claude Code skills?
- What can you build with Claude Code skills?
- How to build a custom Claude Code skill, step by step
- Real example: a PRD skill for cal.com
- Tools and resources
- Frequently asked questions
What is a Claude Code skill?
A Claude Code skill is a reusable folder of markdown instructions and supporting resources that gives Claude Code persistent context for a specific type of task. Instead of re-prompting from scratch every time, the skill tells Claude Code exactly what to do, what standards to follow, and what context to reference. Automatically.
Think of it as onboarding a new team member. When someone joins your team, you give them context: here's how we do things, here's our standards, here's what good looks like. A skill does exactly that, but for AI. Build it once, and every time you or anyone on your team invokes it, Claude Code already has the context it needs.
A skill folder typically contains:
- A
skill.mdfile with instructions (the "brain" of the skill) - One or more template files with your preferred formats and guidance
- Optional context files with product-specific knowledge, conventions, or reference material
The key difference between a skill and a one-off prompt is durability. A prompt is a conversation. A skill is institutional knowledge.
Claude Code skills vs. custom GPTs
Custom GPTs give you a persistent persona and some uploaded context, but they live inside ChatGPT's interface and can't touch your codebase. A Claude Code skill runs in your terminal, connected to your actual repo. It can read your code, understand your architecture, and generate artifacts that reflect what's already built, not just what you described in a system prompt.
Claude Code skills vs. prompt templates
Prompt templates are static. You paste them in, fill in the blanks, and hope the output is close enough. Skills are dynamic. They can research your codebase before generating output, ask clarifying questions, and adapt to the specific context of each request. A template gives you a starting point. A skill gives you a process.
Claude Code skills vs. Claude Projects
Claude Projects (on claude.ai) let you upload reference documents and set a system prompt for web-based conversations. Claude Code skills run in your terminal, connected to your actual codebase. The skill can research your repo, reference real architecture, and generate files directly. It's not limited to what you manually uploaded, and it lives in version control so your whole team can use it.
Why build custom Claude Code skills?
If you're at a funded B2B SaaS startup (say, 6 to 18 months post-funding), your team is shipping fast and context is expensive. Every hour someone spends re-explaining product architecture to an AI tool is an hour not spent on the actual work. According to a 2024 Pragmatic Institute survey, product managers spend roughly 30% of their time on documentation and alignment tasks, and that time compounds across every feature cycle.
The real problem isn't speed. Most AI tools are already fast. The problem is context loss. When your tools don't know your codebase, your team's standards, or your definition of "done," every output needs heavy editing. You end up doing the thinking twice.
Skills fix this in three ways:
- Context is loaded once, not every time. Your product architecture, standards, and templates are baked into the skill. No more pasting the same background into every conversation.
- Output reflects your actual product. Because the skill connects to your codebase, it generates output grounded in real code, real architecture, and real constraints. Not hypotheticals.
- The whole team ships from the same playbook. Push the skill to your repo and everyone gets the same quality, format, and depth. No more "it depends on who wrote it."
Building a good skill takes an initial investment, maybe an hour or two of back-and-forth with Claude Code to get the instructions and templates right. But once it's built, the returns compound every time someone on your team uses it.
What can you build with Claude Code skills? {#use-cases}
Anything your team does repeatedly with a predictable structure. Here are some of the highest-value use cases we've seen:
Product documentation
PRDs, feature specs, technical design docs. Feed in a meeting transcript or a rough outline, and the skill outputs a fully structured document in your team's format, referencing the actual codebase for architecture context.
Design system maintenance
Adding new components to your design system means documenting props, usage guidelines, accessibility considerations, and code examples. A skill can generate all of this from a component file, following your team's documentation conventions.
QA and testing workflows
Generate test plans, acceptance criteria, or regression checklists based on a feature spec or PR diff. The skill knows your testing standards and can reference existing test patterns in the repo.
Release notes and changelogs
Pull commit history and PR descriptions, then generate release notes in your team's format. The skill handles the formatting and categorization so no one has to do it manually.
Sprint and project management
Turn a PRD or feature spec into project management issues (Linear, Jira, etc.) with proper labels, dependencies, and assignments. We did exactly this with MCP and it cut the gap between "decision made" and "work started" down to minutes.
Onboarding content
Generate onboarding documentation, architecture overviews, or codebase walkthroughs that stay current because the skill reads the actual repo instead of relying on stale docs.
The common thread: if someone on your team does it more than twice and it follows a pattern, it should probably be a skill.
How to build a custom Claude Code skill, step by step
You don't need to be a developer to build a skill. If you can describe a process clearly and have opinions about what the output should look like, you have everything you need.
We'll walk through the general process here, then show a concrete example in the next section.
1. Define the task and gather your inputs
Start by identifying the repeatable task and pulling together the materials the skill will need:
- Your template or format. Whatever structure your team already uses for this type of output. If you don't have one, that's fine. Claude Code can help you create one during the skill-building process.
- Your standards and conventions. Style guides, naming conventions, quality criteria. Anything that defines "what good looks like" for your team.
- Product context. For a repo-connected skill, Claude Code will research the codebase directly. But any additional context (architectural decisions, product principles, glossaries) makes the output sharper.
- The Claude Code skills documentation. Link to the official docs so Claude Code understands the skill format it needs to produce.
2. Prompt Claude Code in planning mode
Start with a clear role and structured instructions. Here's the general shape:
> You are a [role]. Create a skill that [does X] based on [input type].
Step 1: Read the Claude Code skills documentation.
Step 2: Understand [your product]'s structure.
Step 3: Here are the standards and best practices we follow.
Step 4: Plan out how you will create the skill.
The key is that last step. By asking Claude Code to plan first, you enter planning mode. It'll ask clarifying questions before building anything:
- Where should the output files be saved?
- What input formats should the skill accept?
- Should the skill be committed to the project repo for the whole team, or kept personal?
This back-and-forth is where the quality happens. Don't rush through it.
3. Review the generated skill files
Claude Code will produce the skill folder with your core files:
skill.md: The brain. Contains all instructions for how to handle the task from start to finish.- Template files: Your output format with guidance for each section.
- Context files: Product-specific knowledge, conventions, or reference material.
Read each file carefully. This is where you'll catch gaps. Maybe the template is too detailed (or not detailed enough), or the context is missing a key decision. It's much easier to fix the instructions now than to debug bad output later.
4. Test with real input
Don't test with a made-up example. Use real, messy input. A real meeting transcript, a real feature request, a real PR diff. That's the actual stress test.
Invoke the skill, provide your input, and evaluate whether the output:
- Reflects your actual product, not generic filler
- Follows your template structure
- Includes insights that go beyond what was explicitly in the input
- References real code and architecture where relevant
If something's off, tell Claude Code directly. "The implementation section should reference specific files" or "The tone is too formal for our team." Iterate on the skill itself, not the individual output.
5. Extend with tool integrations
Once the core skill works, think about what happens after the output. Claude Code skills can connect to external tools through MCP (Model Context Protocol):
- Linear or Jira: Auto-create issues from a generated spec
- Slack: Post a summary to a channel after generating a doc
- Notion: Push the output directly into your team's workspace
- GitHub: Create a PR with the generated files
To add an integration, just describe it: "After generating the output, I want the skill to create issues in Linear." Claude Code updates the skill.md with the new step, and the next run includes it.
6. Share with your team
When the skill is ready, push it to your repo. Every team member who pulls the latest code can invoke it immediately.
A few things to keep in mind:
- Version it like code. Create PRs for skill updates so the team can review changes.
- Keep iterating. Skills should evolve as your process does. Someone finds a gap? Fix the skill, push the update.
- Document the invocation. A quick note in your README or team wiki on how to use the skill goes a long way.
Real example: a PRD skill for cal.com
To make all of this concrete, here's how we built a PRD skill for cal.com, the open-source scheduling platform.
The goal
Take a conversation transcript about a new feature and output a PRD that understands cal.com's product, architecture, and standards, not a generic template with blanks filled in.
What we fed into the skill-building process
- The Claude Code skills documentation
- Cal.com's existing PRD template and standards
- PRD best practices from Lenny's Newsletter and Marty Cagan
- A prompt asking Claude Code to plan the skill before building it
What Claude Code produced
Three files:
skill.md: Instructions to read the input transcript, research the cal.com codebase, load the PRD template, generate the document, and present a summary.template.md: A detailed PRD structure covering problem statement, personas, goals, non-goals, implementation guidance, metrics, and validation criteria.cal-context.md: Everything about cal.com's product, architecture, and conventions in one file for quick reference.
Testing it
We invoked the skill with a real transcript from a feature discussion about conversational onboarding. Claude Code didn't just summarize the conversation. It researched the existing onboarding code, cross-referenced what was already built, and generated a PRD that included:
- Current state analysis of the onboarding flow
- Key insight that activation isn't about completing onboarding, it's about creating a first event type and getting a booking
- Detailed personas (individual users, founders, ops leaders) and anti-personas
- Implementation guidance referencing actual code architecture
- Hypothesis validation framework with primary KPIs and release criteria
Full PRD generated in approximately 6 minutes. Zero re-explaining of product context because the skill already knew cal.com.
Extending it
After the PRD worked, we added Linear integration in a single conversation: "I want the skill to create issues in Linear after we finalize the PRD." Claude Code updated the skill.md, added the Linear step, and the next run auto-created a project with issues and dependency chains. The team could start picking up work immediately after reviewing the PRD.
Tools and resources
Here's what we used and recommend for building custom Claude Code skills:
- Claude Code: The CLI tool that runs skills in your terminal, connected to your codebase [EXTERNAL LINK: Claude Code documentation]
- Claude Code skills documentation: Official docs on skill format and structure [EXTERNAL LINK: Claude Code skills docs]
- Lenny's Newsletter PRD guide: Strong PRD best practices if you're building a PRD skill specifically [EXTERNAL LINK: Lenny's Newsletter]
- Marty Cagan on PRDs: Foundational thinking on what makes a good PRD [EXTERNAL LINK: SVPG]
- Linear MCP: Model Context Protocol integration for auto-creating issues from Claude Code [EXTERNAL LINK: Linear MCP]
If your team is spending more time explaining context to AI tools than actually making product decisions, that's the exact problem custom skills solve. At TDP, we help B2B SaaS teams build these kinds of workflows, converting messy, repetitive processes into repeatable systems that ship faster. [INTERNAL LINK: TDP services]
Frequently asked questions
How long does it take to build a Claude Code skill?
Expect one to two hours for the initial build, including gathering your inputs, going through planning mode, and testing with real data. The PRD skill we built for cal.com took about 90 minutes from first prompt to working output. After that, each invocation takes minutes, not hours.
Do you need to know how to code to build a Claude Code skill?
No. Skills are written in markdown, not code. If you can describe your process clearly and define what good output looks like, you can build a skill. Claude Code handles the technical implementation. You provide the domain knowledge and quality standards.
Can you share Claude Code skills with your team?
Yes. Skills live in your project repo. Once you push the skill files, anyone on the team who pulls the latest code can invoke it. This means the whole team operates from the same playbook, without each person having to set things up individually.
What's the difference between Claude Code skills and Claude Projects?
Claude Projects (on claude.ai) let you upload reference documents and set a system prompt for web-based conversations. Claude Code skills run in your terminal, connected to your actual codebase. The skill can research your repo, reference real architecture, and generate files directly. It's not limited to what you manually uploaded, and it lives in version control.
Can Claude Code skills connect to external tools?
Yes. Through MCP (Model Context Protocol), skills can connect to Linear, Jira, Slack, Notion, GitHub, and any other tool with an MCP integration. In our PRD example, we connected to Linear to auto-create issues directly from the generated document.
How do you update a Claude Code skill after it's been shared?
The same way you update any code. Make changes to the skill files, test the output, create a PR, and push. Everyone who pulls the latest version gets the update. Treat skills like living documentation, not static templates.
Start building
The PRD skill is just one example of what's possible. Anything repeatable (design system docs, QA checklists, release notes, sprint planning, onboarding guides) can become a skill. Build it once, share it with your team, and stop re-explaining context that your tools should already know.
Want to try the PRD skill we built? Check the link below to request access. From there, you can customize it to your product and connect it to your own project management tools.
