Agent Skills: Creating Modular Capabilities for Claude
Agent Skills represent one of the most powerful mechanisms for extending the capabilities of Claude Code. They are competency modules that add specialized knowledge and predefined workflows to the agent, enabling it to perform complex tasks that go well beyond simple code generation.
In this thirteenth article in the series, we will explore the architecture of skills, the ten main categories with real-world examples from the community, and learn how to create custom skills for our specific workflows. Skills transform Claude Code from a generic assistant into a team of specialized experts available in the terminal.
What You Will Learn
- Understand the architecture and structure of Agent Skills
- Explore the 10 main categories of available skills
- Install and configure skills from the community
- Create custom skills step by step
- Integrate skills into the daily development workflow
- Apply best practices for designing effective skills
- Manage dependencies and conflicts between multiple skills
- Build reusable skill libraries for the team
Complete Series Overview
| # | Article | Focus |
|---|---|---|
| 1 | Claude as Technical Partner | Setup and first steps |
| 2 | Context and Project Setup | CLAUDE.md and configuration |
| 3 | Ideation and Requirements | MVP and user personas |
| 4 | Backend and Frontend Architecture | Spring Boot and Angular |
| 5 | Code Structure | Organization and conventions |
| 6 | Advanced Prompt Engineering | Advanced techniques |
| 7 | Testing and Quality | Strategies and test generation |
| 8 | Professional Documentation | README, API, ADR |
| 9 | Deploy and DevOps | Docker, CI/CD, monitoring |
| 10 | Evolution and Maintenance | Refactoring and scalability |
| 11 | Real Project Integration | Claude Code in production |
| 12 | Claude Code CLI | Commands and configuration |
| 13 | Agent Skills (you are here) | Modular capabilities |
| 14 | Specialized Subagents | Role-specific agents |
| 15 | Hooks and Automation | Event-driven workflows |
| 16 | Ralph Wiggum Method | Autonomous iterative dev |
| 17 | BMAD Method | AI-driven agile |
| 18 | Multi-Agent Orchestration | Agent pipelines |
| 19 | Claude Cowork | AI for knowledge workers |
| 20 | Security and Privacy | Best practices |
| 21 | Monitoring and Productivity | Metrics and dashboards |
1. Agent Skills Architecture
An Agent Skill is a Markdown file placed in the project's
.claude/skills/ directory. Each file describes a specific competency
that Claude can invoke when the conversation context requires it.
Unlike subagents (which we will cover in the next article), skills are not
autonomous entities but rather knowledge extensions that enrich the capabilities
of the main agent.
Directory Structure
.claude/
skills/
document-generator.md # Skill for document generation
api-tester.md # Skill for API testing
database-migration.md # Skill for DB migrations
code-review-checklist.md # Skill for code review
performance-analyzer.md # Skill for performance analysis
security-audit.md # Skill for security audit
csv-data-analyzer.md # Skill for CSV data analysis
deployment-validator.md # Skill for deployment validation
agents/ # Subagents (article 14)
commands/ # Custom slash commands
settings.json # Project configuration
settings.local.json # Local configurationAnatomy of a Skill
Each skill file follows a predefined structure that Claude interprets automatically. The structure includes the skill name, a description of its capabilities, operating instructions, and usage constraints.
# Skill Name
## Description
Brief description of what this skill does and when it is activated.
## Capabilities
- Capability 1: what it can do
- Capability 2: what it can do
- Capability N: what it can do
## Instructions
Detailed instructions on how to execute the task:
1. Step 1
2. Step 2
3. Step N
## Constraints
- Do not do X
- Prefer Y over Z
- Expected output format
## Examples
### Example 1: [Title]
Input: ...
Output: ...
### Example 2: [Title]
Input: ...
Output: ...How Claude Selects Skills
Claude analyzes the user's prompt and conversation context to
determine which skills are relevant. Selection happens automatically
based on the semantic match between the request and the descriptions
of available skills. It is not necessary to explicitly invoke a skill:
simply formulate a request that falls within its domain of competence.
To invoke a specific skill, you can use the
/skill skill-name command.
Skill Lifecycle
Lifecycle Phases
| Phase | Description | Claude Action |
|---|---|---|
| Discovery | Claude scans .claude/skills/ at startup |
Loads metadata from all available skills |
| Matching | Semantic analysis of the user prompt | Identifies relevant skills for the request |
| Loading | Full loading of the selected skill | Reads instructions, constraints, and examples |
| Execution | Application of the skill's instructions | Executes the task following the guidelines |
| Validation | Verification of the result against constraints | Checks that the output meets the defined criteria |
2. The 10 Skill Categories
The community has developed hundreds of skills organized into ten main categories. Each category covers a specific domain and offers ready-to-use competencies that can be adopted immediately in your own projects.
Category 1: Document Skills
Document Skills allow Claude to create, modify, and convert documents into professional formats. These skills transform Claude into a structured content generator that produces output ready for distribution.
Main Document Skills
| Skill | Format | Capabilities |
|---|---|---|
| docx-generator | Microsoft Word (.docx) | Generates Word documents with styles, tables, images, and automatic table of contents |
| pdf-creator | Creates professional PDFs with custom layout, header/footer, and watermark | |
| pptx-builder | PowerPoint (.pptx) | Generates presentations with slide master, charts, and animations |
| xlsx-analyzer | Excel (.xlsx) | Creates spreadsheets with formulas, pivot tables, and charts |
| revealjs-presenter | HTML (Reveal.js) | Generates interactive web presentations with transitions and live code |
# Document Generator (DOCX)
## Description
Generates professional Microsoft Word documents from structured
content. Supports custom styles, tables, inline images,
headers/footers, and automatic table of contents.
## Capabilities
- Create .docx documents from scratch with a professional template
- Apply consistent formatting styles
- Insert tables with structured data
- Generate automatic table of contents from headings
- Insert header and footer with page numbering
- Support multilingual content
## Instructions
1. Analyze the structure of the requested content
2. Create the Node.js script using the `docx` library
3. Define document styles (heading, body, table)
4. Build the document structure section by section
5. Execute the script to generate the .docx file
6. Verify that the file was created correctly
## Dependencies
- npm: docx (for .docx generation)
- npm: @types/docx (for TypeScript)
## Constraints
- Always use consistent styles in the document
- Include page numbering in the footer
- Date format: DD/MM/YYYY for Italian documents
- Maximum recommended size: 50 pagesCategory 2: Development & Code Tools
Development skills extend Claude's coding capabilities with advanced patterns, framework-specific knowledge, and structured work methodologies. These skills are particularly useful for maintaining consistency and quality in generated code.
Main Development Skills
| Skill | Technology | Capabilities |
|---|---|---|
| web-artifacts-builder | HTML/CSS/JS | Generates self-contained web components with inline HTML, CSS, and JavaScript |
| tdd-workflow | Multi-language | Guides Test-Driven Development: write tests first, then implementation |
| git-worktrees | Git | Manages Git worktrees for parallel development on multiple branches |
| aws-cdk-builder | AWS CDK | Generates CDK stacks with best practices for cloud infrastructure |
| api-design-first | OpenAPI | Designs APIs starting from the OpenAPI specification, generates server and client |
| angular-component-gen | Angular | Generates standalone Angular components with signals, tests, and storybook |
# TDD Workflow
## Description
Guides development by strictly following the Red-Green-Refactor cycle
of Test-Driven Development. Every feature is implemented starting
from tests that describe the expected behavior.
## Capabilities
- Write tests that define the desired behavior (Red)
- Implement the minimum code to make the tests pass (Green)
- Refactor the code while keeping all tests green (Refactor)
- Handle unit, integration, and e2e tests
- Apply test doubles (mock, stub, spy) where needed
## Instructions
### Red Phase
1. Analyze the requirement and break it down into testable behaviors
2. Write a test that describes the expected behavior
3. Run the test and verify that it FAILS
4. If the test already passes: the test is not testing anything new
### Green Phase
5. Write the MINIMUM code needed to make the test pass
6. Do not optimize, do not add extra features
7. Run all tests and verify that they ALL PASS
### Refactor Phase
8. Refactor the code by eliminating duplication
9. Improve naming and structure
10. Run all tests after each change
11. Tests must remain GREEN after refactoring
## Constraints
- NEVER write production code without a test that requires it
- One test at a time, one feature at a time
- Tests must be independent of each other
- Test naming: should_[behavior]_when_[condition]Category 3: Data & Analysis
Data analysis skills transform Claude into a data analyst capable of exploring datasets, generating complex queries, producing visualizations, and identifying anomalies in data.
Main Data and Analysis Skills
| Skill | Domain | Capabilities |
|---|---|---|
| root-cause-tracing | Debugging | Systematic root cause analysis of complex bugs with causal diagram |
| csv-data-summarizer | CSV datasets | Exploratory analysis, descriptive statistics, correlations, and anomalies |
| postgresql-query-builder | PostgreSQL | Generates optimized queries with indexes, CTEs, window functions, and explain plans |
| log-analyzer | Application logs | Parsing and analysis of logs with pattern recognition and event timelines |
| metrics-dashboard | Monitoring | Generates Grafana/Prometheus configurations from business requirements |
# CSV Data Summarizer
## Description
Analyzes CSV files to produce comprehensive statistical reports with
visualizations, correlations, and anomaly identification.
## Capabilities
- Load and parse CSV files of any size
- Calculate descriptive statistics (mean, median, mode, standard deviation)
- Identify missing values, duplicates, and outliers
- Generate correlations between numeric variables
- Produce visualizations with ASCII charts or Python/matplotlib scripts
- Create structured reports in Markdown format
## Instructions
1. Read the CSV file and identify the columns
2. Classify columns: numeric, categorical, dates, text
3. For each numeric column:
- Calculate min, max, mean, median, std dev
- Identify outliers (IQR method)
- Verify distribution
4. For each categorical column:
- Count unique values and frequencies
- Identify dominant values
5. Calculate correlation matrix for numeric columns
6. Identify temporal patterns (if dates are present)
7. Generate a report with all findings
## Output Format
```markdown
# Analysis Report: [file_name]
## Dataset Overview
- Rows: N, Columns: M
- Missing values: X%
## Statistics by Column
[table for each column]
## Significant Correlations
[matrix and insights]
## Detected Anomalies
[anomaly list with explanation]
```Category 4: Scientific & Research
Scientific skills bring advanced domain competencies such as bioinformatics, materials simulation, and research data analysis. They are designed for researchers and technical teams working with scientific data.
Scientific Domain Skills
| Skill | Domain | Capabilities |
|---|---|---|
| bioinformatics-pipeline | Bioinformatics | DNA/RNA sequence analysis, alignment, gene annotation |
| ml-experiment-tracker | Machine Learning | ML experiment tracking with metrics, hyperparameters, and comparisons |
| materials-simulation | Materials science | Materials property simulation with computational models |
| statistical-analysis | Statistics | Statistical tests, regression, analysis of variance, and confidence intervals |
Category 5: Writing & Research
Writing and research skills assist in creating high-quality technical content, from extracting information from web sources to drafting complete articles with citations and references.
Writing and Research Skills
| Skill | Function | Capabilities |
|---|---|---|
| article-extractor | Content extraction | Extracts and structures content from web URLs, PDFs, and documents |
| content-research-writer | Research and writing | In-depth research on a topic and production of original content |
| technical-blog-writer | Technical blog | Drafts technical articles with code, diagrams, and clear explanations |
| changelog-generator | Release notes | Generates changelogs from Git commits with automatic categorization |
# Changelog Generator
## Description
Generates professional changelogs from Git commit history.
Automatically categorizes changes following Conventional Commits.
## Capabilities
- Analyze commits between two tags/versions
- Categorize: feat, fix, docs, refactor, perf, test, chore
- Generate Keep a Changelog format
- Link related commits and issues/PRs
- Detect breaking changes
- Support semantic versioning (SemVer)
## Instructions
1. Identify the commit range (last tag -> HEAD)
2. Parse each commit message for type and scope
3. Group by category
4. Sort by importance (breaking > feat > fix > others)
5. Generate the CHANGELOG.md document
6. Suggest the new SemVer version
## Output Format
```markdown
# Changelog
## [1.2.0] - 2026-02-14
### Breaking Changes
- **auth:** Removed compatibility with v1 tokens
### Features
- **user:** Added profile edit form (#123)
- **notif:** Push notification system (#145)
### Bug Fixes
- **cart:** Fixed total calculation with discounts (#167)
### Performance
- **api:** Cache on /products endpoint (-40% latency)
```Category 6: Learning & Knowledge
Learning skills transform Claude into a knowledge management system that can organize, connect, and present information in a structured and incremental way.
Learning and Knowledge Skills
| Skill | Function | Capabilities |
|---|---|---|
| tapestry | Knowledge Graph | Creates networks of interconnected documents with bidirectional links and navigation |
| ship-learn-next | Iterative learning | Ship-Learn-Improve cycle: release, analyze feedback, improve |
| concept-mapper | Concept maps | Generates concept maps from text and technical documentation |
| learning-path-builder | Learning paths | Creates personalized learning paths with resources and milestones |
Category 7: Media & Content
Media skills allow Claude to work with video, audio, and digital publishing formats, extending its capabilities beyond text alone.
Media and Content Skills
| Skill | Format | Capabilities |
|---|---|---|
| youtube-transcript | YouTube | Extracts transcripts from YouTube videos, generates summaries and structured notes |
| video-downloader | Video | Downloads videos from supported platforms with quality selection |
| epub-converter | EPUB | Converts Markdown or HTML content to EPUB format for e-readers |
| podcast-notes | Audio | Generates structured notes from podcast transcripts with timestamps |
| diagram-generator | Mermaid/PlantUML | Generates technical diagrams from natural language descriptions |
# Diagram Generator
## Description
Generates technical diagrams in Mermaid or PlantUML format
from natural language descriptions or code analysis.
## Capabilities
- Sequence diagrams from code flows
- Class diagrams from domain models
- ER diagrams from database schemas
- State diagrams from state machines
- Flowcharts from business logic
- C4 architecture diagrams
## Instructions
1. Analyze the request or source code
2. Identify the most appropriate diagram type
3. Extract entities, relationships, and flows
4. Generate the Mermaid/PlantUML code
5. Save to a .md or .puml file
6. If possible, generate an ASCII preview
## Mermaid Format
```mermaid
sequenceDiagram
participant U as User
participant A as API
participant DB as Database
U->>A: POST /login
A->>DB: SELECT user
DB-->>A: User data
A-->>U: JWT Token
```
## Constraints
- Prefer Mermaid for simplicity
- Use PlantUML for complex diagrams
- Always include a legend if the diagram has more than 5 entities
- Maximum 20 entities per diagram (split if necessary)Category 8: Health & Life Sciences
Life sciences skills assist healthcare professionals and researchers in analyzing medical data, reading clinical reports, and conducting biomedical research. These skills always operate with the caveat that they do not replace professional medical advice.
Life Sciences Skills
| Skill | Domain | Capabilities |
|---|---|---|
| claude-ally-health | Medical reports | Analyzes medical reports, highlights abnormal values, and suggests follow-ups |
| clinical-trial-analyzer | Clinical trials | Analysis of clinical trial protocols and results with structured summaries |
| pharma-interaction-checker | Pharmacology | Checks drug interactions based on public databases |
Important Disclaimer
Healthcare skills are support tools and do not in any way replace the advice of a medical professional. Every analysis produced must be verified by qualified personnel before any clinical decision. Claude Code is not a certified medical device.
Category 9: Collaboration & PM
Collaboration and project management skills integrate Claude with work management tools such as Linear, Jira, and meeting analytics systems. They allow automating task management, sprints, and reporting.
Collaboration and PM Skills
| Skill | Tool | Capabilities |
|---|---|---|
| linear-integration | Linear | Creates and manages issues, cycles, and projects on Linear via API |
| jira-workflow | Jira | Syncs tasks, updates statuses, and generates sprint reports on Jira |
| meeting-analytics | Meeting notes | Analyzes meeting notes, extracts action items, and assigns responsibilities |
| sprint-planner | Agile | Plans sprints based on velocity, capacity, and backlog priorities |
| standup-reporter | Daily standup | Generates standup reports from commits, PRs, and tasks completed in the last 24h |
# Meeting Analytics
## Description
Analyzes meeting notes to extract decisions, action items,
risks, and participation metrics. Generates structured reports
and tracks follow-up actions over time.
## Capabilities
- Parse free-form meeting notes
- Extract decisions made and their rationale
- Identify action items with owner and deadline
- Detect mentioned risks and impediments
- Calculate participation metrics
- Generate follow-up emails with summaries
- Track open actions across successive meetings
## Output Format
```markdown
# Meeting Report - [Date]
## Participants
[List with role]
## Decisions
1. [Decision] - Rationale: [why]
2. ...
## Action Items
| # | Action | Owner | Deadline | Status |
|---|--------|-------|----------|--------|
| 1 | ... | @name | DD/MM | Open |
## Identified Risks
- [Risk] - Impact: [high/medium/low]
## Next Meeting
- Date: [suggested]
- Agenda: [proposed topics]
```Category 10: Security & Web Testing
Security skills equip Claude with penetration testing, vulnerability assessment, and security audit competencies. These skills follow recognized standards such as OWASP and produce reports that comply with compliance requirements.
Security and Testing Skills
| Skill | Standard | Capabilities |
|---|---|---|
| owasp-checklist | OWASP Top 10 | Systematic verification of OWASP Top 10 vulnerabilities on web applications |
| ffuf-fuzzer | Web fuzzing | Configures and runs fuzzing sessions with FFUF for endpoint and parameter discovery |
| secure-env-manager | Secrets management | Secure management of environment variables, secret rotation, and vault integration |
| dependency-auditor | CVE database | Complete audit of dependencies with CVE identification and fix suggestions |
| api-security-tester | OWASP API Security | Security tests specific to REST and GraphQL APIs |
# OWASP Security Checklist
## Description
Systematic security verification of the web application
against the OWASP Top 10 vulnerabilities. Produces an
audit report with severity, evidence, and recommendations.
## OWASP Top 10 Checklist
1. A01 - Broken Access Control
2. A02 - Cryptographic Failures
3. A03 - Injection (SQL, NoSQL, OS, LDAP)
4. A04 - Insecure Design
5. A05 - Security Misconfiguration
6. A06 - Vulnerable and Outdated Components
7. A07 - Identification and Authentication Failures
8. A08 - Software and Data Integrity Failures
9. A09 - Security Logging and Monitoring Failures
10. A10 - Server-Side Request Forgery (SSRF)
## Instructions for Each Item
1. Identify the relevant files and endpoints
2. Analyze the code for vulnerable patterns
3. Classify the severity: Critical/High/Medium/Low/Info
4. Document the evidence with code references
5. Propose the remediation with example code
6. Estimate the correction effort
## Report Format
| # | Vulnerability | Severity | File | Status |
|---|--------------|----------|------|--------|
| A01 | Access Control | ... | ... | ... |3. Creating Custom Skills Step by Step
Creating custom skills is the best way to adapt Claude Code to the specific needs of your project and team. Let us look at the complete process from design to testing.
Step 1: Identify the Need
Before creating a skill, it is essential to identify a repetitive pattern in the workflow that can be standardized. The best skills are born from tasks that are performed frequently, have clear rules, and produce predictable output.
Criteria for a Good Skill
- Repetitiveness: The task is performed multiple times a week
- Clear rules: There are defined and predictable steps
- Structured output: The result has a consistent format
- Defined domain: The skill covers a specific and bounded area
- Added value: Automation saves significant time
Step 2: Design the Skill
# Angular Standalone Component Generator
## Description
Generates standalone Angular components following the project's
conventions. Creates the component.ts file, HTML template,
CSS stylesheet, and .spec.ts test file.
## Capabilities
- Generate standalone components with signals for state management
- Create templates with the project's design system
- Generate styles following the project's CSS/SCSS conventions
- Write unit tests with TestBed and ComponentFixture
- Apply OnPush change detection
- Integrate with the router if requested
## Project Conventions
- File naming: kebab-case (user-profile.component.ts)
- Selector prefix: app- (app-user-profile)
- State management: Angular Signals (not RxJS for local state)
- Change detection: OnPush
- Styles: CSS scoped to the component
- Tests: Jasmine + TestBed
## Component Template
```typescript
import { Component, signal, input, output } from '@angular/core';
@Component({
standalone: true,
selector: 'app-[name]',
templateUrl: './[name].component.html',
styleUrls: ['./[name].component.css'],
changeDetection: ChangeDetectionStrategy.OnPush,
imports: []
})
export class [Name]Component {
// Input signals
// State signals
// Output events
// Methods
}
```
## Test Template
```typescript
describe('[Name]Component', () => {
let component: [Name]Component;
let fixture: ComponentFixture<[Name]Component>;
beforeEach(async () => {
await TestBed.configureTestingModule({
imports: [[Name]Component]
}).compileComponents();
fixture = TestBed.createComponent([Name]Component);
component = fixture.componentInstance;
fixture.detectChanges();
});
it('should create', () => {
expect(component).toBeTruthy();
});
});
```
## Constraints
- ALWAYS use standalone: true
- DO NOT use ngModule
- Prefer signal() over BehaviorSubject for local state
- Include at least 3 tests in the .spec.ts file
- Document every input/output with a JSDoc commentStep 3: Test the Skill
After creating the skill file, it is essential to test it with different prompts to verify that Claude invokes it correctly and produces consistent results.
# Test 1: Direct request
> Create a UserProfile component with name and email fields
# Verify:
# - Did it create user-profile.component.ts with standalone: true?
# - Did it use signal() for state?
# - Did it generate the .spec.ts file with at least 3 tests?
# Test 2: Request with routing
> Generate a Dashboard component that is a lazy-loaded route
# Verify:
# - Did it configure routing correctly?
# - Did it apply OnPush change detection?
# Test 3: Complex request
> Create a ProductList component with pagination, filters, and sorting
# Verify:
# - Did it manage state with signals?
# - Did it separate logic into clear methods?
# - Do the tests cover edge cases?Step 4: Iterate and Improve
The best skills are those that evolve over time. After the first tests, it is common to need to add missing constraints, clarify ambiguous instructions, and add examples for specific cases.
Improvement Checklist
- Does the skill name clearly describe its function?
- Are the instructions sufficiently detailed?
- Do the constraints cover all edge cases encountered?
- Do the examples represent the most common use cases?
- Is the output format consistent and useful?
- Does the skill handle errors correctly?
- Is the documentation clear for new team members?
4. Integrating Skills into the Workflow
Skills reach their full potential when they are organically integrated into the team's daily development workflow. Here are the most effective integration patterns.
Pattern 1: Skill Chain
Combine multiple skills in sequence for complex tasks. For example, for a new
feature you can use: api-design-first to define the API, then
tdd-workflow for tests, then angular-component-gen
for the frontend.
# Step 1: API Design
> Design the API for the push notification module
> Endpoints: GET /notifications, POST /notifications/subscribe,
> DELETE /notifications/{id}
# The api-design-first skill generates the OpenAPI specification
# Step 2: Test first
> Generate the tests for NotificationService following TDD
> Base the tests on the just-generated API specification
# The tdd-workflow skill generates the tests (Red phase)
# Step 3: Implementation
> Implement the NotificationService to make the tests pass
# The tdd-workflow skill guides the implementation (Green phase)
# Step 4: Frontend
> Create the NotificationPanel component to display notifications
# The angular-component-gen skill creates the component
# Step 5: Documentation
> Generate the documentation for the notification module
# The changelog-generator or docx-generator skill documents everythingPattern 2: Skill Gate (Skills as Quality Gates)
Use skills as quality checkpoints before critical operations. For example,
run owasp-checklist before every merge to main, or
dependency-auditor before every release.
Pattern 3: Skill Library (Team Skill Library)
Sharing skills in the project repository allows all team members
to benefit from them. The .claude/skills/ directory committed
to the repository becomes a shared knowledge library for the team.
.claude/
skills/
# Development skills
dev/
angular-component-gen.md
spring-service-gen.md
api-design-first.md
tdd-workflow.md
# Quality skills
quality/
code-review-checklist.md
owasp-checklist.md
dependency-auditor.md
performance-analyzer.md
# Documentation skills
docs/
docx-generator.md
changelog-generator.md
adr-writer.md
# Analysis skills
analysis/
csv-data-summarizer.md
log-analyzer.md
root-cause-tracing.md
# Project management skills
pm/
meeting-analytics.md
sprint-planner.md
standup-reporter.md5. Best Practices for Skill Design
After working with dozens of skills, clear patterns emerge about what makes a skill effective. Here are the best practices consolidated from the community.
Skill Best Practices
| Principle | Description | Example |
|---|---|---|
| Single Responsibility | Each skill does one thing and does it well | Separate "generate tests" from "run tests" |
| Explicit Instructions | Clear and unambiguous instructions | "Use Jasmine for tests" not "Use a testing framework" |
| Concrete Examples | At least 2-3 examples with input and expected output | Complete code templates, not pseudo-code |
| Clear Constraints | Explicit constraints on what NOT to do | "DO NOT use ngModule, only standalone: true" |
| Output Format | Defined and consistent output format | Markdown template, file structure, naming |
| Error Handling | Handling of edge cases and errors | "If the file already exists, ask for confirmation before overwriting" |
| Dependency Declaration | Declare external dependencies | "Requires: npm docx, @types/docx" |
| Versioning | Include the skill version in the file | "Version: 1.2.0 - Last updated: 2026-02-14" |
Anti-Patterns to Avoid
Common Mistakes in Skill Creation
- Skills that are too generic: "Generate code" is too vague - specify the language, framework, and conventions
- Vague instructions: "Write good code" says nothing - define concrete quality metrics
- Lack of examples: Without concrete examples, Claude interprets instructions unpredictably
- Contradictory constraints: "Use TypeScript strict" and "Don't use type annotations" are contradictory
- Monolithic skills: A skill that does everything (generates, tests, documents, deploys) is unmanageable
- No output format: Without a defined format, each execution produces different results
- Ignoring dependencies: If the skill requires an npm package, declare it explicitly
6. Advanced Skill Management
Skill Composition
Skills can be composed together to create complex workflows. The secret is to design each skill with compatible inputs and outputs, so that the output of one can feed the input of the next.
# Full Feature Pipeline
## Description
Complete orchestration for creating a new feature,
from API specification to deployment. Combines the skills: api-design-first,
tdd-workflow, angular-component-gen, and changelog-generator.
## Pipeline
### Phase 1: Design (api-design-first)
- Input: Feature requirements in natural language
- Output: Complete OpenAPI specification
- Gate: Approval of the specification by the user
### Phase 2: Backend (tdd-workflow)
- Input: OpenAPI specification from Phase 1
- Output: Service + Controller + Tests with 80%+ coverage
- Gate: All tests pass
### Phase 3: Frontend (angular-component-gen)
- Input: API endpoints from Phase 1 + data models
- Output: Standalone Angular components with tests
- Gate: Build without errors + tests pass
### Phase 4: Documentation (changelog-generator)
- Input: All files created/modified in the previous phases
- Output: Changelog entry + README update
- Gate: Documentation review
## Constraints
- Each phase requires approval before proceeding
- If a phase fails, return to the previous phase
- Maintain separate git commits for each phaseSkill Versioning
Skills evolve with the project. It is good practice to include a version header in each skill and maintain a changelog of modifications.
# Angular Component Generator
> Version: 2.1.0 | Last updated: 2026-02-14
> Changelog:
> - 2.1.0: Added support for lazy-loaded routes
> - 2.0.0: Migration from ngModule to standalone
> - 1.3.0: Added template for reactive forms
> - 1.2.0: Added OnPush change detection
> - 1.1.0: Added signal() support
> - 1.0.0: Initial release
## Description
...Automated Skill Testing
To ensure that skills continue to work correctly over time, it is possible to create automated test scripts that verify skill output against predefined expectations.
#!/bin/bash
# Automated testing of Claude Code skills
echo "=== Testing Agent Skills ==="
# Test 1: Angular Component Generator
echo "Testing: Angular Component Generator..."
OUTPUT=$(claude --print "Create a TestWidget component with a 'title' input of type string" \
--output-format json --max-iterations 5 2>&1)
if echo "$OUTPUT" | grep -q "standalone: true"; then
echo " PASS: standalone component generated"
else
echo " FAIL: standalone not found in output"
fi
if echo "$OUTPUT" | grep -q "signal\|input()"; then
echo " PASS: signal/input used"
else
echo " FAIL: signal/input not found"
fi
# Test 2: TDD Workflow
echo "Testing: TDD Workflow..."
OUTPUT=$(claude --print "Write the tests for a function calculateDiscount(price, percentage)" \
--output-format json --max-iterations 5 2>&1)
if echo "$OUTPUT" | grep -q "describe\|it("; then
echo " PASS: test structure generated"
else
echo " FAIL: test structure not found"
fi
echo "=== Test Complete ==="Conclusion
Agent Skills transform Claude Code from a generic assistant into an ecosystem of specialized competencies that adapt to the project and the team. The ten skill categories - from document generation to security, from data analysis to project management - cover the entire spectrum of software development needs.
Key Takeaways
- Skills are Markdown files in
.claude/skills/: Simple to create, version, and share within the team - 10 categories cover every need: Documents, development, data, research, writing, learning, media, health, PM, security
- Design with Single Responsibility: Each skill does one thing and does it well
- Concrete examples are essential: Claude interprets skills better with templates and expected outputs
- Composition for complex workflows: Skill chains, skill gates, and full feature pipelines
- Continuous iteration: The best skills evolve with the project and team feedback
- Sharing in the repository: Committed skills become a team knowledge library
In the next article we will explore Specialized Subagents: autonomous agents with specific roles that operate independently within Claude Code. We will see how to create language experts, DevOps specialists, and security auditors that work in synergy with the main agent.