Agent Skill Adoption

This proposal addresses implementing Agent Skills for team knowledge sharing and workflow automation. It focuses on establishing a team Skills library and adoption process.

Prerequisites: This proposal assumes familiarity with Agent Skill concepts. See C8: Workflow and Knowledge Skillification for foundational knowledge about Agent Skills.

Problem Statement

Current State: Repetitive Context Setup

Pain Points from Team Feedback

Pain Point	Impact on AI Workflow
Repetitive prompting	Time wasted setting up same context every conversation
Inconsistent approaches	Different team members get different AI behaviors
Expertise loss	Senior developers' effective prompts not shared
Onboarding friction	New members don't know team's AI best practices
No improvement loop	Successful patterns not captured for iteration

Evidence of Missed Opportunities

Scenario 1: API Design Review

A senior developer has refined a set of API review prompts that catch common mistakes. But these prompts only exist in their conversation history. Junior developers continue making the same API design errors.

Scenario 2: Code Migration

Team spent weeks developing effective legacy code migration prompts. Project ends, prompts lost. Next migration project starts from zero.

Scenario 3: Documentation Generation

Each developer has their own way of asking Claude to write documentation. Results are inconsistent. Some follow team conventions, some don't.

Proposed Solution: Team Skills Library

Target Architecture

Reference Implementation: Superpowers

Superpowers is the recommended starting point for teams adopting agent skills. Fork it, customize it, and extend it for your team's specific needs.

Quick Start (30 minutes)

Step 1: Install Superpowers

# Clone to your Claude Code plugins directory
git clone https://github.com/obra/superpowers ~/.claude/plugins/superpowers

Step 2: Configure CLAUDE.md

Add to your project's CLAUDE.md:

You have access to superpowers skills. Use them for:
- /brainstorming - before any feature work
- /writing-plans - before implementation
- /systematic-debugging - for any bug investigation
- /tdd - for all new code
- /verification-before-completion - before claiming done

Step 3: Verify Activation

Start a Claude Code session and request a feature. The agent should automatically trigger brainstorming before writing any code. If it jumps straight to coding, check your CLAUDE.md configuration.

Step 4: First Team Skill

Once comfortable, create your first team-specific skill by copying an existing Superpowers skill and modifying it for your domain.

Customization Guide

Superpowers is designed to be forked and extended. Teams should customize it to encode their specific workflows, standards, and domain knowledge.

What to Customize:

Layer	Examples	Priority
Workflow Skills	Add your API review checklist, deployment procedures	High
Domain Skills	Encode business rules, naming conventions, architecture patterns	High
Tool Integration	Connect to your CI/CD, Jira, internal APIs	Medium
Verification Rules	Define what "done" means for your team	High

Creating Team Skills:

1. Identify Repetitive Decisions - What do senior engineers explain repeatedly? That's a skill candidate.
2. Start from Existing Skills - Copy a similar Superpowers skill as your template. The structure (triggers, steps, verification) is proven.
3. Encode in Markdown - Skills are plain Markdown files with structured sections. No special tooling required.
4. Version Control Skills - Store team skills in your repository. They evolve with your codebase.

Skill Structure:

skills/
  team/
    api-review.md        # Your API design standards
    error-handling.md    # Your error patterns
    testing-standards.md # Your coverage requirements

This directly implements Principle C4 (Workflow and Knowledge Skillification) - capturing team expertise in reusable, AI-executable form.

Alignment with Guiding Principles

Superpowers' design philosophy directly supports several whitepaper principles:

Principle	Superpowers Alignment
E1: Design-Centric Work	Brainstorming skill enforces design before code; blocks premature implementation
E4: Rigorous Verification	Verification-Before-Completion requires evidence (test output, command results) before claiming done
C1: Context Engineering	All skills begin with context gathering; brainstorming uses Socratic questioning
C4: Skillification	The entire framework is built on composable, versionable skills
G5: AI-Visible Artifacts	Skills are plain Markdown—readable by humans and AI agents alike

Workflow Alignment:

Whitepaper Workflow	Primary Superpowers Skills
Feature Development Flow	brainstorming → writing-plans → tdd → verification
API Design Flow	brainstorming → writing-plans → code-review
Bug Fix Flow	systematic-debugging → tdd → verification

Philosophy Match:

Both frameworks share a core belief: AI agents need explicit process discipline, not just capability. Left unconstrained, agents skip steps, rationalize shortcuts, and claim completion prematurely. Structured skills convert implicit team knowledge into explicit, enforceable workflows.

Team Skill Categories

1. Standards Enforcement Skills

Skills that ensure AI-generated code follows team conventions.

---
name: coding-standards
description: Enforce team coding standards and conventions. Use when writing or
  reviewing code to ensure consistency with project guidelines.
---

# Coding Standards

## Naming Conventions
- Use camelCase for variables and functions
- Use PascalCase for classes and components
- Use SCREAMING_SNAKE_CASE for constants

## File Organization
- One component per file
- Group related utilities in directories
- Co-locate tests with source code

