| name | skill-authoring |
| description | Create and modify repository-specific SKILL.md policy files in strict compliance with AGENTS.md and existing project skills. |
Skill authoring (AUTHORITATIVE)
This skill is responsible for creating and modifying SKILL.md files
as enforceable repository policy.
User prompts express intent only.
Governance, structure, and safety are enforced by this skill.
Scope (STRICT)
This skill MAY:
- Create new
SKILL.md files under .agents/skills/
- Modify existing
SKILL.md files under .agents/skills/
This skill MUST NOT:
- Modify source code
- Modify configuration files
- Modify dependencies
- Modify
AGENTS.md
- Modify any file outside
.agents/skills/**
Authority hierarchy (NON‑NEGOTIABLE)
All actions performed by this skill MUST respect the following order
of authority:
AGENTS.md- Existing project-level SKILL.md files
- This
skill-authoring skill
- Newly generated or modified skills
Lower levels MUST comply with higher levels at all times.
Repository-specific default (MANDATORY)
Unless the user explicitly requests a generic, reusable, or
cross-repository skill, all skills generated by this skill are
treated as repository-specific policy.
In repository-specific mode, you MAY assume and encode:
- concrete dependency versions
- repository layout and file paths
- existing tools and workflows
- project-specific enforcement rules
- integration with other project skills
You MUST NOT generalise, abstract, or omit such details by default.
Generic skills require explicit intent
To generate a generic or reusable skill, the user MUST explicitly state
that intent.
You MUST NOT infer generic intent implicitly.
In the absence of explicit instruction, repository-specific assumptions
are mandatory.
Phase 1 — Mandatory preflight (IMPLICIT)
Before creating or modifying any skill, you MUST automatically:
- Read
AGENTS.md
- Read all existing
.agents/skills/**/SKILL.md files
- Extract and treat as binding:
- forbidden actions
- version constraints
- tooling restrictions
- required workflows
- enforcement rules
- cross-skill dependencies
If a rule is ambiguous, you MUST interpret it conservatively.
The user does NOT need to request this step.
Phase 2 — Intent interpretation
Interpret the user prompt as high-level intent only.
You MUST NOT treat the prompt as permission to:
- violate existing rules
- weaken enforcement
- override policies
- bypass required workflows
Governance rules are never inferred from the prompt.
Phase 3 — Conflict detection (AUTOMATIC)
You MUST detect conflicts between the proposed skill and:
AGENTS.md- existing project SKILL.md files
- enforced workflows (e.g.
dev-workflow)
- enforcement skills (e.g. documentation or testing policies)
Conflicts include, but are not limited to:
- weakening existing rules
- introducing forbidden APIs or dependencies
- redefining “done” more weakly
- bypassing required enforcement
If no conflict exists, proceed.
If a conflict exists, proceed to Phase 4.
Phase 4 — Interactive conflict resolution (DEFAULT)
When a conflict is detected, you MUST:
- Pause skill generation
- Clearly describe:
- the conflicting rule (file and section)
- the conflicting proposed behavior
- Ask the developer how to proceed
You MUST present explicit choices:
- ✅ Adjust the new skill to comply with existing rules
- ❌ Abort skill creation
- 📝 Proceed with an explicit override of existing rules
Rules:
- You MUST NOT select an option yourself
- You MUST NOT assume intent
- You MUST NOT partially apply an override
- You MUST NOT proceed without an explicit choice
Phase 5 — Skill generation rules (CONSTRAINED)
Mandatory header
Every SKILL.md file MUST begin with:
---
name: <skill-name>
description: <single-sentence purpose>
---
Rules:
name MUST match the containing directory name- The header MUST be valid YAML
- Extra frontmatter keys are forbidden unless explicitly required
- A SKILL.md without this header is invalid
Repository-specific scope discipline
When generating repository-specific skills, you MUST:
- Encode policy, not operational procedures
- Prefer invariants (“MUST”, “MUST NOT”) over step-by-step instructions
- Avoid restating workflows governed elsewhere (e.g.
dev-workflow)
- Refer to other skills for enforcement, not for implementation details
- Keep each skill limited to exactly one responsibility
Cross-skill awareness
If the generated skill:
- affects documentation
- defines correctness or validation rules
- introduces testable guarantees
you MUST ensure it does not bypass or weaken relevant enforcement skills
(such as doc-codeblock-tests).
Such alignment MUST be encoded explicitly.
Failure semantics (IMPORTANT)
If a requested skill cannot be created without violating higher authority:
- Pause
- Explain the constraint
- Ask for guidance
Doing nothing is preferable to producing an invalid or unsafe skill.
Completion report (MANDATORY)
After successful generation or modification, report:
- the path of the affected SKILL.md file
- inherited constraints from existing rules
- declared dependencies on other skills
- any explicit overrides approved by the developer
