Open-Sourcing agent-skills — Spec-Driven Development with AI Agents
Introduction
As AI-powered development becomes the norm, the quality of how we instruct our agents is becoming a decisive factor in software quality. The question is no longer "can AI write code?" but "how do we tell AI what to build?"
We have open-sourced agent-skills, a skill set that enables AI agents to generate specifications, validate them, and convert them into GitHub Issues — all in a single workflow.
This article explains what Agent Skills are, introduces the concept of Spec-Driven Development, and walks through how to use agent-skills in practice.
Key Takeaways
- Agent Skills are reusable plugins that standardize how AI agents perform complex tasks
- Spec-Driven Development puts structured specs before code, with AI handling generation and validation
- agent-skills provides three skills: spec-generator, spec-inspect, and spec-to-issue
What Are Agent Skills?
Agent Skills are a plugin mechanism that adds specific capabilities to AI coding agents (Claude Code, Cursor, Codex, Gemini CLI, etc.). Defined in the SKILL.md format, they describe the procedures, rules, and output formats an agent should follow for a given task.
skills/
├── spec-generator/
│ └── SKILL.md # Skill definition
├── spec-inspect/
│ └── SKILL.md
└── spec-to-issue/
└── SKILL.md
Traditionally, instructing agents relied on ad-hoc prompts. With Skills, you can standardize procedures in a reusable format. Share them across your team, and everyone gets consistent output quality regardless of who runs the agent.
Agent Skills are agent-agnostic. As long as the agent supports the SKILL.md format, it works with Claude Code, Cursor, Gemini CLI, or any other compatible tool.
What Is Spec-Driven Development?
Spec-Driven Development is a methodology where you create structured specifications before writing code, and use those specs to drive the implementation process.
The key difference from traditional waterfall is that AI agents handle spec generation, validation, and task decomposition. Humans focus on review and decision-making.
Conversation / Prompt
↓
[spec-generator] Generate requirements + design doc + task list
↓
[spec-inspect] Validate spec quality, detect contradictions
↓
[spec-to-issue] Auto-generate GitHub Issues
↓
Implementation phase
There are three critical benefits to this workflow:
1. Specifications become structured
A .specs/{project}/ directory is generated containing requirement.md (requirements), design.md (technical design), and tasks.md (task breakdown). Instead of scattered notes or verbal agreements, you get Git-trackable, versioned specifications.
2. Quality is validated automatically
The system detects contradictions, ambiguous expressions, and missing required sections. Issues like "requirement ID references a non-existent item" or "non-functional requirements are undefined" are caught before implementation begins.
3. Specs convert directly to Issues
Structured GitHub Issues with checklists are auto-generated from the specs. This minimizes the gap between specification and implementation, preventing misalignment on what needs to be built.
Spec-Driven Development is not a silver bullet. Spec quality depends on input quality — vague prompts produce vague specs. The initial conversation matters.
How to Install
agent-skills can be installed with a single npx skills command.
# Install all skills at once
npx skills add anyoneanderson/agent-skills -g -y
# Install individually
npx skills add anyoneanderson/agent-skills --skill spec-generator -g -y
npx skills add anyoneanderson/agent-skills --skill spec-inspect -g -y
npx skills add anyoneanderson/agent-skills --skill spec-to-issue -g -yThe -g flag installs globally (available across all projects), and -y skips confirmation prompts. Remove -g for project-specific installation.
After installation, the skills appear in your agent's skill list.
How to Use
spec-generator — Generate Specifications
Describe your requirements in natural language, and structured specifications are generated automatically.
> Create full spec for a user authentication system
> Generate requirements for an e-commerce platform
> 要件定義を作って：リアルタイムチャットアプリ
Generated specs:
.specs/user-auth/
├── requirement.md # Functional & non-functional requirements
├── design.md # Architecture, class design, API design
└── tasks.md # Prioritized implementation task list
In dialogue mode, the agent asks clarifying questions to refine requirements interactively.
spec-inspect — Validate Specifications
Automatically checks the quality of generated specifications.
> Inspect specs for user-auth
> Run spec-inspect on the auth feature
Examples of detected issues:
- Requirement ID references a non-existent item
- Non-functional requirements (performance, security) are undefined
- Contradictions between design doc and task list
- Ambiguous expressions ("as appropriate", "if necessary", etc.)
Results are output as inspection-report.md.
spec-to-issue — Auto-Generate GitHub Issues
Creates GitHub Issues with implementation tasks from validated specifications.
> Create issue from spec
> Turn this into a GitHub issue
Issues include checklists, links to spec documents, and completion criteria.
FAQ
Q. Which AI agents are supported?
A. Any agent that supports the SKILL.md format. This includes Claude Code, Cursor, Codex, and Gemini CLI. The skills are agent-agnostic by design.
Q. Can I customize the generated specs?
A. Yes. The skills use interactive dialogue to refine requirements. You can also edit the generated .md files directly — they are standard Markdown tracked in Git.
Q. Does this replace traditional project management?
A. No. Spec-Driven Development complements existing workflows. It automates the spec creation and validation steps, but human review and decision-making remain essential.
Q. Is this suitable for large enterprise projects?
A. The skills are designed for projects of any size. For large projects, the structured output (requirement IDs, traceability matrix, dependency graphs) provides the rigor needed for enterprise development.
Summary
agent-skills is an open-source skill set that enables Spec-Driven Development with AI agents.
- spec-generator: Generates structured specifications from natural language conversations
- spec-inspect: Automatically validates spec quality and detects issues
- spec-to-issue: Converts specs into GitHub Issues with checklists
"Have AI write your specs before having AI write your code." We believe this approach fundamentally improves development quality.
At ZenChAIne, we use this workflow daily across our AI and blockchain projects, and we are committed to pushing the boundaries of AI-driven software development.