senior-software-engineering-agent-skill

Senior Software Engineering Agent Skill

English | 简体中文

A reusable senior-level software engineering workflow for AI coding agents: requirements analysis, repository exploration, architecture and impact analysis, database/API design, implementation, testing, verification, and anti-overengineering guardrails.

Status: v0.1.0 Public Preview
Primary target: OpenAI Codex / ChatGPT Agent Skills
Project type: Instruction-first Agent Skill, with progressive reference loading

Community project: This repository is not an official OpenAI repository, product, or endorsement.

Why this Skill exists

Coding agents can write code quickly, but repository-level engineering requires more than code generation. This Skill gives an agent a disciplined workflow so it does not jump straight into implementation before understanding the requirement, existing architecture, call path, compatibility constraints, data model, error behavior, and verification needs.

The default workflow is:

Requirement understanding
        ↓
Repository exploration
        ↓
Real call-path tracing
        ↓
Architecture & impact analysis
        ↓
Minimum complete design
        ↓
Implementation
        ↓
Error / edge-case handling
        ↓
Build / tests / verification
        ↓
Git diff review
        ↓
Evidence-based result report

Core capabilities

• Requirements analysis and ambiguity classification
• Repository-first project reading and call-path tracing
• Architecture and responsibility-boundary decisions
• Database schema, SQL, indexes, transactions, migrations, and consistency
• REST API, DTO/VO, validation, pagination, error-contract, and idempotency design
• Readable implementation, naming, comments, exceptions, and logging
• Third-party API, caching, concurrency, performance, and security checks
• Unit, integration, regression, build, and static verification workflows
• Refactoring with compatibility preservation
• Git diff review before completion
• Explicit rules against speculative abstractions and unnecessary infrastructure
• Evidence-based reporting: never claim tests/builds passed unless actually executed

Installation

A Skill is a directory containing a required SKILL.md plus optional references, scripts, assets, and agents/openai.yaml. OpenAI documents local Skill discovery under repository and user-level .agents/skills locations.

User-level installation

macOS / Linux

git clone https://github.com/kunkun9494/senior-software-engineering-skill.git \
  ~/.agents/skills/senior-software-engineering

Windows PowerShell

git clone https://github.com/kunkun9494/senior-software-engineering-skill.git `
  "$HOME\.agents\skills\senior-software-engineering"

Repository-scoped installation

Run from the target repository root:

git clone https://github.com/kunkun9494/senior-software-engineering-skill.git \
  .agents/skills/senior-software-engineering

For a team repository, you can also copy the Skill directory into .agents/skills/senior-software-engineering/ and commit it directly.

Install with Codex Skill Installer

Codex also supports installing local Skills with $skill-installer, including asking it to download a Skill from another repository. Invoke $skill-installer and provide this repository URL.

Verify installation

In Codex CLI or the IDE extension:

/skills

Look for:

senior-software-engineering

If a newly installed Skill does not appear, restart Codex.

Usage

Explicit invocation

Use explicit invocation when the task is important, broad, risky, or you want to guarantee this workflow is applied.

$senior-software-engineering

Analyze the current repository before changing code.
Implement the requested feature while preserving existing behavior.
Run the relevant tests and inspect the final git diff before reporting completion.

Implicit invocation

The Skill currently allows implicit invocation:

policy:
  allow_implicit_invocation: true

When the task matches the description in SKILL.md, the host can select the Skill automatically.

Example:

Investigate the root cause of duplicate order creation in this Spring Boot repository.
Preserve the existing API contract, implement the fix, add the relevant tests, and verify the diff.

For critical repository work, explicit invocation is still recommended because it removes trigger ambiguity.

Skill structure

senior-software-engineering-skill/
├── SKILL.md
├── README.md
├── README.zh-CN.md
├── LICENSE
├── CHANGELOG.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── agents/
│   └── openai.yaml
├── references/
│   ├── engineering-standards.md
│   ├── database-and-api.md
│   ├── testing-and-verification.md
│   └── agent-execution-protocol.md
├── docs/
│   ├── USER_GUIDE_CN_EN.md
│   ├── PUBLISHING_GUIDE_CN.md
│   └── releases/
│       └── v0.1.0.md
├── examples/
│   ├── feature-development.md
│   ├── bug-fixing.md
│   ├── refactoring.md
│   ├── code-review.md
│   └── project-analysis.md
├── evals/
│   └── trigger-cases.md
├── scripts/
│   └── validate_skill.py
└── .github/
    ├── ISSUE_TEMPLATE/
    │   ├── bug_report.yml
    │   └── feature_request.yml
    ├── workflows/
    │   └── validate.yml
    └── pull_request_template.md

Progressive reference loading

SKILL.md is the orchestration layer. It tells the agent when to load deeper references instead of putting every rule into one monolithic prompt.

• references/engineering-standards.md — architecture, code quality, comments, exceptions, logs, configuration, third parties, cache, concurrency, performance, security, refactoring.
• references/database-and-api.md — database/schema/SQL/indexes/transactions/API/DTO/validation/pagination/idempotency.
• references/testing-and-verification.md — testing levels, verification order, diff review, completion criteria.
• references/agent-execution-protocol.md — detailed autonomous repository workflow for tool-enabled agents.

Examples

• Feature development
• Bug fixing
• Refactoring
• Code review
• Project analysis

Trigger evaluation

The Skill description should trigger for repository-level engineering tasks, but not for trivial syntax or unrelated questions. See evals/trigger-cases.md for positive, negative, and ambiguous trigger cases.

Validation

Run the repository validation script:

python scripts/validate_skill.py

GitHub Actions also runs this validation on pushes and pull requests.

Documentation

• Bilingual Chinese/English User Guide
• 中文 GitHub 发布指南
• v0.1.0 Release Notes
• Official References

Skill vs. project instructions

This Skill should define reusable engineering behavior. Project-specific rules belong in repository-local instructions such as AGENTS.md or project-scoped Skills.

A practical layering model is:

Reusable engineering Skill
        +
Repository/project instructions
        +
Current task prompt

This avoids hard-coding one project's Java version, framework conventions, schema rules, or business constraints into a global Skill.

Compatibility and distribution

OpenAI currently documents standalone Skills for local authoring and repository-scoped workflows in ChatGPT Desktop, Codex CLI, and the IDE extension. For broader reusable distribution, OpenAI recommends packaging Skills as Plugins. This repository remains a standalone Skill for source control, local installation, experimentation, and iteration; a future Plugin package can distribute it more broadly.

Contributing

Issues, trigger-test cases, workflow improvements, and real-world repository feedback are welcome. Read CONTRIBUTING.md before submitting changes.

Versioning

This project follows semantic versioning where practical:

• 0.x: public preview; workflow and trigger behavior may change.
• 1.x: stable public contract for Skill scope and core behavior.

See CHANGELOG.md.

License

MIT. See LICENSE.

Disclaimer

This project provides engineering workflow instructions for AI agents. It does not guarantee correctness, security, production readiness, or compatibility with every repository. Review agent-generated changes, permissions, commands, migrations, and external actions before using them in production systems.