Proposal: AI Coding Agent Skills for the Tekton Organization

[vdemeester]

Summary

Propose creating a tektoncd/skills repository to provide organization-wide AI coding agent instructions (skills) for the Tekton project. This would help contributors using AI coding assistants (Claude Code, GitHub Copilot, Cursor, Codex, etc.) be more productive when working across Tekton repositories.

Motivation

AI coding agents are increasingly used by open-source contributors. These agents work best when they have project-specific context — build commands, testing patterns, code conventions, architecture decisions, and common workflows. Without this context, agents produce generic code that doesn't match project standards.

Several communities adjacent to Tekton have already adopted this pattern:

Prior Art in Adjacent Communities

Community	Repository / File	Approach
Konflux CI	konflux-ci/skills	Dedicated org-wide skills repository with installable skills (debugging pipelines, navigating resources, etc.) via Claude Code plugin marketplace
Konflux CI	Multiple repos (build-definitions, release-service-catalog, docs, fullsend)	Per-repo CLAUDE.md files with project-specific instructions
Knative	knative/client, knative/func	Per-repo AGENTS.md with build commands, testing strategy, boundaries (always do / ask first / never do)
Kubernetes	kubernetes/kops	Per-repo CLAUDE.md
Kubernetes SIGs	kubernetes-sigs/cluster-api-provider-azure, kubernetes-sigs/cloud-provider-azure	Per-repo CLAUDE.md
Tekton (already)	tektoncd/pipelines-as-code	Both CLAUDE.md and AGENTS.md at repo root, plus .claude/skills/ directory with per-project skills (commit message formatting, Jira ticket creation)

The Two Layers

The pattern that's emerging in these communities has two complementary layers:

1. Organization-wide skills (tektoncd/skills)

Reusable skills that apply across the Tekton ecosystem:

• Tekton API conventions — CRD patterns, API versioning, feature gates
• Testing patterns — unit test conventions with gotest.tools/v3, E2E test setup
• Reconciler patterns — controller-runtime conventions used across Tekton
• Contributing workflow — PR process, review expectations, commit conventions
• Release process — release branch management, versioning
• Debugging Tekton — investigating PipelineRun failures, TaskRun debugging
• Writing TEPs — Tekton Enhancement Proposal format and process

These would be available to any contributor working on any tektoncd/* repository.

2. Per-repository instructions (AGENTS.md / CLAUDE.md)

Project-specific instructions that live in each repository:

• Build commands (make, ko, etc.)
• Test commands and test infrastructure
• Linter configuration
• Project architecture and directory layout
• Dependency management (vendoring, go.mod)
• Pre-commit hooks

Example from tektoncd/pipelines-as-code (already merged):

• AGENTS.md / CLAUDE.md at repo root with build/test/lint commands
• .claude/skills/commit-message/ — conventional commit formatting with Jira integration
• .claude/skills/jira-ticket/ — SRVKP story and bug templates with Jira markdown

Proposal

Phase 1: Per-repository AGENTS.md files

Encourage each tektoncd/* repository to add an AGENTS.md file (the tool-agnostic standard, compatible with Codex, Cursor, Copilot, Claude Code, and others) containing:

1. Project overview — what the project does, architecture
2. Build & test commands — how to build, run tests, lint
3. Code conventions — Go patterns, error handling, naming
4. Testing expectations — required test coverage, test frameworks
5. Boundaries — what an AI agent should always do, ask about first, or never do

Using AGENTS.md as the filename ensures compatibility across all major AI coding tools. Projects like pipelines-as-code that want additional Claude Code-specific features (like skills in .claude/skills/) can add those alongside AGENTS.md.

Phase 2: Organization-wide tektoncd/skills

Create a tektoncd/skills repository modeled after konflux-ci/skills containing cross-cutting skills. The repository would include:

• Skills following a standard structure (SKILL.md with YAML frontmatter)
• Test infrastructure to validate skill effectiveness
• Contributing guide for community members to add skills
• Subscription/installation mechanism for AI coding tools

Suggested Initial Skills

Skill	Description
writing-teps	TEP format, metadata, workflow, and best practices
tekton-api-conventions	CRD patterns, versioning, feature gates, API review checklist
debugging-tekton-pipelines	Systematic approach to debugging PipelineRun/TaskRun failures
tekton-testing-patterns	Unit test conventions, E2E test setup, test utilities
tekton-reconciler-patterns	Controller patterns, status management, event recording
tekton-contributing	PR workflow, review process, commit message conventions

Benefits

1. Faster onboarding — new contributors get productive faster with AI assistance that understands Tekton conventions
2. Consistent code quality — AI agents produce code that matches project standards
3. Reduced review burden — PRs from AI-assisted contributors follow conventions from the start
4. Community knowledge capture — tribal knowledge gets codified into machine-readable instructions
5. Tool agnostic — AGENTS.md works across all major AI coding tools

Open Questions

1. Should the org-wide skills repo be tektoncd/skills or tektoncd/ai-skills?
2. Should we require AGENTS.md for all tektoncd/* repos or make it opt-in?
3. What governance model for the skills repo? (Same OWNERS model as other Tekton repos?)
4. Should skills be tested (like konflux-ci/skills does with LLM-based testing)?
5. How do we handle tool-specific features (Claude Code skills, Copilot instructions) alongside the tool-agnostic AGENTS.md?

References

• AGENTS.md specification — the tool-agnostic standard
• konflux-ci/skills — Konflux's organization-wide skills repository
• tektoncd/pipelines-as-code CLAUDE.md — existing Tekton project with AI agent instructions
• Anthropic blog: Using CLAUDE.md files — best practices for project-level AI instructions
• knative/client AGENTS.md — Knative's approach
• knative/func AGENTS.md — another Knative repo with AGENTS.md