Skip to main content

Integrate Agent Skills for AI-Assisted Development

Context and Problem Statement​

AI coding assistants like GitHub Copilot provide general programming assistance but lack project-specific architectural context and patterns. As the ShareThrift project grows in complexity with DDD architecture, microservices patterns, event sourcing, CQRS, and enterprise patterns, we need to provide AI agents with structured understanding of our architecture and best practices.

Agent Skills provide structured, discoverable context in a standardized format that AI agents can consume effectively. The Skills CLI enables easy installation, updating, and management of both community-maintained and custom skills.

Decision Drivers​

  • Contextual AI assistance: Enable AI agents to understand project-specific architecture and patterns
  • Pattern consistency: Ensure AI-generated code follows established DDD, CQRS, and enterprise patterns
  • Technology expertise: Provide AI agents with Apollo GraphQL, Turborepo, React 19, and Azure best practices
  • Maintainability: Use industry-standard skill format that's easy to update and extend
  • Team alignment: Share common understanding of patterns across human developers and AI agents
  • Version control: Track skills changes alongside code changes in git

Implementation Strategy​

1. Skills CLI Integration​

Installation and Management:

# Install skills via pnpm (preferred over npx)
pnpm dlx skills add <repository> --skill <skill-name>

# List installed skills
pnpm dlx skills list

# Update all skills to latest versions
pnpm dlx skills update

# Remove a skill
pnpm dlx skills remove <skill-name>

When given options, select symlink, project wide for the installation, and github copilot and the only agent.

2. Installed Skills​

Technology-Specific Skills (from public repositories):

  1. apollo-client (from apollographql/skills)

    • Apollo Client 4.x best practices
    • Cache configuration and optimization
    • Suspense hooks and modern React patterns
    • Data masking and component boundaries
    • Source: Apollo GraphQL official skills

  2. apollo-server (from apollographql/skills)

    • Apollo Server 4.x patterns
    • DataLoader for N+1 query prevention
    • Error handling and logging standards
    • Context management and authentication
    • Source: Apollo GraphQL official skills

  3. graphql-operations (from apollographql/skills)

    • GraphQL query/mutation best practices
    • Fragment composition
    • Operation naming conventions
    • Source: Apollo GraphQL official skills

  4. graphql-schema (from apollographql/skills)

    • GraphQL schema design patterns
    • Type system best practices
    • Schema federation (if applicable)
    • Source: Apollo GraphQL official skills

  5. turborepo (from vercel/turborepo)

    • Turborepo task orchestration
    • Caching strategies
    • Pipeline dependencies
    • Workspace configuration
    • Source: Vercel/Turborepo official skills

  6. vercel-react-best-practices (from vercel-labs/agent-skills)

    • React 19 patterns and best practices
    • Performance optimization
    • Component composition
    • Hook patterns
    • Source: Vercel official skills

Enterprise Architecture Skills (from specialized repositories):

  1. enterprise-architecture-patterns (from manutej/luxor-claude-marketplace)
    • Domain-Driven Design (Strategic & Tactical patterns)
    • Event Sourcing with snapshots
    • CQRS (Command Query Responsibility Segregation)
    • Saga Pattern (Orchestration & Choreography)
    • API Gateway & Backend-for-Frontend (BFF) patterns
    • Service Mesh configuration
    • Resilience Patterns (Circuit Breaker, Retry, Bulkhead)
    • Distributed systems design
    • Source: Community-maintained enterprise patterns skill (2457 lines)

Skill File Format: Each skill contains a SKILL.md file with:

  • Metadata header: Name, description, tags, tier
  • When to use: Contextual guidance for AI agents
  • Patterns and examples: Concrete code examples
  • Best practices: Dos and don'ts
  • Common pitfalls: Anti-patterns to avoid

3. Skills Update Workflow​

Limitation: The pnpm dlx skills update command has limitations:

  • Updates modified files in skills
  • Does NOT restore deleted files
  • Performs diff/comparison, not full restoration

To restore corrupted skills:

# Remove and reinstall
pnpm dlx skills remove <skill-name>
pnpm dlx skills add <repository> --skill <skill-name>

Update cadence:

  • Run pnpm dlx skills update weekly or when skills repositories announce updates
  • Review skill changes before committing updates
  • Test AI agent behavior after major skill updates

4. Custom Skills (Future)​

For ShareThrift-specific patterns not available in public repositories:

  • Domain models for ShareThrift business logic
  • Cellix framework patterns and conventions
  • Azure Functions + DDD integration patterns
  • Custom bounded context structures

Creating custom skills:

# Add custom skill from ShareThrift repository
pnpm dlx skills add simnova/sharethrift --skill sharethrift-domain-patterns

Consequences​

Positive​

  • Enhanced AI understanding of DDD, CQRS, event sourcing, and enterprise patterns
  • AI-generated code follows established architectural patterns consistently
  • AI agents understand Apollo GraphQL, Turborepo, React 19 best practices
  • Reduced anti-patterns (N+1 queries, cache anti-patterns, Turborepo bypasses)
  • Faster development with AI agents suggesting architecture-aligned solutions
  • Skills serve as living documentation for both AI and human developers
  • Benefit from Apollo, Vercel, and community-maintained skills
  • Skills CLI simplifies installation and updates
  • Skills tracked in git alongside code
  • Same skills available locally and in CI/CD pipelines

Negative​

  • Team must maintain skills directory and keep skills updated periodically
  • Developers need to understand skills concept and CLI commands
  • Skills must be updated periodically to stay current with upstream changes
  • skills update doesn't restore deleted files, requires full reinstall
  • Skills CLI doesn't generate version lock files (unlike npm/pnpm)

More Information​

Validation​

Local development validation criteria:

  • AI agents reference skills when suggesting code changes
  • Code suggestions align with DDD patterns, Apollo best practices, and Turborepo conventions
  • AI agents identify anti-patterns (N+1 queries, prebuild scripts, manual cache updates)
  • Skills content is visible when asking AI agents about architectural patterns

Installed Skills Sources​

  1. Apollo Skills: https://github.com/apollographql/skills

    • apollo-client, apollo-server, graphql-operations, graphql-schema

  2. Turborepo Skills: https://github.com/vercel/turborepo

    • turborepo

  3. Vercel Skills: https://github.com/vercel-labs/agent-skills

    • vercel-react-best-practices

  4. Enterprise Architecture Skills: https://github.com/manutej/luxor-claude-marketplace

    • enterprise-architecture-patterns (comprehensive DDD, CQRS, Saga, Event Sourcing guide)

Skills CLI Documentation​

  • Skills CLI GitHub: https://github.com/skills-sh/skills
  • Skills Format: Skills are markdown files with YAML frontmatter
  • Installation: Via npx or pnpm dlx (pnpm dlx preferred for this project)

Usage Examples​

Installing a skill:

pnpm dlx skills add apollographql/skills --skill apollo-client

Viewing installed skills:

pnpm dlx skills list

Updating all skills:

pnpm dlx skills update

Removing a skill:

pnpm dlx skills remove apollo-client

Future Considerations​

  • Custom ShareThrift skills: Create custom skills for domain-specific patterns:

    • ShareThrift bounded contexts (Listings, Reservations, Members, IAM)
    • Cellix framework conventions
    • Azure Functions + DDD integration patterns

  • Lock file consideration: Monitor Skills CLI for lock file feature (similar to package-lock.json)

    • Would enable reproducible AI context across environments
    • Currently not supported by Skills CLI