skill-authoring

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:

1. AGENTS.md
2. Existing project-level SKILL.md files
3. This skill-authoring skill
4. 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:

1. Read AGENTS.md
2. Read all existing .agents/skills/**/SKILL.md files
3. 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:

1. Pause skill generation
2. Clearly describe:
   • the conflicting rule (file and section)
   • the conflicting proposed behavior
3. Ask the developer how to proceed

You MUST present explicit choices:

1. ✅ Adjust the new skill to comply with existing rules
2. ❌ Abort skill creation
3. 📝 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