AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) when working in this repository.

🎯 Repository Purpose

This repository is a collection of reusable Agent Skills, guardrails and policies for software engineering tasks. Skills are self-contained bundles of instructions (and optionally scripts) that extend AI agent capabilities. They can be invoked directly by users, triggered by context, or called by other skills/agents as part of a larger workflow.

Core focus areas: Test-Driven Development (TDD), code quality, security, CI/CD, and general software engineering best practices.

For the list of skills currently published in this repo and how end users install them, see README.md.

🌐 Language

Every file in this repository must be written in English. This is repository-wide and admits no per-directory exception. It covers:

• Markdown — SKILL.md, README.md, AGENTS.md, references/, guardrails/, templates and examples.
• Frontmatter — name, description and every other field.
• Code — source, scripts, identifiers, comments and log output.
• Data and fixtures — evals/*.json (including input and expected), assets/, .feature files and any sample content.

Applies equally to files an agent generates on the user's behalf. When a user writes to you in another language, answer them in that language but keep the committed files in English.

Guardrails

The following guardrails must be met:

• For security of the content this repository commits — secrets, scripts, tracked artefacts — see guardrails/code-security-checklist.md.
• For security of what a skill instructs an agent to read, run and trust, see guardrails/ai-security-checklist.md.
• For detailed guidelines on skill creation, see guardrails/skill-creation-checklist.md.

🧠 Core Principles for Skills

Every skill in this repository must adhere to these principles:

1. Single Responsibility: Each SKILL.md should cover one specific concern (e.g., "orchestrating TDD", not "TDD and deployment").
2. Progressive Disclosure: Keep the main SKILL.md under 500 lines. Put detailed reference material, examples, and long-form documentation in references/, loaded only on demand. If SKILL.md keeps growing, split its content into separate files inside references/ rather than letting it become unwieldy.
3. Script over Explanation: For repetitive or deterministic tasks, prefer executable scripts (scripts/) over long inline instructions. Scripts run outside the agent's context, saving tokens.
4. Clarity for Agents: The description in the skill's frontmatter must be specific and include trigger phrases so the agent knows exactly when to use it.
5. English Only: See Language — the requirement is repository-wide, not limited to SKILL.md and its references.
6. README.md (recommended): A README.md file that explains what the skills do and how to install them.
7. Clear License: Skills authored here are MIT, with ownership information (dariopalminio/agile-sddf). A skill vendored from a third party keeps its upstream licence instead — never relabel it. It ships that licence file inside its own directory and is listed in NOTICE. The one current instance is skills/skill-master/, which is Apache-2.0 (Copyright Anthropic, PBC).

🏗️ Repository Structure

Please follow this structure when adding or modifying skills:

.
├── skills/                     # Root directory for all skills
│   └── <skill-name>/           # kebab-case, e.g. code-backend-nestjs
│       ├── SKILL.md            # REQUIRED: Main instruction file
│       ├── scripts/            # (Optional) Executable scripts
│       ├── references/         # (Optional) Supporting docs (loaded on demand)
│       ├── assets/             # (Optional) Static files used by the skill
│       └── lib/                # (Optional) Shared code for scripts
├── template/
│   └── SKILL.md                # Base template for new skills
├── spec/
│   └── agent-skills-spec.md    # Agent Skills specification
├── README.md                   # Documentation for end users
└── AGENTS.md                   # This file (documentation for agents)

✍️ Skill Creation Checklist

When creating a new skill, follow this checklist:

1. Create the directory: skills/<skill-name>/ (use kebab-case).
2. Create SKILL.md: Start with the required YAML frontmatter:

   ---
   name: my-skill-name
   description: Clear description of what it does and when to use it.
   ---

   Field	Required	Description
   name	Yes	Unique skill identifier (lowercase, hyphens for spaces)
   description	Yes	Full description of what it does and when to use it, with trigger phrases
   metadata.version	No (Vercel extension)	Skill version, e.g. "1.2.0"

3. Name name: Lowercase, with hyphens, maximum 64 characters.
4. Description description: In English, maximum 1024 characters, describing what it does and when to use it.
5. License license: MIT for a skill authored here. A vendored skill declares its upstream licence instead, or omits the field when that licence travels as a file beside it — which is what skill-master does.
6. Write concise instructions: Focus on the core workflow. Keep it actionable.
7. Add references (if needed): Move detailed guides, rules, or long examples to references/.
8. Add scripts (if needed): For any deterministic actions.
9. Validate: Ensure the skill works as expected.
10. Skill worker: Ensure that the skill is of type worker, meaning it does not invoke sub-agents nor is it an orchestrator skill. The skill remains autonomous and atomic.

Naming Conventions

Gerund form (verb + -ing, e.g. testing-react-components) is an optional community convention some skill names follow.

🧪 Quality and Testing Standards

• Validate Your Skills: Use tools like skillgrade to evaluate skill quality and prevent regressions.
• Script Requirements:
  • Bash: Use #!/bin/bash and set -e.
  • Node.js: Use #!/usr/bin/env node and the .mjs extension.
  • Output: Send status messages to stderr and machine-readable output (e.g., JSON) to stdout.
  • Cleanup: Include a trap for cleaning up temporary files.

🤝 Contributing and Collaboration

When contributing to this repository:

• Propose changes: For significant changes, open an issue or pull request for discussion.
• Maintain consistency: New skills should mirror the style and structure of existing ones.
• Keep it simple: Avoid over-engineering. The goal is to make skills easy to understand and use.

🔗 Useful References

• Anthropic Skills Repository for examples
• Best Practices for Skills
• Best Practices for Skill Testing