## Import Order
1. External packages
2. Internal packages
3. Relative imports

2. Workflow Automation Skills

Skills that automate common development workflows.

---
name: commit
description: Create well-structured git commits following Conventional Commits
  specification. Use when committing code changes to ensure consistent, semantic
  commit messages that enable automated changelog generation and version bumping.
---

# Commit

Create commits following Conventional Commits format.

## Format

  [type]([scope]): [subject]

  [body]

  [footer]

## Types

- `feat` - New feature (triggers minor version bump)
- `fix` - Bug fix (triggers patch version bump)
- `docs` - Documentation only
- `refactor` - Code change without feature/fix
- `test` - Adding or updating tests
- `chore` - Maintenance tasks

## Rules

- Subject: imperative mood, max 50 chars, no period
- Body: wrap at 72 chars, explain what and why
- Footer: reference issues, note breaking changes
- Breaking change: add `!` after type or `BREAKING CHANGE:` in footer

3. Quality Assurance Skills

Skills that ensure code quality.

---
name: security-review
description: Perform security review of code changes. Use when reviewing code for
  security vulnerabilities, authentication issues, or data handling concerns.
allowed-tools: Read Grep Glob
---

# Security Review

## OWASP Top 10 Checks
1. Injection vulnerabilities
2. Broken authentication
3. Sensitive data exposure
4. XML external entities
5. Broken access control
...

## Code Patterns to Flag
- Hardcoded credentials
- SQL string concatenation
- Unvalidated user input
- Missing auth checks

Implementation Phases

Phase 1: Foundation

Goal: Establish Skills infrastructure and create first team Skills.

Deliverables:

• Create .claude/skills/ directory in team repositories
• Document Skill creation guidelines
• Create initial Skills for most common workflows
• Establish naming conventions

Phase 2: Adoption

Goal: Drive team adoption and establish improvement processes.

Deliverables:

• Conduct Skill usage training for team
• Gather usage feedback
• Iterate on Skill effectiveness
• Establish Skill maintenance process

Phase 3: Continuous Improvement

Goal: Maintain Skill quality and relevance.

Activities:

• Regular Skill review and cleanup
• New Skill proposals via PR
• Deprecate outdated Skills
• Cross-team Skill sharing

CLAUDE.md Integration

Add to project CLAUDE.md:

## Team Skills

### Available Skills
This project includes team Skills in `.claude/skills/`:

- **coding-standards** - Team code conventions and patterns
- **code-review** - Standardized review checklists
- **api-design** - REST API design standards
- **testing** - Test creation guidelines

### Using Skills
Skills are automatically discovered based on context. You don't need to explicitly
trigger them. When your request matches a Skill's description, Claude will load
and apply that Skill.

### Creating New Skills
1. Create directory at `.claude/skills/[skill-name]/`
2. Write `SKILL.md` with frontmatter (name, description)
3. Add supporting files as needed
4. Submit PR for team review

### Skill Standards
- Use gerund naming: `reviewing-code`, `designing-apis`
- Keep SKILL.md under 500 lines
- Link to supporting files for details
- Write descriptions in third person

Skill Development Workflow

From Pattern to Skill

Steps

1. Identify pattern: Notice you keep explaining the same context
2. Document pattern: Write down what you keep telling Claude
3. Create Skill: Structure as SKILL.md with proper frontmatter
4. Test: Use the Skill on similar tasks
5. Iterate: Adjust based on Claude's behavior
6. Share: Commit to repository for team access

Success Metrics

Metric	Target	How to Measure
Skill coverage	>80% common workflows	Audit team activities vs available Skills
Repetitive prompting	-70%	Survey: "How often do you repeat context?"
AI output consistency	High	Compare outputs across team members
New member onboarding	-50% time	Measure time to effective AI usage
Skill adoption rate	>90% team	Track who uses Skills in workflows
Skill contributions	1+ per member	Count PRs adding/improving Skills

Quick Start Guide

Create Your First Skill

# 1. Create skill directory
mkdir -p .claude/skills/my-first-skill

# 2. Create SKILL.md
cat > .claude/skills/my-first-skill/SKILL.md << 'EOF'
---
name: my-first-skill
description: [What it does and when to use it]
---

# My First Skill

## Instructions
[Clear, step-by-step guidance]

## Examples
[Concrete examples]
EOF

# 3. Test it
# Ask Claude something that matches your description

# 4. Commit and share
git add .claude/skills/
git commit -m "Add my-first-skill for [purpose]"
git push

Related Proposals

• Agent-Friendly Knowledge Base - Git-based knowledge for AI access
• Ubiquitous Language - Consistent terminology
• Continuous Context Cleanup - Maintaining clean context

Related Principles

• C8: Workflow and Knowledge Skillification - Core principle for Agent Skills
• G1: Single Source of Truth - Skills as canonical workflow definitions
• G2: Version-Controlled Docs - Skills in git

Related: Agent-Friendly Knowledge Base | Back to: Proposals Overview